Class responsible for managing discovery and loading of plugins. More...

#include <gmPluginLoader.h>

Collaboration diagram for GmPluginLoader:

[legend]

Public Member Functions
	GmPluginLoader (const QStringList &pluginPaths)
	Constructor. Receive as a parameter a list of paths where plugins should be searched for.

	~GmPluginLoader ()
	Destructor. Unloads all plugins. See comments in the class description.

bool	checkAndStoreLibVersion (const QStringList &libInfo, const QStringList &libDepInfo, QString &err)
	Given a library (plugin) version and dependency information, checks that the current environment is compatible. If it is, the given library information is added to the current environment. More...

bool	loadPluginList ()
	Traverses plugin paths looking for plugins. Loads the plugin description found in Lua files building the plugin info map. More...

void	printPluginVersionInfo (const GmLogCategory &logger, bool printDep)
	A helper function that can be used to print version information for every plugin registered by loadPluginList(). More...

QList< GmPluginInfo * >	pluginListByCategory (QString cat) const
	Returns a list with information about every known plugin that implements the specified category.

bool	hasCategory (QString cat) const
	Returns true if there exists at least one plugin from the given category.

GmPluginInfo *	pluginInfo (QString pluginName) const
	Returns the plugin information object given the plugin name or NULL if not found.

GmPluginObject *	instancePluginObject (QString objId, QString objTypeName, QString objDescription, GmSimulationData *simData, QString category)
	Instances a new object with type given by typeName in a simmilar way as done by loadPluginObject(), but without calling resource Lua functions and also without calling loadPrivateData() on the resulting object.

GmPluginObject *	loadPluginObject (LuaTable &globalTab, LuaTable &objTab, GmSimulationData *simData, QString category)
	Loads information for an object bound to a plugin. More...

bool	loadPluginObjectList (LuaTable &globalTab, GmSimulationData simData, QString category, QString listName, bool required, GmPluginLoaderAdder adder)
	Loads information for a list of objects bound to a single plugin category. More...

GmPluginObjectFactory *	objectFactory (QString pluginName, QString category="", QString objType="")
	Given a plugin name, returns the plugin root object. More...

const GmLogCategory &	logger ()
	Returns a reference to the internal logger used to emit error messages.

const QMap< QString, GmPluginInfo * > &	pluginMap () const
	Returns a map with available plugin names and their information object.

const QMap< QString, GmPluginInfo * > &	pluginDataAliasMap () const
	Returns a map with registered plugin data alias names and their information object.

bool	checkPluginDataAttributes (LuaTable &globalTab, QString alias, const LuaTable &objTab)
	Submits objTab for checking by the plugin data checking function, from the plugin associated with the given alias.

Static Public Member Functions
static void	printLibVersionInfo (const GmLogCategory &logger, QString libName, const QStringList &info)
	Helper function to print the given library version info in a formatted way.

Private Member Functions
bool	recursiveLoad (QString pluginName, const GmPluginInfo *info, QString category)
	If the Shared library given by pluginName hasn't been loaded, loads it filling _pluginInstanceMap. If the plugin depends on other plugins, makes sure that the dependent plugins are loaded prior to loading pluginName. More...

bool	loadPluginRsrcs (LuaTable &globalTab, const GmPluginInfo *info)
	If the plugin type associated with info has a Lua resource file, loads it in the model environment inside the table named by info->pluginLuaTableName() More...

bool	checkObjectAttributes (LuaTable &globalTab, const GmPluginInfo *info, LuaTable &objTable)
	If the plugin type that will be used to parse attributes in objTable has a registered Lua check function, calls it to verify the data in objTable. More...

Private Attributes
QStringList	_pathList
	List of paths where plugins will be searched.

QMap< QString, GmPluginInfo * >	_pluginInfoMap
	Map associating plugin names with their information.

QMap< QString, QPluginLoader * >	_pluginInstanceMap
	Map associating plugin names with their implementation.

