Yate: Engine Class Reference

Yate

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
Engine Class Reference

Engine globals. More...

`#include <yatengine.h>`

## Public Types
enum | RunMode { Stopped = 0 , Console = 1 , Server = 2 , Client = 3 , ClientProxy = 4 }
enum | CallAccept { Accept = 0 , Partial = 1 , Congestion = 2 , Reject = 3 }
enum | PluginMode { LoadFail = 0 , LoadLate , LoadEarly }

## Public Member Functions
int | engineInit ()
int | engineCleanup ()
int | run ()
bool | setHook (MessagePostHook *hook, bool remove=false)
int | usedPlugins ()
unsigned int | messageCount ()
unsigned int | handlerCount ()
unsigned int | postHookCount ()
unsigned int | messageRate () const
unsigned int | messageMaxRate () const
unsigned int | messageAge (bool usec=false) const
void | getStats (u_int64_t &enqueued, u_int64_t &dequeued, u_int64_t &dispatched, u_int64_t &queueMax)
void | resetMax ()
bool | pluginLoaded (const String &name) const
bool | loadPluginDir (const String &relPath)

## Static Public Member Functions
static int | main (int argc, const char **argv, const char **env, RunMode mode=Console, EngineLoop loop=0, bool fail=false)
static void | help (bool client, bool errout=false)
static Engine * | self ()
static RunMode | mode ()
static CallAccept | accept ()
static void | setAccept (CallAccept ca)
static const TokenDict * | getCallAcceptStates ()
static void | setCongestion (const char *reason=0)
static unsigned int | getCongestion ()
static bool | clientMode ()
static bool | Register (const Plugin *plugin, bool reg=true)
static const String & | nodeName ()
static const String & | sharedPath ()
static String | configFile (const char *name, bool user=false)
static const String & | configPath (bool user=false)
static const String & | configSuffix ()
static const String & | modulePath ()
static void | extraPath (const String &path)
static void | userPath (const String &path)
static const String & | moduleSuffix ()
static const char * | pathSeparator ()
static const Configuration & | config ()
static unsigned int | runId ()
static const NamedList & | runParams ()
static void | init ()
static bool | init (const String &name)
static void | halt (unsigned int code)
static bool | restart (unsigned int code, bool gracefull=false)
static bool | started ()
static bool | exiting ()
static bool | install (MessageHandler *handler)
static bool | uninstall (MessageHandler *handler)
static bool | enqueue (Message *msg, bool skipHooks=false)
static bool | enqueue (const char *name, bool broadcast=false)
static bool | dispatch (Message *msg)
static bool | dispatch (Message &msg)
static bool | dispatch (const char *name, bool broadcast=false)
static const String & | trackParam ()
static bool | installHook (MessageHook *hook)
static void | uninstallHook (MessageHook *hook)
static void | pluginMode (PluginMode mode)
static const ObjList * | events (const String &type)
static void | clearEvents (const String &type)
static SharedVars & | sharedVars ()
static void | buildCmdLine (String &line)
static void | initLibrary (const String &line, String *output=0)
static int | cleanupLibrary ()
static MessageDispatcher * | dispatcher ()

## Protected Member Functions
| ~Engine ()
bool | loadPlugin (const char *file, bool local=false, bool nounload=false)
void | loadPlugins ()
void | initPlugins ()

## Friends
class | EnginePrivate
class | EngineCommand

## Detailed Description

Engine globals.

This class holds global information about the engine. Note: this is a singleton class.

## Member Enumeration Documentation

## ◆ PluginMode

enum PluginMode

Plugin load and initialization modes. Default is LoadLate that initailizes the plugin after others. LoadEarly will move the plugin to the front of the init order. LoadFail causes the plugin to be unloaded.

## ◆ RunMode

enum RunMode

Running modes - run the engine as Console, Client or Server.

## Constructor & Destructor Documentation

## ◆ ~Engine()

~Engine | ( |  | ) |
| protected

Destroys the engine and everything. You must not call it directly, run() will do it for you.

## Member Function Documentation

## ◆ accept()

static CallAccept accept | ( |  | ) |
| inlinestatic

Get call accept status

Returns
  Engine's call accept status as enumerated value

## ◆ buildCmdLine()

static void buildCmdLine | ( | String & | line | ) |
| static

Append command line arguments form current config. The following parameters are added: -Dads, -v, -q, Debugger timestamp. This method should be used when starting another libyate based application

Parameters

  line | Destination string

## ◆ cleanupLibrary()

static int cleanupLibrary | ( |  | ) |
| static

Cleanup library. Set late abort, kill all threads. This method should be used in cleanup stage of libyate based applications

Returns
  Halt code

## ◆ clearEvents()

