Lumiera plugins define '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. More...

Description

Lumiera plugins define '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 lumiera_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 initialised 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 finalising the plugin structure initialisation 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 plugin registry 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>

Typedefs
typedef lumiera_plugin *	LumieraPlugin

Functions
	LUMIERA_ERROR_DECLARE (PLUGIN_INIT)

	LUMIERA_ERROR_DECLARE (PLUGIN_OPEN)

	LUMIERA_ERROR_DECLARE (PLUGIN_WTF)

	LUMIERA_ERROR_DECLARE (PLUGIN_REGISTER)

	LUMIERA_ERROR_DECLARE (PLUGIN_VERSION)

LumieraPlugin	lumiera_plugin_new (const char *name)
	Allocates an preinitialises a plugin structure.

LumieraPlugin	lumiera_plugin_init (LumieraPlugin self, void *handle, LumieraInterface plugin)

LumieraPlugin	lumiera_plugin_load (const char *plugin)
	Tries to load a plugin Creates a new plugin structure and tries to load and initialise the plugin.

int	lumiera_plugin_register (LumieraPlugin self)
	Register a plugin and its interfaces.

lumiera_err	lumiera_plugin_error (LumieraPlugin self)
	Query the error state of a plugin.

void *	lumiera_plugin_handle (LumieraPlugin self)
	Query the plugin handle.

const char *	lumiera_plugin_name (LumieraPlugin self)
	Query the plugin name The name is the path and filename under which it was loaded.

void	lumiera_plugin_refinc (LumieraPlugin self)

void	lumiera_plugin_refdec (LumieraPlugin self)

unsigned	lumiera_plugin_unload (LumieraPlugin self)
	Tries to unload a plugin.

LumieraPlugin	lumiera_plugin_lookup (const char *name)
	Lookup a plugin handle in the pluginregistry.

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.

int	lumiera_plugin_cmp_fn (const void keya, const void keyb)

const void *	lumiera_plugin_key_fn (const PSplaynode node)

void	lumiera_plugin_delete_fn (PSplaynode node)

Typedef Documentation

◆ LumieraPlugin

typedef lumiera_plugin* LumieraPlugin

Definition at line 64 of file plugin.h.

Function Documentation

◆ LUMIERA_ERROR_DECLARE() [1/5]

LUMIERA_ERROR_DECLARE ( PLUGIN_INIT )

◆ LUMIERA_ERROR_DECLARE() [2/5]

LUMIERA_ERROR_DECLARE ( PLUGIN_OPEN )

◆ LUMIERA_ERROR_DECLARE() [3/5]

LUMIERA_ERROR_DECLARE ( PLUGIN_WTF )

◆ LUMIERA_ERROR_DECLARE() [4/5]

LUMIERA_ERROR_DECLARE ( PLUGIN_REGISTER )

◆ LUMIERA_ERROR_DECLARE() [5/5]

LUMIERA_ERROR_DECLARE ( PLUGIN_VERSION )

◆ lumiera_plugin_new()

LumieraPlugin lumiera_plugin_new ( const char * name )

Allocates an preinitialises a plugin structure.

Parameters

name	path/filename of the plugin

Returns: new allocated/preinitialised plugin structure with its error state set to LUMIERA_ERROR_PLUGIN_INIT

Definition at line 123 of file plugin.c.

References lumiera_malloc(), lumiera_strndup(), NULL, and psplaynode_init().

Referenced by lumiera_plugin_load_DYNLIB().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_init()

LumieraPlugin lumiera_plugin_init	(	LumieraPlugin	self,
		void *	handle,
		LumieraInterface	plugin
	)

Complete plugin initialisation Stores any pending error (from loading) in self which clears out the LUMIERA_ERROR_PLUGIN_INIT error state which was initialised 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 initialise this plugin

Definition at line 139 of file plugin.c.

References lumiera_error().

Referenced by lumiera_plugin_load_DYNLIB().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_load()

LumieraPlugin lumiera_plugin_load ( const char * plugin )

Tries to load a plugin Creates a new plugin structure and tries to load and initialise 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 241 of file plugin.c.

References lumiera_plugin_types, and NULL.

Referenced by AppState::init(), TEST(), TEST(), TEST(), TEST(), and TEST().

Here is the caller graph for this function:

◆ lumiera_plugin_register()

int lumiera_plugin_register ( LumieraPlugin self )

Register a plugin and its interfaces.

Registers the plugin (unconditionally) at the plugin registry. 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 occurred

Definition at line 260 of file plugin.c.

References lumiera_error_peek(), LUMIERA_ERROR_SET, LUMIERA_ERROR_SET_CRITICAL, LUMIERA_INTERFACE_CAST, LUMIERA_INTERFACE_HANDLE, lumiera_interface_mutex, lumiera_interface_version(), lumiera_interfaceregistry_bulkregister_interfaces(), lumiera_pluginregistry, LUMIERA_RECMUTEX_SECTION, and psplay_insert().

