From be95afee123c169b083049c2f441d3860a12fea0 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 20 Apr 2007 03:57:41 +0000 Subject: Clean up API, hide more methods that should not be exposed to user. Document performance of most methods. Clean up and clarify documentation. git-svn-id: http://svn.drobilla.net/lad/slv2@460 a436a847-0d15-0410-975c-d299462d15a1 --- slv2/world.h | 75 ++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 40 insertions(+), 35 deletions(-) (limited to 'slv2/world.h') diff --git a/slv2/world.h b/slv2/world.h index 4f5b252..64f0fc2 100644 --- a/slv2/world.h +++ b/slv2/world.h @@ -28,17 +28,19 @@ extern "C" { /** \defgroup world Library context, data loading, etc. * - * These functions deal with the data model which other SLV2 methods - * operate with. The world contains an in-memory cache of all bundles - * manifest.ttl files, from which you can quickly query plugins, etc. + * The "world" represents all library state, and the data found in bundles' + * manifest.ttl (ie it is an in-memory index of all things LV2 found). + * Plugins (and plugin extensions) and the LV2 specification (and LV2 + * extensions) itself can be queried from the world for use. * * Normal hosts which just want to easily load plugins by URI are strongly - * recommended to simply find all installed data in the recommended way with - * \ref slv2_world_load_all rather than find and load bundles manually. - * - * Functions are provided for hosts that wish to access bundles explicitly and - * individually for some reason, this is intended for hosts which are tied to - * a specific bundle (shipped with the application). + * recommended to simply call \ref slv2_world_load_all to find all installed + * data in the recommended way. + * + * Normal hosts should NOT have to refer to bundles directly under normal + * circumstances. However, functions are provided to load individual bundles + * explicitly, intended for hosts which depend on a specific bundle + * (which is shipped with the application). * * @{ */ @@ -60,7 +62,7 @@ void slv2_world_free(SLV2World world); -/** Load all installed LV2 bundles on the system +/** Load all installed LV2 bundles on the system. * * This is the recommended way for hosts to load LV2 data. It does the most * reasonable thing to find all installed plugins, extensions, etc. on the @@ -70,60 +72,63 @@ slv2_world_free(SLV2World world); * * Use of other functions for loading bundles is \em highly discouraged * without a special reason to do so - use this one. - */ -void -slv2_world_load_all(SLV2World world); - - -/** Load all bundles found in \a search_path. * - * \param search_path A colon-delimited list of directories. These directories - * should contain LV2 bundle directories (ie the search path is a list of - * parent directories of bundles, not a list of bundle directories). - * - * If \a search_path is NULL, \a world will be unmodified. - * Use of this function is \b not recommended. Use \ref slv2_world_load_all. + * Time = Query */ void -slv2_world_load_path(SLV2World world, - const char* search_path); +slv2_world_load_all(SLV2World world); -/** Load a specific bundle into \a world. +/** Load a specific bundle. * - * \arg bundle_base_uri is a fully qualified URI to the bundle directory, + * \arg bundle_uri A fully qualified URI to the bundle directory, * with the trailing slash, eg. file:///usr/lib/lv2/someBundle/ * * Normal hosts should not use this function. * - * Hosts should not attach \em any long-term significance to bundle paths + * Hosts should \b never attach any long-term significance to bundle paths * as there are no guarantees they will remain consistent whatsoever. + * Plugins (and other things) are identified by URIs, \b not bundle or + * file names. + * * This function should only be used by apps which ship with a special - * bundle (which it knows exists at some path because they are part of - * the same package). + * bundle (which it knows exists at some path because the bundle is + * shipped with the application). + * + * Time = Query */ void slv2_world_load_bundle(SLV2World world, - const char* bundle_base_uri); + const char* bundle_uri); -/** Add all plugins present in \a world to \a list. +/** Return a list of all found plugins. + * + * The returned list contains just enough references to query + * or instantiate plugins. The data for a particular plugin will not be + * loaded into memory until a call to an slv2_plugin_* function results in + * a query (at which time the data is cached with the SLV2Plugin so future + * queries are very fast). * * Returned plugins contain a reference to this world, world must not be * destroyed until plugins are finished with. + * + * Time = O(1) */ SLV2Plugins slv2_world_get_all_plugins(SLV2World world); -/** Get plugins filtered by a user-defined filter function. +/** Return a list of found plugins filtered by a user-defined filter function. * - * All plugins in \a world that return true when passed to \a include - * (a pointer to a function that takes an SLV2Plugin and returns a bool) - * will be added to \a list. + * All plugins currently found in \a world that return true when passed to + * \a include (a pointer to a function which takes an SLV2Plugin and returns + * a bool) will be in the returned list. * * Returned plugins contain a reference to this world, world must not be * destroyed until plugins are finished with. + * + * Time = O(n * Time(include)) */ SLV2Plugins slv2_world_get_plugins_by_filter(SLV2World world, -- cgit v1.2.1