diff options
| -rw-r--r-- | ext/persist.lv2/persist.h | 298 | ||||
| -rw-r--r-- | ext/persist.lv2/persist.ttl | 4 |
2 files changed, 156 insertions, 146 deletions
diff --git a/ext/persist.lv2/persist.h b/ext/persist.lv2/persist.h index 2ac4880..0a8f4f0 100644 --- a/ext/persist.lv2/persist.h +++ b/ext/persist.lv2/persist.h @@ -1,24 +1,26 @@ -/* lv2_persist.h - C header file for the LV2 Persist extension. - * Copyright (C) 2010 Leonard Ritter <paniq@paniq.org> - * - * This header is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as published - * by the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This header is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public - * License for more details. - * - * You should have received a copy of the GNU Lesser General Public License - * along with this header; if not, write to the Free Software Foundation, - * Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA - */ +/* + Copyright (C) 2010-2011 David Robillard <http://drobilla.net> + Copyright (C) 2010 Leonard Ritter <paniq@paniq.org> + + This header is free software; you can redistribute it and/or modify it + under the terms of the GNU Lesser General Public License as published + by the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This header is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public + License for more details. + + You should have received a copy of the GNU Lesser General Public License + along with this header; if not, write to the Free Software Foundation, + Inc., 59 Temple Place, Suite 330, Boston, MA 01222-1307 USA +*/ -/** @file - * C header for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>. - */ +/** + @file + C API for the LV2 Persist extension <http://lv2plug.in/ns/ext/persist>. +*/ #ifndef LV2_PERSIST_H #define LV2_PERSIST_H @@ -29,32 +31,34 @@ extern "C" { #define LV2_PERSIST_URI "http://lv2plug.in/ns/ext/persist" -/** A host-provided function to store a value under a given key. - * @param callback_data Must be the callback_data passed to LV2_Persist.save(). - * @param key The URI key (predicate) under which the value is to be stored. - * @param value Pointer to the value (object) to be stored. - * @param size The size of the data at @a value in bytes. - * @param type The type of @a value, as a URI mapped to an integer. - * - * The host passes a callback of this type to LV2_Persist.save(). This - * callback is called repeatedly by the plugin within LV2_Persist.save() to - * store all the key/value records that describe its current state. - * - * Unless @a type is 0, @a value is guaranteed to be POD (i.e. a region - * of memory that does not contain pointers and can safely be copied - * and persisted indefinitely with a simple memcpy). If @a type is 0, - * then @a value is a reference, as defined by the LV2 Atom extension - * <http://lv2plug.in/ns/ext/atom/>. Hosts are not required to support - * references: a plugin MUST NOT expect a host to persist references unless - * the host supports the feature <http://lv2plug.in/ns/ext/atom#blobSupport>. - * Plugins SHOULD express their state entirely with POD values. - * - * Note that @a size MUST be > 0, and @a value MUST point to a valid region of - * memory @a size bytes long (this is required to make restore unambiguous). - * - * The plugin MUST NOT attempt to use this function outside of the - * LV2_Persist.restore() context. - */ +/** + A host-provided function to store a value under a given key. + @param callback_data Must be the callback_data passed to LV2_Persist.save(). + @param key The URI key (predicate) under which the value is to be stored. + @param value Pointer to the value (object) to be stored. + @param size The size of the data at @a value in bytes. + @param type The type of @a value, as a URI mapped to an integer. + + The host passes a callback of this type to LV2_Persist.save(). + This callback is called repeatedly by the plugin within + LV2_Persist.save() to store all the key/value records that describe + its current state. + + Unless @a type is 0, @a value is guaranteed to be POD (i.e. a region + of memory that does not contain pointers and can safely be copied + and persisted indefinitely with a simple memcpy). If @a type is 0, + then @a value is a reference, as defined by the LV2 Atom extension + <http://lv2plug.in/ns/ext/atom/>. Hosts are not required to support + references: a plugin MUST NOT expect a host to persist references unless + the host supports the feature <http://lv2plug.in/ns/ext/atom#blobSupport>. + Plugins SHOULD express their state entirely with POD values. + + Note that @a size MUST be > 0, and @a value MUST point to a valid region of + memory @a size bytes long (this is required to make restore unambiguous). + + The plugin MUST NOT attempt to use this function outside of the + LV2_Persist.restore() context. +*/ typedef void (*LV2_Persist_Store_Function)( void* callback_data, const char* key, @@ -62,116 +66,122 @@ typedef void (*LV2_Persist_Store_Function)( size_t size, uint32_t type); -/** A host-provided function to retrieve a value under a given key. - * @param callback_data Must be the callback_data passed to LV2_Persist.restore(). - * @param key The URI key (predicate) under which a value has been stored. - * @param size (Output) If non-NULL, set to the size of the restored value. - * @param type (Output) If non-NULL, set to the type of the restored value. - * @return A pointer to the restored value (object), or NULL if no value - * has been stored under @a key. - * - * A callback of this type is passed by the host to LV2_Persist.restore(). This - * callback is called repeatedly by the plugin within LV2_Persist.restore() to - * retrieve the values of any keys it requires to restore its state. - * - * The returned value MUST remain valid until LV2_Persist.restore() returns. - * - * The plugin MUST NOT attempt to use this function, or any value returned from - * it, outside of the LV2_Persist.restore() context. Returned values MAY be - * copied for later use if necessary. - */ +/** + A host-provided function to retrieve a value under a given key. + @param callback_data Must be the callback_data passed to LV2_Persist.restore(). + @param key The URI key (predicate) under which a value has been stored. + @param size (Output) If non-NULL, set to the size of the restored value. + @param type (Output) If non-NULL, set to the type of the restored value. + @return A pointer to the restored value (object), or NULL if no value + has been stored under @a key. + + A callback of this type is passed by the host to LV2_Persist.restore(). This + callback is called repeatedly by the plugin within LV2_Persist.restore() to + retrieve the values of any keys it requires to restore its state. + + The returned value MUST remain valid until LV2_Persist.restore() returns. + + The plugin MUST NOT attempt to use this function, or any value returned from + it, outside of the LV2_Persist.restore() context. Returned values MAY be + copied for later use if necessary. +*/ typedef const void* (*LV2_Persist_Retrieve_Function)( void* callback_data, const char* key, size_t* size, uint32_t* type); -/** When the plugin's extension_data is called with argument LV2_PERSIST_URI, - * the plugin MUST return an LV2_Persist structure, which remains valid for - * the lifetime of the plugin. - * - * The host can use the contained function pointers to save and restore the - * state of a plugin instance at any time (provided the threading restrictions - * for the given function are met). - * - * The typical use case is to save the plugin's state when a project is - * saved, and to restore the state when a project has been loaded. Other - * uses are possible (e.g. cloning plugin instances or taking a snapshot - * of plugin state). - * - * Stored data is only guaranteed to be compatible between instances of plugins - * with the same URI (i.e. if a change to a plugin would cause a fatal error - * when restoring state saved by a previous version of that plugin, the plugin - * URI must change just as it must when a plugin's ports change). Plugin - * authors should consider this possibility, and always store sensible data - * with meaningful types to avoid such compatibility issues in the future. - */ +/** + Persist Extension Data. + + When the plugin's extension_data is called with argument LV2_PERSIST_URI, + the plugin MUST return an LV2_Persist structure, which remains valid for + the lifetime of the plugin. + + The host can use the contained function pointers to save and restore the + state of a plugin instance at any time (provided the threading restrictions + for the given function are met). + + The typical use case is to save the plugin's state when a project is + saved, and to restore the state when a project has been loaded. Other + uses are possible (e.g. cloning plugin instances or taking a snapshot + of plugin state). + + Stored data is only guaranteed to be compatible between instances of plugins + with the same URI (i.e. if a change to a plugin would cause a fatal error + when restoring state saved by a previous version of that plugin, the plugin + URI must change just as it must when a plugin's ports change). Plugin + authors should consider this possibility, and always store sensible data + with meaningful types to avoid such compatibility issues in the future. +*/ typedef struct _LV2_Persist { - /** Save plugin state using a host-provided @a store callback. - * - * @param instance The instance handle of the plugin. - * @param store The host-provided store callback. - * @param callback_data An opaque pointer to host data, e.g. the map or - * file where the values are to be stored. If @a store is called, - * this MUST be passed as its callback_data parameter. - * - * The plugin is expected to store everything necessary to completely - * restore its state later (possibly much later, in a different - * process, on a completely different machine, etc.) - * - * The @a callback_data pointer and @a store function MUST NOT be - * used beyond the scope of save(). - * - * This function has its own special threading class: it may not be - * called concurrently with any "Instantiation" function, but it - * may be called concurrently with functions in any other class, - * unless the definition of that class prohibits it (e.g. it may - * not be called concurrently with a "Discovery" function, but it - * may be called concurrently with an "Audio" function. The plugin - * is responsible for any locking or lock-free techniques necessary - * to make this possible. - * - * Note that in the simple case where state is only modified by - * restore(), there are no synchronization issues since save() is - * never called concurrently with restore() (though run() may read - * it during a save). - * - * Plugins that dynamically modify state while running, however, - * must take care to do so in such a way that a concurrent call to - * save() will save a consistent representation of plugin state for a - * single instant in time. The simplest way to do this is to modify a - * copy of the state map and atomically swap a pointer to the entire - * map once the changes are complete (for very large state maps, - * a purely functional map data structure may be more appropriate - * since a complete copy is not necessary). - */ + /** + Save plugin state using a host-provided @a store callback. + + @param instance The instance handle of the plugin. + @param store The host-provided store callback. + @param callback_data An opaque pointer to host data, e.g. the map or + file where the values are to be stored. If @a store is called, + this MUST be passed as its callback_data parameter. + + The plugin is expected to store everything necessary to completely + restore its state later (possibly much later, in a different + process, on a completely different machine, etc.) + + The @a callback_data pointer and @a store function MUST NOT be + used beyond the scope of save(). + + This function has its own special threading class: it may not be + called concurrently with any "Instantiation" function, but it + may be called concurrently with functions in any other class, + unless the definition of that class prohibits it (e.g. it may + not be called concurrently with a "Discovery" function, but it + may be called concurrently with an "Audio" function. The plugin + is responsible for any locking or lock-free techniques necessary + to make this possible. + + Note that in the simple case where state is only modified by + restore(), there are no synchronization issues since save() is + never called concurrently with restore() (though run() may read + it during a save). + + Plugins that dynamically modify state while running, however, + must take care to do so in such a way that a concurrent call to + save() will save a consistent representation of plugin state for a + single instant in time. The simplest way to do this is to modify a + copy of the state map and atomically swap a pointer to the entire + map once the changes are complete (for very large state maps, + a purely functional map data structure may be more appropriate + since a complete copy is not necessary). + */ void (*save)(LV2_Handle instance, LV2_Persist_Store_Function store, void* callback_data); - /** Restore plugin state using a host-provided @a retrieve callback. - * - * @param instance The instance handle of the plugin. - * @param retrieve The host-provided retrieve callback. - * @param callback_data An opaque pointer to host data, e.g. the map or - * file from which the values are to be restored. If @a retrieve is - * called, this MUST be passed as its callback_data parameter. - * - * The plugin MAY assume a restored value was set by a previous call to - * LV2_Persist.save() by a plugin with the same URI. - * - * The plugin MUST gracefully fall back to a default value when a - * value can not be retrieved. This allows the host to reset the - * plugin state with an empty map. - * - * The @a callback_data pointer and @a store function MUST NOT be used - * beyond the scope of restore(). - * - * This function is in the "Instantiation" threading class as defined - * by LV2. This means it MUST NOT be called concurrently with any other - * function on the same plugin instance. - */ + /** + Restore plugin state using a host-provided @a retrieve callback. + + @param instance The instance handle of the plugin. + @param retrieve The host-provided retrieve callback. + @param callback_data An opaque pointer to host data, e.g. the map or + file from which the values are to be restored. If @a retrieve is + called, this MUST be passed as its callback_data parameter. + + The plugin MAY assume a restored value was set by a previous call to + LV2_Persist.save() by a plugin with the same URI. + + The plugin MUST gracefully fall back to a default value when a + value can not be retrieved. This allows the host to reset the + plugin state with an empty map. + + The @a callback_data pointer and @a store function MUST NOT be used + beyond the scope of restore(). + + This function is in the "Instantiation" threading class as defined + by LV2. This means it MUST NOT be called concurrently with any other + function on the same plugin instance. + */ void (*restore)(LV2_Handle instance, LV2_Persist_Retrieve_Function retrieve, void* callback_data); diff --git a/ext/persist.lv2/persist.ttl b/ext/persist.lv2/persist.ttl index 64e217e..aa6a92c 100644 --- a/ext/persist.lv2/persist.ttl +++ b/ext/persist.lv2/persist.ttl @@ -29,7 +29,7 @@ @prefix xsd: <http://www.w3.org/2001/XMLSchema> . <http://lv2plug.in/ns/ext/persist> - a lv2:Specification ; + a lv2:Specification ; doap:name "LV2 Persist" ; doap:developer [ a foaf:Person ; @@ -42,7 +42,7 @@ foaf:homepage <http://drobilla.net/> ; rdfs:seeAlso <http://drobilla.net/drobilla.rdf> ] ; - lv2:documentation """ + lv2:documentation """ <p>This extension provides a mechanism for plugins to save and restore state across instances, allowing hosts to save configuration/state/data with a project or fully clone (i.e. make a deep copy of) a plugin instance.</p> |