Referenced by AppState::init(), TEST(), TEST(), TEST(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_error()

lumiera_err lumiera_plugin_error ( LumieraPlugin self )

Query the error state of a plugin.

Parameters

self	plugin to query

Returns: error identifier, NULL if no error was set

Definition at line 149 of file plugin.c.

◆ lumiera_plugin_handle()

void * lumiera_plugin_handle ( LumieraPlugin self )

Query the plugin handle.

Parameters

self	plugin to query

Returns: opaque handle set by the loader functions

Definition at line 157 of file plugin.c.

Referenced by lumiera_plugin_unload_DYNLIB().

Here is the caller graph for this function:

◆ lumiera_plugin_name()

const char * lumiera_plugin_name ( LumieraPlugin self )

Query the plugin name The name is the path and filename under which it was loaded.

Parameters

self	plugin to query

Returns: pointer to the name string

Definition at line 165 of file plugin.c.

References NULL.

Referenced by TEST().

Here is the caller graph for this function:

◆ lumiera_plugin_refinc()

void lumiera_plugin_refinc ( LumieraPlugin self )

Increment refcount

Parameters

self	plugin which refcount to increment

Definition at line 172 of file plugin.c.

Referenced by depwalk(), and lumiera_interface_open_interfacenode().

Here is the caller graph for this function:

◆ lumiera_plugin_refdec()

void lumiera_plugin_refdec ( LumieraPlugin self )

Decrement refcount

Parameters

self	plugin which refcount to decrement

Definition at line 179 of file plugin.c.

Referenced by lumiera_interfacenode_close().

Here is the caller graph for this function:

◆ lumiera_plugin_unload()

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 297 of file plugin.c.

References LUMIERA_INTERFACE_CAST, LUMIERA_INTERFACE_HANDLE, lumiera_interface_mutex, lumiera_interfaceregistry_bulkremove_interfaces(), lumiera_plugin_types, lumiera_pluginregistry, LUMIERA_RECMUTEX_SECTION, and psplay_remove().

Referenced by TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_lookup()

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 338 of file plugin.c.

References lumiera_interface_mutex, lumiera_pluginregistry, LUMIERA_RECMUTEX_SECTION, NULL, and psplay_find().

Referenced by TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_discover()

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 187 of file plugin.c.

References init_exts_globs(), lumiera_config_setdefault(), lumiera_config_wordlist_get_nth(), LUMIERA_DIE, lumiera_error_peek(), lumiera_get_plugin_path_default(), lumiera_interface_mutex, lumiera_pluginregistry, LUMIERA_RECMUTEX_SECTION, lumiera_tmpbuf_snprintf(), NULL, and psplay_find().

Referenced by AppState::init(), TEST(), TEST(), TEST(), TEST(), and TEST().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lumiera_plugin_cmp_fn()

int lumiera_plugin_cmp_fn	(	const void *	keya,
		const void *	keyb
	)

Definition at line 379 of file plugin.c.

Referenced by lumiera_interfaceregistry_init().

Here is the caller graph for this function:

◆ lumiera_plugin_key_fn()

const void * lumiera_plugin_key_fn ( const PSplaynode node )

Definition at line 386 of file plugin.c.

Referenced by lumiera_interfaceregistry_init().

Here is the caller graph for this function:

◆ lumiera_plugin_delete_fn()

void lumiera_plugin_delete_fn ( PSplaynode node )

Definition at line 393 of file plugin.c.

References LUMIERA_INTERFACE_CAST, LUMIERA_INTERFACE_HANDLE, lumiera_interfaceregistry_bulkremove_interfaces(), and lumiera_plugin_types.

Referenced by lumiera_interfaceregistry_init().

Here is the call graph for this function:

Here is the caller graph for this function:

Description

Typedefs

Functions

Typedef Documentation

◆ LumieraPlugin

Function Documentation

◆ LUMIERA_ERROR_DECLARE() [1/5]

◆ LUMIERA_ERROR_DECLARE() [2/5]

◆ LUMIERA_ERROR_DECLARE() [3/5]

◆ LUMIERA_ERROR_DECLARE() [4/5]

◆ LUMIERA_ERROR_DECLARE() [5/5]

◆ lumiera_plugin_new()

◆ lumiera_plugin_init()

◆ lumiera_plugin_load()

◆ lumiera_plugin_register()

◆ lumiera_plugin_error()

◆ lumiera_plugin_handle()

◆ lumiera_plugin_name()

◆ lumiera_plugin_refinc()

◆ lumiera_plugin_refdec()

◆ lumiera_plugin_unload()

◆ lumiera_plugin_lookup()

◆ lumiera_plugin_discover()

◆ lumiera_plugin_cmp_fn()

◆ lumiera_plugin_key_fn()

◆ lumiera_plugin_delete_fn()