PIPluginLoader Class Reference

Plugin loader. Handles dynamic library loading, symbol resolution, and plugin lifecycle management. More...

#include <piplugin.h>

Public Types
enum	Error {   Unknown , NoError , NoSuchFile , LibraryLoadError ,   MissingSymbols , InvalidLoaderVersion , InvalidUserVersion }
	Possible load plugin error. More...
typedef int(*	FunctionLoaderVersion) ()
	Signature of the exported loader version function.
typedef void(*	FunctionStaticMerge) (int, void *, void *)
	Signature of the exported static merge function.

Public Member Functions
	PIPluginLoader (const PIString &name=PIString())
	Contruct loader with base filename "name" and call load() if "name" not empty.
	~PIPluginLoader ()
	Destructor, unload library.
bool	load (const PIString &name)
	Loads plugin by base filename name and updates error state on failure. More...
void	unload ()
	Unload plugin and free library.
bool	isLoaded () const
	Returns if plugin is successfully loaded.
Error	lastError () const
	Returns error of last load() call.
PIString	lastErrorText () const
	Returns error message of last load() call.
void	setMessages (bool yes)
	Set if PIPluginLoader should print load messages, true by default.
bool	isMessages () const
	Returns if PIPluginLoader should print load messages, true by default.
PIString	libPath ()
	Returns loaded plugin library path.
void *	resolve (const char *name)
	Obtain exported library method with name "symbol". More...
void	mergeStatic ()
	Invoke plugin PIP_PLUGIN_STATIC_SECTION_MERGE Calls the plugin's static section merge function to synchronize application and plugin data. More...

Static Public Member Functions
static PIStringList	pluginsDirectories (const PIString &name)
	Returns existing plugin directories for subdirectory name.

Related Functions
(Note that these are not member functions.)
#define	PIP_PLUGIN
	Declares plugin entry points and should be used before other PIP_PLUGIN_* macros.
#define	PIP_PLUGIN_SET_USER_VERSION(version)
	Sets user version checked during loading, "version" is quoted string.
#define	PIP_PLUGIN_ADD_STATIC_SECTION(type, ptr)
	Registers a static section pointer for future merge. type is an integer key.
#define	PIP_PLUGIN_STATIC_SECTION_MERGE
	Declares a function that merges plugin and application static sections. More...
#define	PIP_PLUGIN_EXPORT
	Marks a plugin function for export.

Detailed Description

Plugin loader. Handles dynamic library loading, symbol resolution, and plugin lifecycle management.

Synopsis

This file provides several macro to define plugin and PIPluginLoader - class to load and check plugin.

Plugin side

Plugin is a shared library that can be loaded in run-time. This is only PIP_PLUGIN macro necessary to define plugin. If you want to set and check some version, use macro PIP_PLUGIN_SET_USER_VERSION(version). Also you can define a function to merge static sections between application and plugin with macro PIP_PLUGIN_STATIC_SECTION_MERGE. Before merge, you should set pointers to that sections with macro PIP_PLUGIN_ADD_STATIC_SECTION(type, ptr).

Application side

Application should use class PIPluginLoader to load plugin. Main function is load(PIString name). "name" is base name of library, PIPluginLoader try to use sevaral names, <name>, lib<name> and "dll", "so" and "dylib" extensions, depends on system.
For example:

PIPluginLoader l;
l.load("foo");

On Windows, try to open "foo", "libfoo", "foo.dll" and "libfoo.dll".
If you using user version check, you should set it with macro PIP_PLUGIN_SET_USER_VERSION(version). When plugin is successfully loaded and checked, you can load your custom symbols with function resolve(name), similar to PILibrary.

Note

You should use PIP_PLUGIN_EXPORT and C-linkage with functions you want to use with resolve(name)!

Static sections

Macro PIP_PLUGIN_STATIC_SECTION_MERGE defines function with arguments (int type, void * from, void * to), so you can leave this macro as declaration or define its body next:

PIP_PLUGIN_STATIC_SECTION_MERGE() {
    switch (type) {
    ...
    }
}

Note

If you using singletones, remember that cpp-defined singletones in shared libraries are single for whole application, including plugins! But if you use h-defined singletones or static linking, there are many objects in application and you should merge their content with this macro.

Anyway, if this is macro PIP_PLUGIN_STATIC_SECTION_MERGE, it called once while loading plugin with "from" - plugin side and "to" - application side, and second (optionally) on method mergeStatic() with "from" - application side and "to" - plugin side.
First direction allow you to copy all defined static content from plugin to application, and second - after loading all plugins (for example) to copy static content from application (and all other plugins) to plugin.

Examples

Simple plugin:

#include <piplugin.h>
 
PIP_PLUGIN
 
extern "C" {
    PIP_PLUGIN_EXPORT void myFunc() {
        piCout << "Hello plugin!";
    }
}

Application:

#include <piplugin.h>
int main() {
    PIPluginLoader pl;
    pl.load("your_lib");
    if (pl.isLoaded()) {
        typedef void(*MyFunc)();
        MyFunc f = (MyFunc)pl.resolve("myFunc");
        if (f) f();
    }
    return 0;
}

Complex plugin:

#include <piplugin.h>
 
PIStringList global_list;
 
PIP_PLUGIN
PIP_PLUGIN_SET_USER_VERSION("1.0.0")
PIP_PLUGIN_ADD_STATIC_SECTION(1, &global_list)
 
STATIC_INITIALIZER_BEGIN
    global_list << "plugin_init";
STATIC_INITIALIZER_END
 
PIP_PLUGIN_STATIC_SECTION_MERGE {
    PIStringList * sfrom = (PIStringList*)from, * sto = (PIStringList*)to;
    *sto << *sfrom;
    sto->removeDuplicates();
}

Application:

#include <piplugin.h>
 
PIStringList global_list;
 
PIP_PLUGIN_SET_USER_VERSION("1.0.0");
PIP_PLUGIN_ADD_STATIC_SECTION(1, &global_list);
 
int main() {
    global_list << "app";
    PIPluginLoader pl;
    pl.load("your_lib");
    pl.mergeStatic();
    piCout << "list =" << global_list;
    return 0;
}

Member Enumeration Documentation

Error

enum PIPluginLoader::Error

Possible load plugin error.

Enumerator
Unknown	No load() call yet
NoError	No error
NoSuchFile	Can`t find library file
LibraryLoadError	System can`t load library
MissingSymbols	Can`t find necessary symbols
InvalidLoaderVersion	Internal version mismatch
InvalidUserVersion	User version mismatch

Member Function Documentation

load()

bool PIPluginLoader::load

(

const PIString &

name

)

Loads plugin by base filename name and updates error state on failure.

Loader try prefix "lib" and suffix ".dll", ".so" or ".dylib", depends on platform.

resolve()

void * PIPluginLoader::resolve

(

const char *

name

)

Obtain exported library method with name "symbol".

See also

PILibrary::resolve()

mergeStatic()

void PIPluginLoader::mergeStatic

(

)

Invoke plugin PIP_PLUGIN_STATIC_SECTION_MERGE Calls the plugin's static section merge function to synchronize application and plugin data.

Call PIP_PLUGIN_STATIC_SECTION_MERGE function on every common type, with "from" - application scope, "to" - plugin scope

Friends And Related Function Documentation

PIP_PLUGIN_STATIC_SECTION_MERGE

#define PIP_PLUGIN_STATIC_SECTION_MERGE

related

Declares a function that merges plugin and application static sections.

This is functions with 3 arguments: (int type, void * from, void * to). This function invoked first while loading plugin with "from" - plugin scope, "to" - application scope, and second (optionally) on PIPluginLoader::mergeStatic() method with "from" - application scope, "to" - plugin scope. So with macro you can merge application and plugin static data.