modules::Module Class Reference

Module base class. More...

#include <module.h>

Inheritance diagram for modules::Module:

modules::Core core::Epona List of all members.

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::ConfQconfig (Core &core, conf::ConfGlobalQ &global)
 Returns configuration information.
virtual Interfacefactory (PSIID iid)
 Retrieves an interface object exposed by the module.
virtual Interfaceinterface (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.

Detailed Description

This class is the base class for all modules. Each module must create a new class derived from it and use it as the class of their module object.

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.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
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
 

Enumerator:
msLoaded  The module is loaded, ready to be "hooked" by other modules.
msStarted  The module is started.


Constructor & Destructor Documentation

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.

Parameters:
[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).


Member Function Documentation

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.

Parameters:
[in] core The core module.
[in] global The ConfGlobalQ object to which you can add global directives, variables and include paths.
Returns:
A pointer to the configuration parser, or 0 if the module doesn't need to be configured.
See also:
conf::ConfQ

Reimplemented in core::Epona.

virtual Interface* modules::Module::factory PSIID  iid  )  [inline, virtual]
 

Retrieves an interface object exposed by the module, using an unique identifier.

Parameters:
[in] iid The interface identifier.
Returns:
A pointer to an object of the requested interface class, or 0 if the module doesn't expose an object of this interface. The object returned by this function is owned by the caller, which must free it whenever it's no longer needed. To get an object owned by the provider, use the interface() function. Note that modules are not required to provide an object of a given interface through the interface() function even if they provide it through this function.
See also:
Interface, interface()

virtual Interface* modules::Module::interface PSIID  iid  )  [inline, virtual]
 

Retrieves an interface object exposed by the module, using an unique identifier.

Parameters:
[in] iid The interface identifier.
Returns:
A pointer to an object of the requested interface class, or 0 if the module doesn't expose an object of this interface. The object returned by this function is owned by its module and must not be freed by the caller. To get an object owned by the caller, use the factory() function. Note that modules are not required to provide an object of a given interface through the factory() function even if they provide it through this function.
See also:
Interface, factory()

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.

Parameters:
[in] core The core module.
Returns:
true if successful, false otherwise (in the latter case, module will be released by the modules manager.)
See also:
notify()

ssize_t modules::Module::memory_usage  )  const [inline]
 

Returns information about module's memory usage.

Returns:
The module memory usage, expressed in bytes, or -1 if this information is unavailable (which is what does the default implementation).

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.

Parameters:
[in] sender The module that sent the notification.
[in] msg The notification message. The standard messages are:
  • mnLoaded: the module sending the message is loaded. You may now hook it or add references to it if you need to. After this module is loaded, this message is sent automatically once for each loaded module, including those that were loaded BEFORE this one.
  • mnStarted: the module sending the message is started. After this module is started, this message is sent automatically once for each loaded module, including those that were started BEFORE this one.
  • mnStopped: the module sending the message is stopped. You MUST remove clean up any hooks *and references* you set up previously. After this module is started, this message is sent automatically once for each stopped module. Additionally, you'll get this message for each module being started when this module is going to be unloaded, after stop() has been called.
[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.

Parameters:
[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.
Returns:
true if the query is supported (even if it was not successful), false otherwise.

int modules::Module::references  )  const [inline]
 

Returns the number of references that have been added to the module.

Returns:
The reference count.
See also:
references_add()

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.

Returns:
The new reference count.
See also:
notify()

int modules::Module::references_remove  )  [inline]
 

Removes a reference to the module (decreases the reference count by one).

Returns:
The new reference count.

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.

Parameters:
[in] core The core module.

virtual int modules::Module::state  )  const [inline, virtual]
 

Returns the module state, which is an OR'ed combination of any of the msLoaded or msStarted bits.

This helps other modules to determine whether a module is loaded or started and must be updated accordingly by the load(), start(), stop() and unload() functions.

Returns:
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.

Parameters:
[in] core The core module.
Returns:
true if successful, false otherwise (in that case, module unloading will fail there, so it's better to not return false unless it's a temporary error and module operation can continue; the return value is ignored when the program stops).

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.

Parameters:
[in] core The core module.

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.


The documentation for this class was generated from the following file:
Generated on Sun May 20 21:32:21 2007 for Epona API by  doxygen 1.4.6