static void clearEvents | ( | const String & | type | ) |
| static

Clear the list of captured events of a specific type

Parameters

  type | Type of captured events, an empty name clear engine events

## ◆ clientMode()

static bool clientMode | ( |  | ) |
| inlinestatic

Check if the engine is running as telephony client

Returns
  True if the engine is running in client mode

## ◆ config()

static const Configuration & config | ( |  | ) |
| static

The global configuration of the engine. You must use this resource with caution. Note that sections [general], [modules], [preload] and [postload] are reserved by the engine. Also [telephony] is reserved by the drivers.

Returns
  A reference to the read-only engine configuration

## ◆ configFile()

static String configFile | ( | const char * | name,
|  | bool | user = false )
| static

Get the filename for a specific configuration

Parameters

  name | Name of the configuration requested
  user | True to build a user settings path

Returns
  A full path configuration file name

## ◆ configPath()

static const String & configPath | ( | bool | user = false | ) |
| static

Get the system or user configuration directory path

Parameters

  user | True to get the user settings path

Returns
  The directory path for system or user configuration files

## ◆ configSuffix()

static const String & configSuffix | ( |  | ) |
| inlinestatic

Get the configuration file suffix

Returns
  The suffix for configuration files

## ◆ dispatch() [1/3]

static bool dispatch | ( | const char * | name,
|  | bool | broadcast = false )
| static

Convenience function. Dispatch a parameterless message to the registered handlers

Parameters

  name | The name of the message to create and dispatch
  broadcast | Broadcast flag, true if handling the mesage must not stop it

Returns
  True if one handler accepted it, false if all ignored

## ◆ dispatch() [2/3]

static bool dispatch | ( | Message & | msg | ) |
| static

Synchronously dispatch a message to the registered handlers

Parameters

  msg | The message to dispatch

Returns
  True if one handler accepted it, false if all ignored

## ◆ dispatch() [3/3]

static bool dispatch | ( | Message * | msg | ) |
| static

Synchronously dispatch a message to the registered handlers

Parameters

  msg | Pointer to the message to dispatch

Returns
  True if one handler accepted it, false if all ignored

## ◆ dispatcher()

static MessageDispatcher * dispatcher | ( |  | ) |
| inlinestatic

Retrieve common Engine dispatcher

Returns
  MessageDispatcher pointer, NULL if not set

## ◆ engineCleanup()

int engineCleanup | ( |  | ) |

Do engine cleanup

Returns
  Error code, 0 for success

## ◆ engineInit()

int engineInit | ( |  | ) |

Initialize the engine

Returns
  Error code, 0 for success

## ◆ enqueue() [1/2]

static bool enqueue | ( | const char * | name,
|  | bool | broadcast = false )
| inlinestatic

Convenience function. Enqueue a new parameterless message in the message queue

Parameters

  name | Name of the parameterless message to put in queue
  broadcast | Broadcast flag, true if handling the mesage must not stop it

Returns
  True if enqueued, false on error (already queued)

References Engine::enqueue().

## ◆ enqueue() [2/2]

static bool enqueue | ( | Message * | msg,
|  | bool | skipHooks = false )
| static

Enqueue a message in the message queue for asynchronous dispatching

Parameters

  msg | The message to enqueue, will be destroyed after dispatching
  skipHooks | True to append the message directly into the main queue

Returns
  True if enqueued, false on error (already queued)

Referenced by Engine::enqueue().

## ◆ events()

static const ObjList * events | ( | const String & | type | ) |
| static

Retrive the list of captured events of a specific type

Parameters

  type | Type of captured events, an empty name returns engine events

Returns
  List containing captured events of specified type, NULL if not found

## ◆ exiting()

static bool exiting | ( |  | ) |
| inlinestatic

Check if the engine is currently exiting

Returns
  True if exiting, false in normal operation

Referenced by Client::valid().

## ◆ extraPath()

static void extraPath | ( | const String & | path | ) |
| static

Add a relative extra module loading path. The list is empty by default but can be filled by a main program before calling main()

Parameters

  path | Relative path to extra modules to be loaded

## ◆ getCallAcceptStates()

static const TokenDict * getCallAcceptStates | ( |  | ) |
| inlinestatic

Get call accept states

Returns
  states Pointer to the call accept states TokenDict

## ◆ getCongestion()

static unsigned int getCongestion | ( |  | ) |
| inlinestatic

Get the congestion state counter

Returns
  Zero if not congested else the number of congested components

## ◆ getStats()

void getStats | ( | u_int64_t & | enqueued,
|  | u_int64_t & | dequeued,
|  | u_int64_t & | dispatched,
|  | u_int64_t & | queueMax )
| inline

Retrieve dispatcher's statistics counters

