Module manager facilities

---

Detailed Description

RHexLib provides simple means for defining tasks that need to be performed periodically. Following initialization, all RHexLib programs surrender control to the "module manager", which performs synchronous scheduling of periodic tasks defined through instantiations of the Module class. All module manager functionality is accessed through a collection of functions (all prefixed with "MM"), described in this section.

The Module abstract base class defines a template for periodic tasks that can be defined by a RHexLib programmer. Defining such a task involves deriving a class from Module, and providing implementations for its methods Module::init, Module::uninit, Module::activate, Module::deactivate and Module::update. In particular, the update method is periodically called by the module manager and defines the core functionality of the module.

The module manager maintains a database of currently recognized modules. Each module in the database is uniquely identified with its name and index, specified through its constructor Module::Module. Usually, the functions MMAddModule and MMRemoveModule are called from within main() to initialize this database. The MMFindModule function can be used to query this database.

The execution properties of a module are parametrized with three quantities: period, offset and order. As noted before, the module manager is a "synchronous" scheduler. As such, it divides time into "steps" of equal duration (usually 1ms), and schedules module updates within these slots. Both the period and offset of a module are integers corresponding to these steps and respectively specify the periodicity of module updates and the beginning time offset of the first update (for periods larger than 1). Finally if multiple modules are to be updated in the same step, the order parameter determines the execution order with lower values having higher priority. These parameters can be specified through the MMAddModule function call.

Modules can be activated and deactivated through the functions MMActivateModule and MMDeactivateModule. However, it is much better practice to use the functions MMGrabModule and MMReleaseModule instead as they provide access control and reference counting for activation and deactivation. These two functions provide reliable means of resource management for modules.

The function MMMainLoop must be called from main() to transfer execution control to the module manager. Beyond that point, module scheduling starts and the module manager retains execution control until either MMShutdown or MMPowerOff are explicitly called from within module methods.

The module manager also provides message facilities either through the console display or through a network connection to a message logger client. The functions MMMessage, MMWarning and MMFatalError can be used to issue messages at various levels of priority and severity.

The following configuration file symbols are recognized by the module manager:

• int mm_update_period: Time in between two module updates, given in microseconds. This determines the fundamental frequency of module updates.
• float mm_mainloop_prio: QNX process execution priority for the main module manager loop.
• float mm_min_idle_time: Minimum idle time per step to be left unused by the main module manager loop process (seconds). This feature ensures that enough time is left for other systems processes such as communications and serial device access.
• float mm_profile_enable: When nonzero, enables execution profiling for module updates.
• string mm_profile_filename: When module execution profiling is enabled, this variable specifies the output filename for execution statistics.
• float mm_msglog_enable: When nonzero, enables logging of module manager messages to a local file on the hard disk.
• string mm_log_filename: When local message logging is enabled, thois variable spacifies the message dump filename.
• float mm_log_priority: When local message logging is enabled, this variable specifies the priority threshold for message filtering.

Compounds
class	Module
	Interface class for periodic tasks. More...
Functions
void	MMAddModule (Module *m, MM_STEP period, MM_STEP offset, int order)
void	MMRemoveModule (Module *m)
Module *	MMFindModule (char *n, int ind)
void	MMActivateModule (Module *m)
void	MMDeactivateModule (Module *m)
void	MMGrabModule (Module *m, Module *ask)
void	MMReleaseModule (Module *m, Module *ask)
void	MMMainLoop (void)
void	MMShutdown (void)
void	MMPowerOff (void)
void	MMExitMainLoop (void)

---

Function Documentation

void MMActivateModule (  Module *  m  )  [inline]

This function puts the specified module in the ACTIVE state and calls its Module::activate method. As a consequence, the module is activated and periodic execution of its Module::update method will start.

void MMAddModule (  Module *  m, MM_STEP  period, MM_STEP  offset, int  order )  [inline]

This function is used to add a module instance to the module manager's database. The period, offset and order of the module are also specified through this function and cannot be changed unless the module is removed and readded.

void MMDeactivateModule (  Module *  m  )  [inline]

This function puts the specified module in the INACTIVE state and calls its Module::deactivate method. As a consequence, the module is deactivated and its Module::update method will no longer be called.

void MMExitMainLoop (  void   )  [inline]

This function causes MMMainLoop function call to return without deactivating any module. Clean shutdown must be manually performed for a graceful exit.

Module* MMFindModule (  char *  n, int  ind )  [inline]

This function can be used to query the module manager's database for a module with the specified name and index. Each module is uniquely identified with its string name and integer index.

void MMGrabModule (  Module *  m, Module *  ask )  [inline]

This function is similar to MMActivateModule except that it performs access control and an activation count. Single user modules can be grabbed only once. For multiple user modules, the first call to this method causes activation.

void MMMainLoop (  void   )  [inline]

Following initialization, all RHexLib programs must call this function to transfer execution control to the module manager. This function returns only when MMShutdown is explicitly called, in which case the program must perform cleanup and exit.

void MMPowerOff (  void   )  [inline]

This method deactivates all modules and immediately terminates execution. It is usually called when graceful shutdown is not possible.

void MMReleaseModule (  Module *  m, Module *  ask )  [inline]

This function is similar to MMDeactivateModule except that it performs access control and an activation count. A module is deactivated only when it has been released as many times as it was grabbed.

void MMRemoveModule (  Module *  m  )  [inline]

This function is used to remove a module from the module manager's database.

void MMShutdown (  void   )  [inline]

This method deactivates and releases all modules and causes the MMMainLoop function call to return. Usually, this method is called by an individual module when an event requiring graceful termination of execution is detected.

---

RHexLib Reference Documentation