common/plugin.h File Reference
Detailed Description
Lumiera plugins defines 'interfaces' as shown in interface.h, the plugin system handles the loading of all kinds of plugins under the hood, invoked from the interface system.Most things defined here are called internally and should not be used by other parts of the application.
Plugin discovery The plugin_discover() function offers a automatic way to load and register new plugins. It traverses all configured plugin directories. It takes to function for loading and registering plugins as parameter, by now this only uses the here defined plugin_load() and plugin_register() functions which lets it load any newly found plugin unconditionally. Later these callbacks will be replaced by a smarter system (plugindb) which makes it possible to load plugins on-demand and select proper plugins based on their version and capabilities.
Plugin loading Plugins are loaded and initialized in a sequence of steps: plugin_load() dispatches to a specific loader function depending on the type (extension) of a plugin. This loader allocates a new plugin structure with plugin_new() and then does it work and eventually finalizing the plugin structure initialization with plugin_init() by providing a handle to a lumieraorg__plugin interface. plugin_init() also stores the current error state (which might be clean) into the plugin. After that the plugin can be registered which records it in the pluginregistry and if its error state is clean, registering all interfaces it offers in the interface registry. With that the plugin is ready to be used. Plugins with the error state set should still be registered to prevent further discovery runs to try loading them again.
Definition in file plugin.h.
#include "lib/psplay.h"
#include "lib/error.h"
#include "common/interface.h"
#include <stdlib.h>
#include <nobug.h>
Go to the source code of this file.
Typedefs | |
|
typedef struct lumiera_plugin_struct | lumiera_plugin |
| typedef lumiera_plugin * | LumieraPlugin |
Functions | |
| LUMIERA_ERROR_DECLARE (PLUGIN_VERSION) | |
| LUMIERA_ERROR_DECLARE (PLUGIN_REGISTER) | |
| LUMIERA_ERROR_DECLARE (PLUGIN_WTF) | |
| LUMIERA_ERROR_DECLARE (PLUGIN_OPEN) | |
| LUMIERA_ERROR_DECLARE (PLUGIN_INIT) | |
| int | lumiera_plugin_cmp_fn (const void *keya, const void *keyb) |
| void | lumiera_plugin_delete_fn (PSplaynode node) |
| int | lumiera_plugin_discover (LumieraPlugin(*callback_load)(const char *plugin), int(*callback_register)(LumieraPlugin)) |
| discover new plugins traverses the configured plugin paths and calls the callback_load function for any plugin not actually loaded. | |
| lumiera_err | lumiera_plugin_error (LumieraPlugin self) |
| Query the error state of a plugin. | |
| void * | lumiera_plugin_handle (LumieraPlugin self) |
| Query the plugin handle. | |
| LumieraPlugin | lumiera_plugin_init (LumieraPlugin self, void *handle, LumieraInterface plugin) |
| Complete plugin initialization. | |
| const void * | lumiera_plugin_key_fn (const PSplaynode node) |
| LumieraPlugin | lumiera_plugin_load (const char *plugin) |
| Tries to load a plugin Creates a new plugin structure and tries to load and initialize the plugin. | |
| LumieraPlugin | lumiera_plugin_lookup (const char *name) |
| Lookup a plugin handle in the pluginregistry. | |
| const char * | lumiera_plugin_name (LumieraPlugin self) |
| Query the plugin name The name is the path and filname under which it was loaded. | |
| LumieraPlugin | lumiera_plugin_new (const char *name) |
| Allocates an preinitializes a plugin structure. | |
| void | lumiera_plugin_refdec (LumieraPlugin self) |
| Decrement refcount. | |
| void | lumiera_plugin_refinc (LumieraPlugin self) |
| Increment refcount. | |
| int | lumiera_plugin_register (LumieraPlugin self) |
| Register a plugin and its interfaces. | |
| unsigned | lumiera_plugin_unload (LumieraPlugin self) |
| Tries to unload a plugin. | |
| NOBUG_DECLARE_FLAG (plugin) | |
Function Documentation
| LumieraPlugin lumiera_plugin_new | ( | const char * | name | ) |
| LumieraPlugin lumiera_plugin_init | ( | LumieraPlugin | self, | |
| void * | handle, | |||
| LumieraInterface | plugin | |||
| ) |
Complete plugin initialization.
For internal use only.
Stores any pending error (from loading) in self which clears out the LUMIERA_ERROR_PLUGIN_INIT error state which was initialized by lumiera_plugin_new(), stores the handle and plugin pointers in the plugin struct.
- Parameters:
-
self pointer to the plugin struct handle opaque handle referring to some plugin type specific data plugin a lumieraorg__plugin interface which will be used to initialize this plugin
Definition at line 145 of file plugin.c.
References lumiera_error().
| LumieraPlugin lumiera_plugin_load | ( | const char * | plugin | ) |
Tries to load a plugin Creates a new plugin structure and tries to load and initialize the plugin.
The plugins error state may be set on any problem which should be queried later.
- Parameters:
-
plugin path/filename of the plugin to load
- Returns:
- pointer to the new plugin structure (always, never NULL, check error state)
Definition at line 244 of file plugin.c.
References lumiera_plugintype_struct::ext, and lumiera_plugintype_struct::lumiera_plugin_load_fn.
Referenced by lumiera::AppState::init().
| int lumiera_plugin_register | ( | LumieraPlugin | self | ) |
Register a plugin and its interfaces.
Registers the plugin (unconditionally) at the pluginregistry. When the error state of the plugin is NULL then use its lumieraorg__plugin interface to register all interfaces offered by the plugin at the interface registry. Registered plugins will be automatic unloaded at application end.
- Parameters:
-
self the plugin to be registered (calling with NULL is a no-op)
- Returns:
- 1 on success (including calling with NULL) and 0 when a error occured
Definition at line 263 of file plugin.c.
References lumiera_error_peek(), LUMIERA_ERROR_SET, LUMIERA_INTERFACE_CAST, LUMIERA_INTERFACE_HANDLE, lumiera_interface_version(), and LUMIERA_RECMUTEX_SECTION.
Referenced by lumiera::AppState::init().
| lumiera_err lumiera_plugin_error | ( | LumieraPlugin | self | ) |
| void* lumiera_plugin_handle | ( | LumieraPlugin | self | ) |
| const char* lumiera_plugin_name | ( | LumieraPlugin | self | ) |
| void lumiera_plugin_refinc | ( | LumieraPlugin | self | ) |
| void lumiera_plugin_refdec | ( | LumieraPlugin | self | ) |
| unsigned lumiera_plugin_unload | ( | LumieraPlugin | self | ) |
Tries to unload a plugin.
When the Plugin is unused, then all resources associated with it are freed and it will be removed from memory
- Parameters:
-
plugin the plugin to be unloaded.
- Returns:
- 0 on success, else the refcount of users which keeping the plugin loaded
Definition at line 300 of file plugin.c.
References lumiera_plugintype_struct::ext, LUMIERA_INTERFACE_CAST, LUMIERA_INTERFACE_HANDLE, lumiera_plugintype_struct::lumiera_plugin_unload_fn, and LUMIERA_RECMUTEX_SECTION.
| LumieraPlugin lumiera_plugin_lookup | ( | const char * | name | ) |
Lookup a plugin handle in the pluginregistry.
- Parameters:
-
name name of the plugin to be looked up
- Returns:
- plugin handle on success, NULL if the plugin is not found in the registry
Definition at line 341 of file plugin.c.
References LUMIERA_RECMUTEX_SECTION.
| int lumiera_plugin_discover | ( | LumieraPlugin(*)(const char *plugin) | callback_load, | |
| int(*)(LumieraPlugin) | callback_register | |||
| ) |
discover new plugins traverses the configured plugin paths and calls the callback_load function for any plugin not actually loaded.
If callback_load returns a plugin (and not NULL) then this is feed to the callback_register function.
Definition at line 193 of file plugin.c.
References lumiera_config_setdefault(), lumiera_config_wordlist_get_nth(), LUMIERA_DIE, lumiera_error_peek(), and LUMIERA_RECMUTEX_SECTION.
Referenced by lumiera::AppState::init().
