classPiiEngine
#include <PiiEngine.h>
An execution engine.
Inherits PiiOperationCompound
Description
A class that stores information about a loaded plug-in.
The task of PiiEngine is to handle the loading and unloading of plug-in modules. It inherits from PiiOperationCompound and can thus be used as an executor for a set of interconnected operations. PiiEngine provides a convenience function execute() to check the configuration and to start execution.
A typical, simple usage scenario for the engine is as follows:
//1. create a PiiEngine instance PiiEngine engine; //2. load the necessary plug-ins engine.loadPlugin("piimage"); //3. create operations PiiOperation* reader = engine.createOperation("PiiImageFileReader"); PiiOperation* writer = engine.createOperation("PiiImageFileWriter"); //4. configure them reader->setProperty("fileNamePattern", "*.bmp"); writer->setProperty("outputDirectory", "."); writer->setProperty("extension", "jpg"); //5. connect them reader->connectOutput("image", writer, "image"); //6. monitor for run-time errors connect(engine, SIGNAL(errorOccured(PiiOperation*,const QString&)), myMonitor, SLOT(handleError(PiiOperation*,const QString&))); //7. start the engine try { engine.execute(); } catch (PiiExecutionException& ex) { //handle possible start-up errors here }
Each plug-in has two names: the name of the shared library the plug-in was loaded from, and the name of the plug-in in Ydin's resource database.
Public types
|
enum
|
{ TextFormat, BinaryFormat }
File formats. |
Constructors and destructor
|
( )
Constructs a new PiiEngine. |
|
|
( )
Destroys the engine. |
Public member functions
|
virtual Q_INVOKABLE PiiEngine *
|
( )
Creates a deep copy of the engine. |
|
void
|
( )
Checks and executes all child operations. |
|
( )
Get the library name of the plug-in. |
|
|
Plugin &
|
(
|
|
( )
|
|
|
(
|
|
|
( )
Get the resource name of the plug-in. |
|
|
void
|
(
Saves the engine to fileName. |
|
( )
Get the version of Into the plug-in was originally compiled and linked against. |
|
|
( )
|
Static public member functions
|
static void
|
Ensures that plugin is loaded. |
|
static void
|
Ensures that all plug-ins listed in plugins are loaded. |
|
static bool
|
Returns |
|
static PiiEngine *
|
Loads a stored engine from fileName. |
|
static Plugin
|
Loads a plug-in into the engine. |
|
static void
|
A convenience function that loads many plugins at once. |
|
static QStringList
|
Returns the library names of loaded plug-ins. |
|
static QStringList
|
Returns the resource names of loaded plug-ins. |
|
static QList< Plugin >
|
( )
Returns loaded plug-ins. |
|
static int
|
Remove the named plugin. |
Friends
|
friend struct
|
|
Enumeration details
-
enum FileFormat
File formats.
-
TextFormat- data is saved as UTF-8 text. See PiiTextOutputArchive and PiiTextInputArchive. -
BinaryFormat- data is saved in a raw binary format. See PiiBinaryOutputArchive and PiiBinaryInputArchive.
-
Function details
-
PiiEngine
()Constructs a new PiiEngine.
-
~PiiEngine
()Destroys the engine.
-
Creates a deep copy of the engine.
Reimplemented from PiiOperationCompound.
-
void execute
()Checks and executes all child operations.
This function first calls PiiOperation::check() for all child operations. If none of them throws an exception, PiiOperation::start() will be called. This is a convenience function that saves one from manually performing the sanity check. If the engine is neither
StoppednorPaused, this function does nothing. -
QString libraryName
()Get the library name of the plug-in.
This function returns the name of the plug-in as passed to the PiiEngine::loadPlugin() function.
-
Plugin & operator=
(- const Plugin & other
-
Plugin
() -
Plugin
(- const Plugin & other
-
QString resourceName
()Get the resource name of the plug-in.
Note that this is not the name of the shared library but the resource ID of the plug-in in Ydin's resource database. (See PiiYdin::resourceDatabase())
-
void save
(- const QString & fileName
- const QVariantMap & config = QVariantMap()
- FileFormat format = TextFormat
Saves the engine to fileName.
The format argument specifies the file format. The config map is used to add configuration information to the file. The following keys are recognized:
-
plugins- the names of plug-ins that need to be loaded to be able to run the engine. If the config map doesn't contain thepluginskey, pluginLibraryNames() will be used. -
application- the name of the application that created the engine. If this value is not given, "Into" will be used. -
version- the version of the application that created the engine. Ifapplicationis not given, the current Into version will be used.
try { PiiEngine::loadPlugin("piibase"); PiiEngine engine; engine.addOperation("PiiObjectCounter", "counter"); engine.save("counter_engine.cft"); } catch (PiiException& ex) { // handle errors here }
Exceptions
- PiiException&
-
if fileName cannot be opened for writing
- PiiSerializationException&
-
if the serialization of the engine fails for any reason.
-
PiiVersionNumber version
()Get the version of Into the plug-in was originally compiled and linked against.
-
~Plugin
() -
Ensures that plugin is loaded.
This function tries to load the plug-in is it is not yet loaded. Unlike loadPlugin(), this function doesn't increase the reference count of plug-ins that are already loaded.
Exceptions
- PiiLoadException&
-
if the plug-in cannot be loaded
-
Ensures that all plug-ins listed in plugins are loaded.
This function tries to load all plug-ins that are not yet loaded. Unlike loadPlugins(), this function doesn't increase the reference count of plug-ins that are already loaded.
Exceptions
- PiiLoadException&
-
if any of the plug-ins cannot be loaded
-
Returns
trueif the the plugin callednameis loaded andfalseotherwise. -
Loads a stored engine from fileName.
The stored configuration values will be written to config. Archive file format will be automatically recognized.
PiiVariantMap mapConfig; PiiEngine* pEngine = PiiEngine::load("counter_engine.cft", &mapConfig); QCOMPARE(mapConfig["application"].toString(), QString("Into"));
Exceptions
- PiiException&
-
if fileName cannot be opened for reading
- PiiLoadException&
-
if any of the required plug-ins cannot be loaded.
- PiiSerializationException&
-
if the archive type cannot be recognized or an error occurs when reading the engine instance.
-
Loads a plug-in into the engine.
The name of the plug-in is the name of the plug-in library file without a file name extension. For example, to load the flow control plug-in ({libpiiflowcontrol.so, piiflowcontrol.dll}), do this:
PiiEngine::loadPlugin("piiflowcontrol");
This will load the plug-in in the default plug-in location. In Unix, the plug-in library file
libpiiflowcontrol.sowill be searched inLD_LIBRARY_PATH. In Windows,piiflowcontrol.dllwill be searched inPATH. If the plug-in is located in another directory, either relative or absolute path names can be used. Use slash as the path separator (backslash will also work on Windows). Note that in this case you need to use the full file name (preferably without the extension, though).PiiEngine::loadPlugin("relative/path/to/libmyplugin"); PiiEngine::loadPlugin("/absolute/path/to/libmyotherplugin");
Plug-ins are always in process-wide use. It is not possible to load a plug-in to a single PiiEngine instance. Each plug-in is identified by its base name (see QFileInfo::baseName()). Thus, avoid using similar names even in separate directories.
Successive calls to loadPlugin() with the same plug-in name are OK. To really unload the plug-in one needs to issue the same number of unloadPlugin() calls.
This function is thread-safe.
Returns
Basic information about the loaded plug-in.
Exceptions
- PiiLoadException&
-
if the plug-in cannot be loaded
-
A convenience function that loads many plugins at once.
PiiEngine::loadPlugins(QStringList() << "piiimage" << "piibase");
Exceptions
- PiiLoadException&
-
if any of the plug-ins cannot be loaded
See also
-
Returns the library names of loaded plug-ins.
-
Returns the resource names of loaded plug-ins.
-
Returns loaded plug-ins.
-
Remove the named plugin.
Either the full path or the base name will do as name.
WARNING! Unloading plug-ins needs special attention. Make extremely sure that no instances of classes created by the plugin are in memory! Otherwise, all bets are off. If you have created an operation with PiiOperationCompound::createOperation(), detach and delete the operation from the engine before trying to unload the plugin.
This function is thread-safe.
Parameters
- name
- force
-
if
false, the plug-in will not be removed from the address space of the process until all loadPlugin() calls have been abrogated. Iftrue, a single call removes the plug-in irrespective of the number of references.
Returns
the number of references left
Add a note
Not a single note added yet. Be the first, add yours.