QVector< QPluginLoader * >	_pluginInstanceList
	List storing the same pointers as _pluginInstanceMap, but in their load order.

QMap< QString, QString >	_revisionMap
	Map associating plugin/library paths with their revisions.

QMap< QString, GmPluginInfo * >	_pluginDataAliasMap
	Map associating plugin data aliases with their corresponding plugins.

GmLogCategory	_logger
	Logger object for plugin handling.

Detailed Description

Class responsible for managing discovery and loading of plugins.

When constructed, the class receives a path list where plugins are searched for. For a plugin to be recognized as such, there must be a shared library and an information file describing the plugin capabilities. Both should have the same base name, differing only in the extension, which should be the standard shared library extension for the plugin (.dll or. so) and .lua for the information file.

After creating the loader, the function checkAndStoreLibVersion() should be used to verify and register the revisions for the currently loaded basic Gema libraries. This is needed for later checking the current environment against the environment expected by the plugins.

After registering versions, the function loadPluginList() should be called. It will read the information file for discovered plugins. Shared libraries will not be loaded at this time. Instead, they will be loaded only if the plugin is instanced by a call to loadPluginObjectData() or loadPluginObjectListData()

Once loaded, plugins will stay loaded until the PluginLoader is destroyed. IMPORTANT: The plugin loader should NOT be destroyed prior to the destruction of all objects created by the plugins.

Messages are logged to a special logger category used only for plugin messages.

Member Function Documentation

◆ checkAndStoreLibVersion()

bool GmPluginLoader::checkAndStoreLibVersion	(	const QStringList &	libInfo,
		const QStringList &	libDepInfo,
		QString &	err
	)

Given a library (plugin) version and dependency information, checks that the current environment is compatible. If it is, the given library information is added to the current environment.

The basic environment should be set up by calling this function with version information for the basic gema libraries in dependency sequence (first the utilitary libs, then the core library, followed by the lua core library, etc...). Afterwards it can be used to check plugins.

The given libInfo and libDepInfo parameters must be formated according to the specifications for GmPluginObjectFactory.

On errors, the function returns false and fills err with an error message.

◆ checkObjectAttributes()

bool GmPluginLoader::checkObjectAttributes	(	LuaTable &	globalTab,
		const GmPluginInfo *	info,
		LuaTable &	objTable
	)

private

If the plugin type that will be used to parse attributes in objTable has a registered Lua check function, calls it to verify the data in objTable.

Parameters

globalTab	Global table where all simulation data was loaded
info	Information object associated with the plugin
objTable	Lua table with object attributes to be checked

Returns: Returns false if an error was identified, true otherwise.

◆ loadPluginList()

bool GmPluginLoader::loadPluginList ( )

Traverses plugin paths looking for plugins. Loads the plugin description found in Lua files building the plugin info map.

Returns false if no valid plugin could be found.

◆ loadPluginObject()

GmPluginObject * GmPluginLoader::loadPluginObject	(	LuaTable &	globalTab,
		LuaTable &	objTab,
		GmSimulationData *	simData,
		QString	category
	)

Loads information for an object bound to a plugin.

This method loads from a Lua table the definition of an object implemented by a plugin. The following standard object fields are read from the table: id - Object unique identification among other objects of the same plugin category (unique among meshes, for example). typeName - String identifying the object type name. Can be the plugin name if it only exports one object type or the full qualified type name composed by the plugin name + "."

the object type (Ex: "GemaMesh.cell"). description - Optional description of the object

After those fields are read, the plugin corresponding to the plugin typeName is loaded to memory (if needed) and it's object factory retrieved. With the factory at hand, a new object of type typeName is instanced. The new object is then used to validate and load other fields present in the Lua table.

Obs: Check for global required fields and object unicity names where done by the object criation function call while parsing the simulation file.

Check for specific object attributes can be done by a registered Lua function provided by a Lua resource tied to the plugin (the preferred method) or can be done by the associated plugin type in the call to loadPrivateData().

Parameters