Parameters

  enqueued | Returns count of enqueued messages
  dequeued | Returns count of dequeued messages
  dispatched | Returns count of all dispatched messages, including dequeued ones
  queueMax | Returns queued high watermark

References MessageDispatcher::getStats().

## ◆ halt()

static void halt | ( | unsigned int | code | ) |
| static

Stop the engine and the entire program

Parameters

  code | Return code of the program

## ◆ handlerCount()

unsigned int handlerCount | ( |  | ) |
| inline

Get the number of handlers in the dispatcher

Returns
  Count of handlers

References MessageDispatcher::handlerCount().

## ◆ help()

static void help | ( | bool | client,
|  | bool | errout = false )
| static

Display the help information on console

Parameters

  client | Display help for client running mode
  errout | Display on stderr intead of stdout

## ◆ init() [1/2]

static void init | ( |  | ) |
| static

Reinitialize the plugins

## ◆ init() [2/2]

static bool init | ( | const String & | name | ) |
| static

Reinitialize one plugin

Parameters

  name | Name of the plugin to initialize, emplty, "*" or "all" to initialize all

Returns
  True if plugin(s) were reinitialized

## ◆ initLibrary()

static void initLibrary | ( | const String & | line,
|  | String * | output = 0 )
| static

Initialize library from command line arguments. Enable debugger output. This method should be used in initialization stage of libyate based applications

Parameters

  line | Command line arguments string
  output | Optional string to be filled with invalid argument errors or any output to be displyed later

## ◆ initPlugins()

void initPlugins | ( |  | ) |
| protected

Initialize all registered plugins

## ◆ install()

static bool install | ( | MessageHandler * | handler | ) |
| static

Installs a handler in the dispatcher.

Parameters

  handler | A pointer to the handler to install

Returns
  True on success, false on failure

## ◆ installHook()

static bool installHook | ( | MessageHook * | hook | ) |
| static

Appends a new message hook to the hooks list.

Parameters

  hook | The message hook to append.

Returns
  True if the message hook was successfully appended to the hooks list

## ◆ loadPlugin()

bool loadPlugin | ( | const char * | file,
|  | bool | local = false,
|  | bool | nounload = false )
| protected

Loads one plugin from a shared object file

Parameters

  file | Name of the plugin file to load
  local | Attempt to keep symbols local if supported by the system
  nounload | Never unload the module from memory, finalize if possible

Returns
  True if success, false on failure

## ◆ loadPluginDir()

bool loadPluginDir | ( | const String & | relPath | ) |

Loads the plugins from an extra plugins directory or just an extra plugin

Parameters

  relPath | Path to the extra directory, relative to the main modules

Returns
  True if the plugin was loaded or the directory could at least be opened

## ◆ loadPlugins()

void loadPlugins | ( |  | ) |
| protected

Loads the plugins from the plugins directory

## ◆ main()

static int main | ( | int | argc,
|  | const char ** | argv,
|  | const char ** | env,
|  | RunMode | mode = Console,
|  | EngineLoop | loop = 0,
|  | bool | fail = false )
| static

Main entry point to be called directly from a wrapper program

Parameters

  argc | Argument count
  argv | Argument array
  env | Environment variables
  mode | Mode the engine must run as - Console, Client or Server
  loop | Callback function to the main thread's loop
  fail | Fail and return after parsing command line arguments

Returns
  Program exit code

## ◆ messageAge()

unsigned int messageAge | ( | bool | usec = false | ) | const
| inline

Get the average dequeued message age in milliseconds or microseconds

Parameters

  usec | True to return microseconds instead of milliseconds

Returns
  Average age of dequeued messages

References MessageDispatcher::messageAge().

## ◆ messageCount()

unsigned int messageCount | ( |  | ) |
| inline

Get the number of messages waiting in the queue

Returns
  Count of messages in the queue

References MessageDispatcher::messageCount().

## ◆ messageMaxRate()

unsigned int messageMaxRate | ( |  | ) | const
| inline

Get the maximum rate of dispatched messages per second

Returns
  Maximum number of messages dispatched per second

## ◆ messageRate()

unsigned int messageRate | ( |  | ) | const
| inline

Get the rate of dispatched messages per second

Returns
  Number of messages dispatched in the last second

## ◆ mode()

static RunMode mode | ( |  | ) |
| inlinestatic

Get the running mode of the engine

Returns
  Engine's run mode as enumerated value

## ◆ modulePath()

static const String & modulePath | ( |  | ) |
| inlinestatic

The module loading path

## ◆ moduleSuffix()

static const String & moduleSuffix | ( |  | ) |
| inlinestatic

Get the module filename suffix

Returns
  The suffix for module files

## ◆ nodeName()

