#include <module.h>
Inheritance diagram for modules::Module:
Public Types | |
enum | { mnNone = 0, mnLoaded = 1, mnStarted = 2, mnStopped = 3, mnSync = 4, mnReconfig = 5, mnCoreDefined = 512, mnUserDefined = 4096 } |
Notification messages for the notify() function. More... | |
enum | { msLoaded = 0x1, msStarted = 0x2 } |
Module state bits. More... | |
Public Member Functions | |
virtual int | version () const=0 |
Returns the module version number. | |
Module (std::string const &name, std::string const &description, std::string const &author="", std::string const &url="") | |
Constructor. | |
virtual | ~Module () |
Destructor. | |
virtual conf::ConfQ * | config (Core &core, conf::ConfGlobalQ &global) |
Returns configuration information. | |
virtual Interface * | factory (PSIID iid) |
Retrieves an interface object exposed by the module. | |
virtual Interface * | interface (PSIID iid) |
Retrieves an interface object exposed by the module. | |
virtual bool | load (Core &core) |
Loads the module. | |
ssize_t | memory_usage () const |
Returns information about module's memory usage. | |
virtual void | notify (Module &sender, int msg, void *arg) |
Notifies a message to a module. | |
virtual bool | query (std::string const &query, std::string &feedback) |
Queries a module. | |
virtual void | start (Core &core) |
Starts the module. | |
virtual bool | stop (Core &core) |
Stops the module. | |
virtual void | unload (Core &core) |
Unloads the module. | |
virtual std::string const & | name () const |
Returns the module name. | |
virtual std::string const & | description () const |
Returns the module description. | |
virtual std::string const & | author () const |
Returns the module author. | |
virtual std::string const & | url () const |
Returns the module URL (where new versions can be found.). | |
int | references () const |
Returns the reference count. | |
int | references_add () |
Adds a reference to the module. | |
int | references_remove () |
Removes a reference to the module. | |
virtual int | state () const |
Returns the module state. | |
void * | data () const |
Returns the data set by the module manager. | |
void | data (void *data) |
Sets arbitrary data (for use by the module manager only!). | |
Protected Attributes | |
std::string | m_name |
The module name. | |
std::string | m_description |
The module description. | |
std::string | m_author |
The module author. | |
std::string | m_url |
The module URL. | |
int | m_references |
The module reference count. | |
int | m_state |
The module state. |
The version() function must be overriden in derived classes. The config(), factory(), interface(), load(), memory_usage(), notify(), query(), start(), stop() and unload() functions are possible candidates as well.
The module manager calls the functions in the following order to load and start a module:
The module manager calls the functions in the following order to stop and unload a module:
When the program stops (or restarts), the stop() function is called for each module in the reverse order they were started. unload() is NOT called and there is NO notification sent so everything vital (saving data, etc.) MUST be done by the stop() function, while cleaning up (such as removing hooks and references or freeing memory) may be left out of it as the program will stop anyway.
anonymous enum |
mnNone | Don't use. |
mnLoaded | The module is loaded. |
mnStarted | The module is started. |
mnStopped | The module is stopped. |
mnSync |
The module must sync.
This message is generally handled only by database modules. They must sync their databases when they receive it (whatever that means, if anything, is up to them). |
mnReconfig |
All modules have been reconfigured.
This message is sent when the configuration files for all modules have been reloaded. The sender is the core module. |
mnCoreDefined | Core-defined messages will be (mnCoreDefined + x). |
mnUserDefined | User-defined messages must be (mnUserDefined + x). |
anonymous enum |
msLoaded | The module is loaded, ready to be "hooked" by other modules. |
msStarted | The module is started. |
modules::Module::Module | ( | std::string const & | name, | |
std::string const & | description, | |||
std::string const & | author = "" , |
|||
std::string const & | url = "" | |||
) | [inline] |
Module constructor that sets the module name and description.
[in] | name | The module name (must be the same as the shared library filename, with no extension). |
[in] | description | The module description, whose contents can be freely chosen by the module developer. |
[in] | author | The author of the module's name (for informative purpose only). |
[in] | url | An URL where information about the module and latest versions can be found (for informative purpose only). |
virtual int modules::Module::version | ( | ) | const [pure virtual] |
Returns the module version number, which must be a hexadecimal number of the following format:
0xMMmmRRRR
where MM is the major version number, mm the minor version number and RRRR the release number.
Example: 0x01050010 => 1.5.16
Modules should check the version number of other modules they use to ensure that their version is the same as the one for which the module was compiled.
Implemented in core::Epona.
virtual conf::ConfQ* modules::Module::config | ( | Core & | core, | |
conf::ConfGlobalQ & | global | |||
) | [inline, virtual] |
Returns configuration information, in the form of a conf::ConfQ parser filled with configuration directives that will be used to configure the module.
[in] | core | The core module. |
[in] | global | The ConfGlobalQ object to which you can add global directives, variables and include paths. |
Reimplemented in core::Epona.
Retrieves an interface object exposed by the module, using an unique identifier.
[in] | iid | The interface identifier. |
Retrieves an interface object exposed by the module, using an unique identifier.
[in] | iid | The interface identifier. |
virtual bool modules::Module::load | ( | Core & | core | ) | [virtual] |
Asks the module to load itself. When this function returns, the module must be ready to get "hooked" (that is, used by other modules) and the msLoaded bit must have been added to the module state.
This function is also ideal to ensure other modules you'll need are there and load them if not (but don't add references or hook other modules -- wait until the notify() function is called later). Modules loaded in this function are guaranteed to be started BEFORE this module starts, which may be useful.
The load() function inherited from Module just changes the module state and returns true.
ssize_t modules::Module::memory_usage | ( | ) | const [inline] |
Returns information about module's memory usage.
virtual void modules::Module::notify | ( | Module & | sender, | |
int | msg, | |||
void * | arg | |||
) | [inline, virtual] |
Notifies a message to a module, described by the message number and parameter. The function must ignore all messages it doesn't recognize.
[in] | sender | The module that sent the notification. |
[in] | msg | The notification message. The standard messages are:
|
[in] | arg | An optional parameter that may be used by the sender to pass additional data. |
virtual bool modules::Module::query | ( | std::string const & | query, | |
std::string & | feedback | |||
) | [inline, virtual] |
Queries a module. This function may be used to pass special module-defined commands to the modules for it to execute, with feedback.
The default implementation always returns false.
[in] | query | The query that must be executed by the module. What possible queries are and how they're interpreted is entirely left to the choice of the module writer. There are no standard queries. |
[out] | feedback | A feedback string should be set by the implementer to this parameter before returning, if the query is supported. It can be an empty string; in that case, the caller should consider that the module didn't provide any feedback. |
virtual void modules::Module::start | ( | Core & | core | ) | [virtual] |
Asks the module to start itself. The module state must be updated accordingly. What the module does in this function is completely free.
This function must either success or the Core::fatal() function must be called.
The start() function inherited from Module just changes the module state.
virtual bool modules::Module::stop | ( | Core & | core | ) | [virtual] |
Asks the module to stop itself. The module must stop its operations and do any important task that needs to be done, such as saving data, as this is the only function that will be called when the program stops. Removing hooks and references and freeing memory, on the other hand, is better left to the notify() and unload() function since they're meaningless if the program will stop immediately.
The stop() function inherited from Module just changes the module state and returns true.
virtual void modules::Module::unload | ( | Core & | core | ) | [virtual] |
Asks the module to unload itself. The module must do all the remaining cleanup and update the state so that, if the load() was called afterwards, it would work perfectly.
This function must either success or the Core::fatal() function must be called.
The unload() function inherited from Module just changes the module state.
int modules::Module::references | ( | ) | const [inline] |
Returns the number of references that have been added to the module.
int modules::Module::references_add | ( | ) | [inline] |
When another module needs to prevent this module from being unloaded, it adds a reference through this function. A module can only be unloaded when its reference count is zero (it can be stopped regardless of it though -- for example when the program stops).
This function increments the reference count by one.
You should only add a reference when a module absolutely CAN'T continue without the module being referenced. If it still can work without it (perhaps with altered functionality), then it should not add a reference and watch for its unloading through the notify() function.
int modules::Module::references_remove | ( | ) | [inline] |
Removes a reference to the module (decreases the reference count by one).
virtual int modules::Module::state | ( | ) | const [inline, virtual] |