globalTab	Global table where all simulation data was loaded
objTab	Lua table where the object data was loaded
simData	Pointer to the simulation data structure, passed as a parameter when creating the plugin object
category	The category for the expected plugin object. Used only for validation purposes and to get better error messages.

Returns: Returns the newly created object or NULL if it can't be loaded.

◆ loadPluginObjectList()

bool GmPluginLoader::loadPluginObjectList	(	LuaTable &	globalTab,
		GmSimulationData *	simData,
		QString	category,
		QString	listName,
		bool	required,
		GmPluginLoaderAdder *	adder
	)

Loads information for a list of objects bound to a single plugin category.

This method loads object definitions from a Lua list and calls loadPluginObject() to create an object for each list entry. Created objects are stored in it's destination by the adder object received as a parameter.

See comments in loadPluginObject() for an overview of the object creation details.

Parameters

globalTab	Global table where all simulation data was loaded
simData	Pointer to the simulation data structure, passed as a parameter when creating plugin objects
category	The category for the expected plugin objects. Used only for validation purposes and to get better error messages.
listName	The name of the list in the global Lua environment used to store object definitions
required	Defines if the existannce of at least one object in the list is necessary for model correctness.
objMap	Adder object used to store each parsed plugin object into its final destination

Returns: Returns false if any of the objects could't be loaded. In the case of errors, the container referenced by the adder will be filled with the previous objects in the list that could be loaded, so don't forget to release the memory of those poor guys.

◆ loadPluginRsrcs()

bool GmPluginLoader::loadPluginRsrcs	(	LuaTable &	globalTab,
		const GmPluginInfo *	info
	)

private

If the plugin type associated with info has a Lua resource file, loads it in the model environment inside the table named by info->pluginLuaTableName()

If the plugin has dependent plugins, their resources are loaded recursivelly in order for the plugin to be able to call check functions given by the plugins it depends upon.

Returns false if the plugin has an associated resource and there was an error loading it.

◆ objectFactory()

GmPluginObjectFactory * GmPluginLoader::objectFactory	(	QString	pluginName,
		QString	category = `""`,
		QString	objType = `""`
	)

Given a plugin name, returns the plugin root object.

If the shared library has already been loaded, returns the already instanced root object. Else, tries to load the library.

This is a lower level function. It's better to use instancePluginObject(), loadPluginObject() or loadPluginObjectList() when possible.

Parameters

pluginName	Name identifying the plugin to be loaded. Must be the plugin name and NOT a full hierarchical plugin object type name.
category	The category for the expected plugin. Used only for validation purposes. Can be empty for no category check.
objType	The object type that will be requested to the plugin. Used only for validation purposes. Can be empty for no objType check.

Returns: Returns the plugin factory or NULL in case of errors loading the plugin.

◆ printPluginVersionInfo()

void GmPluginLoader::printPluginVersionInfo	(	const GmLogCategory &	logger,
		bool	printDep
	)

A helper function that can be used to print version information for every plugin registered by loadPluginList().

This has the side effect of loading every registered plugin.

◆ recursiveLoad()

bool GmPluginLoader::recursiveLoad	(	QString	pluginName,
		const GmPluginInfo *	info,
		QString	category
	)

private

If the Shared library given by pluginName hasn't been loaded, loads it filling _pluginInstanceMap. If the plugin depends on other plugins, makes sure that the dependent plugins are loaded prior to loading pluginName.

If info is NULL, gets the information internally. The category string reflects the desired category when the plugin was loaded. Can't be queried from the plugin info since the plugin can implement several categories (and showing all would change the log for all existing regression tests...). Returns true on success, false on error.

The documentation for this class was generated from the following files:

inc/plugins/gmPluginLoader.h
src/plugins/gmPluginLoader.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ checkAndStoreLibVersion()

◆ checkObjectAttributes()

◆ loadPluginList()

◆ loadPluginObject()

◆ loadPluginObjectList()

◆ loadPluginRsrcs()

◆ objectFactory()

◆ printPluginVersionInfo()

◆ recursiveLoad()