From 729beb72302a1e10bbc06ffa0a7d8a5b59672fcf Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 11 Jan 2019 18:23:19 +0100 Subject: Use a clearer name for state directory and improve documentation --- lilv/lilv.h | 43 +++++++++++++++++++++++-------------------- src/state.c | 26 +++++++++++++------------- test/lilv_test.c | 28 ++++++++++++++-------------- 3 files changed, 50 insertions(+), 47 deletions(-) diff --git a/lilv/lilv.h b/lilv/lilv.h index 589da8c..1ed219c 100644 --- a/lilv/lilv.h +++ b/lilv/lilv.h @@ -1278,28 +1278,31 @@ typedef const void* (*LilvGetPortValueFunc)(const char* port_symbol, @param map The map to use for mapping URIs in state. - @param file_dir Directory of files created by the plugin earlier (or NULL). - This is for hosts that support file creation at any time with state + @param scratch_dir Directory of files created by the plugin earlier, or + NULL. This is for hosts that support file creation at any time with state state:makePath. These files will be copied as necessary to `copy_dir` and not be referred to directly in state (a temporary directory is appropriate). - @param copy_dir Directory of copies of files in `file_dir` (or NULL). This - directory will have the same structure as `file_dir` but with possibly - modified file names to distinguish different revisions. If you only care - about saving one state snapshot, it can be the same as `save_dir`. Plugin - state will refer to files in this directory. - - @param link_dir Directory of links to external files (or NULL). A link will + @param copy_dir Directory of copies of files in `scratch_dir`, or NULL. + This directory will have the same structure as `scratch_dir` but with + possibly modified file names to distinguish revisions. This allows the + saved state to contain the exact contents of the scratch file at save time, + so that the state is not ruined if the file is later modified (for example, + by the plugin continuing to record). This can be the same as `save_dir` to + create a copy in the state bundle, but can also be a separate directory + which allows multiple state snapshots to share a single copy if the file has + not changed. + + @param link_dir Directory of links to external files, or NULL. A link will be made in this directory to any external files referred to in plugin state. In turn, links will be created in the save directory to these links (e.g. save_dir/file => link_dir/file => /foo/bar/file). This allows many state - snapshots to share a single link to an external file, so archival - (e.g. with tar -h) will not create several copies of the file. If this is - not required, it can be the same as save_dir. + snapshots to share a single link to an external file, so archival (e.g. with + tar -h) will not create several copies of the file. If this is not + required, it can be the same as `save_dir`. @param save_dir Directory of files created by plugin during save (or NULL). - If the state will be saved, this should be the bundle directory later passed - to lilv_state_save(). + This is typically the bundle directory later passed to lilv_state_save(). @param get_value Function to get port values (or NULL). If NULL, the returned state will not represent port values. This should only be NULL in @@ -1324,12 +1327,12 @@ typedef const void* (*LilvGetPortValueFunc)(const char* port_symbol, saving an instances state many times while avoiding any duplication of data. If supported (via state:makePath passed to LV2_Descriptor::instantiate()), - `file_dir` should be the directory where any files created by the plugin + `scratch_dir` should be the directory where any files created by the plugin (not during save time, e.g. during instantiation) are stored. These files - will be copied to preserve their state at this time.plugin-created files are stored. - Lilv will assume any files within this directory (recursively) are created - by the plugin and all other files are immutable. Note that this function - does not save the state, use lilv_state_save() for that. + will be copied to preserve their state at this time.plugin-created files are + stored. Lilv will assume any files within this directory (recursively) are + created by the plugin and all other files are immutable. Note that this + function does not save the state, use lilv_state_save() for that. See state.h from the LV2 State extension for details on the `flags` and `features` parameters. @@ -1338,7 +1341,7 @@ LILV_API LilvState* lilv_state_new_from_instance(const LilvPlugin* plugin, LilvInstance* instance, LV2_URID_Map* map, - const char* file_dir, + const char* scratch_dir, const char* copy_dir, const char* link_dir, const char* save_dir, diff --git a/src/state.c b/src/state.c index 0b14f25..4fc7e43 100644 --- a/src/state.c +++ b/src/state.c @@ -58,7 +58,7 @@ struct LilvStateImpl { LilvNode* plugin_uri; ///< Plugin URI LilvNode* uri; ///< State/preset URI char* dir; ///< Save directory (if saved) - char* file_dir; ///< Directory for files created by plugin + char* scratch_dir; ///< Directory for files created by plugin char* copy_dir; ///< Directory for snapshots of external files char* link_dir; ///< Directory for links to external files char* label; ///< State/Preset label @@ -232,9 +232,9 @@ abstract_path(LV2_State_Map_Path_Handle handle, } else if (lilv_path_is_child(real_path, state->dir)) { // File in state directory (loaded, or created by plugin during save) path = lilv_path_relative_to(real_path, state->dir); - } else if (lilv_path_is_child(real_path, state->file_dir)) { + } else if (lilv_path_is_child(real_path, state->scratch_dir)) { // File created by plugin earlier - path = lilv_path_relative_to(real_path, state->file_dir); + path = lilv_path_relative_to(real_path, state->scratch_dir); if (state->copy_dir) { int st = lilv_mkdir_p(state->copy_dir); if (st) { @@ -347,7 +347,7 @@ LILV_API LilvState* lilv_state_new_from_instance(const LilvPlugin* plugin, LilvInstance* instance, LV2_URID_Map* map, - const char* file_dir, + const char* scratch_dir, const char* copy_dir, const char* link_dir, const char* save_dir, @@ -359,14 +359,14 @@ lilv_state_new_from_instance(const LilvPlugin* plugin, const LV2_Feature** sfeatures = NULL; LilvWorld* const world = plugin->world; LilvState* const state = (LilvState*)calloc(1, sizeof(LilvState)); - state->plugin_uri = lilv_node_duplicate(lilv_plugin_get_uri(plugin)); - state->abs2rel = zix_tree_new(false, abs_cmp, NULL, path_rel_free); - state->rel2abs = zix_tree_new(false, rel_cmp, NULL, NULL); - state->file_dir = file_dir ? absolute_dir(file_dir) : NULL; - state->copy_dir = copy_dir ? absolute_dir(copy_dir) : NULL; - state->link_dir = link_dir ? absolute_dir(link_dir) : NULL; - state->dir = save_dir ? absolute_dir(save_dir) : NULL; - state->atom_Path = map->map(map->handle, LV2_ATOM__Path); + state->plugin_uri = lilv_node_duplicate(lilv_plugin_get_uri(plugin)); + state->abs2rel = zix_tree_new(false, abs_cmp, NULL, path_rel_free); + state->rel2abs = zix_tree_new(false, rel_cmp, NULL, NULL); + state->scratch_dir = scratch_dir ? absolute_dir(scratch_dir) : NULL; + state->copy_dir = copy_dir ? absolute_dir(copy_dir) : NULL; + state->link_dir = link_dir ? absolute_dir(link_dir) : NULL; + state->dir = save_dir ? absolute_dir(save_dir) : NULL; + state->atom_Path = map->map(map->handle, LV2_ATOM__Path); LV2_State_Map_Path pmap = { state, abstract_path, absolute_path }; LV2_Feature pmap_feature = { LV2_STATE__mapPath, &pmap }; @@ -1257,7 +1257,7 @@ lilv_state_free(LilvState* state) free(state->values); free(state->label); free(state->dir); - free(state->file_dir); + free(state->scratch_dir); free(state->copy_dir); free(state->link_dir); free(state); diff --git a/test/lilv_test.c b/test/lilv_test.c index 5d5b5eb..d91e3f9 100644 --- a/test/lilv_test.c +++ b/test/lilv_test.c @@ -1610,21 +1610,21 @@ test_state(void) temp_dir = lilv_realpath("temp"); - const char* file_dir = NULL; - char* copy_dir = NULL; - char* link_dir = NULL; - char* save_dir = NULL; + const char* scratch_dir = NULL; + char* copy_dir = NULL; + char* link_dir = NULL; + char* save_dir = NULL; // Get instance state state LilvState* state = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, save_dir, + scratch_dir, copy_dir, link_dir, save_dir, get_port_value, world, 0, NULL); // Get another instance state LilvState* state2 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, save_dir, + scratch_dir, copy_dir, link_dir, save_dir, get_port_value, world, 0, NULL); // Ensure they are equal @@ -1672,7 +1672,7 @@ test_state(void) lilv_instance_run(instance, 1); LilvState* state3 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, save_dir, + scratch_dir, copy_dir, link_dir, save_dir, get_port_value, world, 0, NULL); TEST_ASSERT(!lilv_state_equals(state2, state3)); // num_runs changed @@ -1682,7 +1682,7 @@ test_state(void) // Take a new snapshot and ensure it matches the set state LilvState* state4 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, save_dir, + scratch_dir, copy_dir, link_dir, save_dir, get_port_value, world, 0, NULL); TEST_ASSERT(lilv_state_equals(state2, state4)); @@ -1757,7 +1757,7 @@ test_state(void) // Make directories and test files support mkdir("temp", 0700); - file_dir = temp_dir; + scratch_dir = temp_dir; mkdir("files", 0700); copy_dir = lilv_realpath("files"); mkdir("links", 0700); @@ -1787,13 +1787,13 @@ test_state(void) // Get instance state state LilvState* fstate = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, "state/fstate.lv2", + scratch_dir, copy_dir, link_dir, "state/fstate.lv2", get_port_value, world, 0, ffeatures); // Get another instance state LilvState* fstate2 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, "state/fstate2.lv2", + scratch_dir, copy_dir, link_dir, "state/fstate2.lv2", get_port_value, world, 0, ffeatures); // Should be identical @@ -1805,7 +1805,7 @@ test_state(void) // Get yet another instance state LilvState* fstate3 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, "state/fstate3.lv2", + scratch_dir, copy_dir, link_dir, "state/fstate3.lv2", get_port_value, world, 0, ffeatures); // Should be different @@ -1827,7 +1827,7 @@ test_state(void) // Take a new snapshot and ensure it matches LilvState* fstate5 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, "state/fstate5.lv2", + scratch_dir, copy_dir, link_dir, "state/fstate5.lv2", get_port_value, world, 0, ffeatures); TEST_ASSERT(lilv_state_equals(fstate3, fstate5)); @@ -1847,7 +1847,7 @@ test_state(void) // Take a new snapshot LilvState* fstate7 = lilv_state_new_from_instance( plugin, instance, &map, - file_dir, copy_dir, link_dir, "state/fstate7.lv2", + scratch_dir, copy_dir, link_dir, "state/fstate7.lv2", get_port_value, world, 0, ffeatures); TEST_ASSERT(!lilv_state_equals(fstate6, fstate7)); -- cgit v1.2.1