plugin.c File Reference

Plugin loader implementation. More...

Go to the source code of this file.

Description

Plugin loader implementation.

Definition in file plugin.c.

#include "include/logging.h"
#include "lib/safeclib.h"
#include "lib/tmpbuf.h"
#include "lib/psplay.h"
#include "lib/recmutex.h"
#include "lib/error.h"
#include "include/config-facade.h"
#include "common/interfaceregistry.h"
#include "common/config.h"
#include "common/plugin.h"
#include <glob.h>
#include <nobug.h>

Macros
#define	LUMIERA_PLUGIN_TYPE_PLANNED(name, ext)
#define	LUMIERA_PLUGIN_TYPES
	Supported (and planned) plugin types and their file extensions This maps filename extensions to implementations (of the respective _load_NAME and _unload_NAME functions) So far we only support platform dynamic libraries, later we may add plugins implemented in Lua and c source modules which get compiled on the fly.
#define	LUMIERA_PLUGIN_TYPE(type, ext)
#define	LUMIERA_PLUGIN_TYPE(type, ext)   {lumiera_plugin_load_##type, lumiera_plugin_unload_##type, ext},

Typedefs
typedef lumiera_plugintype *	LumieraPlugintype

Classes
struct	lumiera_plugintype
	record the extension and a callback function for loading the associated plugin for each plugin type More...
struct	lumiera_plugin

Functions
static char *	init_exts_globs (void)
	LUMIERA_ERROR_DEFINE (PLUGIN_INIT, "Initialisation error")
	LUMIERA_ERROR_DEFINE (PLUGIN_OPEN, "Could not open plugin")
	LUMIERA_ERROR_DEFINE (PLUGIN_WTF, "Not a Lumiera plugin")
	LUMIERA_ERROR_DEFINE (PLUGIN_REGISTER, "Could not register plugin")
	LUMIERA_ERROR_DEFINE (PLUGIN_VERSION, "Plugin Version unsupported")
LumieraPlugin	lumiera_plugin_new (const char *name)
	Allocates an preinitialises a plugin structure.
LumieraPlugin	lumiera_plugin_init (LumieraPlugin self, void *handle, LumieraInterface plugin)
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)
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.
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 plugin)
	Register a plugin and its interfaces.
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_cmp_fn (const void *keya, const void *keyb)
const void *	lumiera_plugin_key_fn (const PSplaynode node)
void	lumiera_plugin_delete_fn (PSplaynode node)

Variables
PSplay	lumiera_pluginregistry
static lumiera_plugintype	lumiera_plugin_types []

Typedef Documentation

LumieraPlugintype

typedef lumiera_plugintype* LumieraPlugintype

Definition at line 76 of file plugin.c.

Macro Definition Documentation

LUMIERA_PLUGIN_TYPE_PLANNED

#define LUMIERA_PLUGIN_TYPE_PLANNED	(		name,
			ext
	)

Definition at line 51 of file plugin.c.

LUMIERA_PLUGIN_TYPES

#define LUMIERA_PLUGIN_TYPES

Value:

  LUMIERA_PLUGIN_TYPE(DYNLIB, ".so")            \
  LUMIERA_PLUGIN_TYPE(DYNLIB, ".lum")           \
  LUMIERA_PLUGIN_TYPE_PLANNED(LUA, ".lua")      \
  LUMIERA_PLUGIN_TYPE_PLANNED(CSOURCE, ".c")

Supported (and planned) plugin types and their file extensions This maps filename extensions to implementations (of the respective _load_NAME and _unload_NAME functions) So far we only support platform dynamic libraries, later we may add plugins implemented in Lua and c source modules which get compiled on the fly.

Definition at line 59 of file plugin.c.

LUMIERA_PLUGIN_TYPE [1/2]

#define LUMIERA_PLUGIN_TYPE	(		type,
			ext
	)

Value:

  LumieraPlugin lumiera_plugin_load_##type (const char*);       \
  void lumiera_plugin_unload_##type (LumieraPlugin);

Definition at line 79 of file plugin.c.

LUMIERA_PLUGIN_TYPE [2/2]

#define LUMIERA_PLUGIN_TYPE	(		type,
			ext
	)		{lumiera_plugin_load_##type, lumiera_plugin_unload_##type, ext},

Definition at line 79 of file plugin.c.

---

Class Documentation

lumiera_plugin_struct

struct lumiera_plugin_struct

Class Members
psplaynode	node
const char *	name
unsigned	refcnt
time_t	last
lumiera_err	error	bulk loading plugins must not fail entirely, just because one plugin doesn't comply. Thus we're recording local errors here
LumieraInterface	plugin
void *	handle

Collaboration diagram for lumiera_plugin:

Function Documentation

init_exts_globs()

static char * init_exts_globs ( void  )

static

Definition at line 350 of file plugin.c.

References lumiera_malloc(), and lumiera_plugin_types.

Referenced by lumiera_plugin_discover().

Here is the call graph for this function:

Here is the caller graph for this function:

LUMIERA_ERROR_DEFINE() [1/5]

LUMIERA_ERROR_DEFINE	(	PLUGIN_INIT	,
		"Initialisation error"
	)

LUMIERA_ERROR_DEFINE() [2/5]

LUMIERA_ERROR_DEFINE	(	PLUGIN_OPEN	,
		"Could not open plugin"
	)

LUMIERA_ERROR_DEFINE() [3/5]

LUMIERA_ERROR_DEFINE	(	PLUGIN_WTF	,
		"Not a Lumiera plugin"
	)

LUMIERA_ERROR_DEFINE() [4/5]

LUMIERA_ERROR_DEFINE	(	PLUGIN_REGISTER	,
		"Could not register plugin"
	)

LUMIERA_ERROR_DEFINE() [5/5]

LUMIERA_ERROR_DEFINE	(	PLUGIN_VERSION	,
		"Plugin Version unsupported"
	)

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_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_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_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_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_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:

Variable Documentation

lumiera_pluginregistry

PSplay lumiera_pluginregistry

extern

Definition at line 34 of file interfaceregistry.c.

Referenced by lumiera_interfaceregistry_destroy(), lumiera_interfaceregistry_init(), lumiera_plugin_discover(), lumiera_plugin_lookup(), lumiera_plugin_register(), and lumiera_plugin_unload().

lumiera_plugin_types

lumiera_plugintype lumiera_plugin_types[]

static

Initial value:

=
  {
    LUMIERA_PLUGIN_TYPES
    {NULL, NULL, NULL}
  }

Definition at line 87 of file plugin.c.

Referenced by init_exts_globs(), lumiera_plugin_delete_fn(), lumiera_plugin_load(), and lumiera_plugin_unload().