Into

Modules

Documentation

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 &
(
  • const Plugin & other
)
( )
(
  • const Plugin & other
)

Get the resource name of the plug-in.

void
(
  • const QString & fileName
  • const QVariantMap & config = QVariantMap()
  • FileFormat format = TextFormat
)

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 true if the the plugin called name is loaded and false otherwise.

static PiiEngine *
(
  • const QString & fileName
  • QVariantMap * config = 0
)

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
(
  • const QString & name
  • bool force = false
)

Remove the named plugin.

Friends

friend struct

Enumeration details

Function details

  • PiiEngine

    ()

    Constructs a new PiiEngine.

  • ~PiiEngine

    ()

    Destroys the engine.

  • virtual Q_INVOKABLE PiiEngine * clone

    ()
    [virtual]

    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 Stopped nor Paused, 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 the plugins key, 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. If application is not given, the current Into version will be used.

    One may store any application-specific configuration values to the map.
     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

    ()
  • static void ensurePlugin

    ( )
    [static]

    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

  • static void ensurePlugins

    ( )
    [static]

    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

  • static bool isLoaded

    ( )
    [static]

    Returns true if the the plugin called name is loaded and false otherwise.

  • static PiiEngine * load

    (
    • const QString & fileName
    • QVariantMap * config = 0
    )
    [static]

    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.

  • static Plugin loadPlugin

    ( )
    [static]

    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.so will be searched in LD_LIBRARY_PATH. In Windows, piiflowcontrol.dll will be searched in PATH. 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

  • static void loadPlugins

    ( )
    [static]

    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
  • static QStringList pluginLibraryNames

    ()
    [static]

    Returns the library names of loaded plug-ins.

  • static QStringList pluginResourceNames

    ()
    [static]

    Returns the resource names of loaded plug-ins.

  • static QList< Plugin > plugins

    ()
    [static]

    Returns loaded plug-ins.

  • static int unloadPlugin

    (
    • const QString & name
    • bool force = false
    )
    [static]

    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. If true, a single call removes the plug-in irrespective of the number of references.

    Returns

    the number of references left

Notes (0)

Add a note

Not a single note added yet. Be the first, add yours.