static const String & nodeName | ( |  | ) |
| inlinestatic

Get the server node name, should be unique in a cluster

Returns
  Node identifier string, defaults to host name

## ◆ pathSeparator()

static const char * pathSeparator | ( |  | ) |
| static

Get the canonical path element separator for the operating system

Returns
  The operating system specific path element separator

## ◆ pluginLoaded()

bool pluginLoaded | ( | const String & | name | ) | const
| inline

Check if a plugin is currently loaded

Parameters

  name | Name of the plugin to check

Returns
  True if the named plugin is loaded

## ◆ pluginMode()

static void pluginMode | ( | PluginMode | mode | ) |
| static

Set the load and init mode of the currently loading Plugin

Parameters

  mode | Load and init mode, default LoadLate

## ◆ postHookCount()

unsigned int postHookCount | ( |  | ) |
| inline

Get the number of post-handling hooks in the dispatcher

Returns
  Count of hooks

References MessageDispatcher::postHookCount().

## ◆ Register()

static bool Register | ( | const Plugin * | plugin,
|  | bool | reg = true )
| static

Register or unregister a plugin to the engine.

Parameters

  plugin | A pointer to the plugin to (un)register
  reg | True to register (default), false to unregister

Returns
  True on success, false on failure

## ◆ resetMax()

void resetMax | ( |  | ) |
| inline

Reset the high water mark of the stat counters

References MessageDispatcher::messageCount().

## ◆ restart()

static bool restart | ( | unsigned int | code,
|  | bool | gracefull = false )
| static

Stop and restart the engine and the entire program

Parameters

  code | Return code of the program
  gracefull | Attempt to wait until no plugin is busy

Returns
  True if restart was initiated, false if exiting or no supervisor

## ◆ run()

int run | ( |  | ) |

Run the engine.

Returns
  Error code, 0 for success

## ◆ runId()

static unsigned int runId | ( |  | ) |
| static

Get a - supposedly unique - instance ID

Returns
  Unique ID of the current running instance

## ◆ runParams()

static const NamedList & runParams | ( |  | ) |
| inlinestatic

Get the engine parameters specific to this run.

Returns
  A reference to the list of run specific parameters

## ◆ self()

static Engine * self | ( |  | ) |
| static

Get a pointer to the unique instance.

Returns
  A pointer to the singleton instance of the engine

## ◆ setAccept()

static void setAccept | ( | CallAccept | ca | ) |
| inlinestatic

Set call accept status

Parameters

  ca | New call accept status as enumerated value

## ◆ setCongestion()

static void setCongestion | ( | const char * | reason = 0 | ) |
| static

Alter the congestion state counter.

Parameters

  reason | Reason to enter congested state, NULL to leave congestion

## ◆ setHook()

bool setHook | ( | MessagePostHook * | hook,
|  | bool | remove = false )
| inline

Install or remove a hook to catch messages after being dispatched

Parameters

  hook | Pointer to a post-dispatching message hook
  remove | Set to True to remove the hook instead of adding

Returns
  True on success, false on failure (may fail if already found in the list)

References MessageDispatcher::setHook().

## ◆ sharedPath()

static const String & sharedPath | ( |  | ) |
| inlinestatic

Get the application's shared directory path

Returns
  The base path for shared files and directories

## ◆ sharedVars()

static SharedVars & sharedVars | ( |  | ) |
| static

Access the engine's shared variables

Returns
  Reference to the static variables shared between modules

## ◆ started()

static bool started | ( |  | ) |
| inlinestatic

Check if the engine was started

Returns
  True if the engine has gone through the start phase

## ◆ trackParam()

static const String & trackParam | ( |  | ) |
| inlinestatic

Retrieve the tracker parameter name

Returns
  Name of the parameter used to track message dispatching

References String::empty(), and MessageDispatcher::trackParam().

## ◆ uninstall()

static bool uninstall | ( | MessageHandler * | handler | ) |
| static

Uninstalls a handler drom the dispatcher.

Parameters

  handler | A pointer to the handler to uninstall

Returns
  True on success, false on failure

## ◆ uninstallHook()

static void uninstallHook | ( | MessageHook * | hook | ) |
| static

Remove a message hook from the hooks list.

Parameters

  hook | The hook to remove.

## ◆ usedPlugins()

int usedPlugins | ( |  | ) |

Get a count of plugins that are actively in use

Returns
  Count of plugins in use

## ◆ userPath()

static void userPath | ( | const String & | path | ) |
| static

Set the per user application data path. This method must be called by a main program before calling main() or help() Path separators are not allowed. The default is taken from CFG_DIR.

Parameters

  path | Single relative path component to write user specific data

The documentation for this class was generated from the following file:

- yatengine.h