plugin.h File Reference

Go to the source code of this file.

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)
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. More...
lumiera_err	lumiera_plugin_error (LumieraPlugin self)
	Query the error state of a plugin. More...
void *	lumiera_plugin_handle (LumieraPlugin self)
	Query the plugin handle. More...
LumieraPlugin	lumiera_plugin_init (LumieraPlugin self, void *handle, LumieraInterface plugin)
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 initialise the plugin. More...
LumieraPlugin	lumiera_plugin_lookup (const char *name)
	Lookup a plugin handle in the pluginregistry. More...
const char *	lumiera_plugin_name (LumieraPlugin self)
	Query the plugin name The name is the path and filename under which it was loaded. More...
LumieraPlugin	lumiera_plugin_new (const char *name)
	Allocates an preinitialises a plugin structure. More...
void	lumiera_plugin_refdec (LumieraPlugin self)
void	lumiera_plugin_refinc (LumieraPlugin self)
int	lumiera_plugin_register (LumieraPlugin self)
	Register a plugin and its interfaces. More...
unsigned	lumiera_plugin_unload (LumieraPlugin self)
	Tries to unload a plugin. More...

Function Documentation

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(), and psplaynode_init().

Here is the call 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().

Here is the call 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.

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_RECMUTEX_SECTION.

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.

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.

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.

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.

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.

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.

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 lumiera_config_setdefault().

Here is the call graph for this function: