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 ()
void	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)
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 ()

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

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.

enum RunMode

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

Constructor & Destructor Documentation

~Engine ( )

protected

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

Member Function Documentation

static CallAccept accept ( )

inlinestatic

Get call accept status

Returns

Engine's call accept status as enumerated value

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

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

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

static bool clientMode ( )

inlinestatic

Check if the engine is running as telephony client

Returns

True if the engine is running in client mode

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

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

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

static const String& configSuffix ( )

inlinestatic

Get the configuration file suffix

Returns

The suffix for configuration files

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

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

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

int engineCleanup

(

)

Do engine cleanup

Returns

Error code, 0 for success

int engineInit

(

)

Initialize the engine

Returns

Error code, 0 for success

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().

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().

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

static bool exiting ( )

inlinestatic

Check if the engine is currently exiting

Returns

True if exiting, false in normal operation

Referenced by Client::valid().

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

static const TokenDict* getCallAcceptStates ( )

inlinestatic

Get call accept states

Returns

states Pointer to the call accept states TokenDict

static unsigned int getCongestion ( )

inlinestatic

Get the congestion state counter

Returns

Zero if not congested else the number of congested components

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().

static void halt ( unsigned int  code )

static

Stop the engine and the entire program

Parameters

code	Return code of the program

unsigned int handlerCount ( )

inline

Get the number of handlers in the dispatcher

Returns

Count of handlers

References MessageDispatcher::handlerCount().

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

static void init ( )

static

Reinitialize the plugins

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

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

void initPlugins ( )

protected

Initialize all registered plugins

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

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

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

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

void loadPlugins ( )

protected

Loads the plugins from the plugins directory

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

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().

unsigned int messageCount ( )

inline

Get the number of messages waiting in the queue

Returns

Count of messages in the queue

References MessageDispatcher::messageCount().

unsigned int messageMaxRate ( ) const

inline

Get the maximum rate of dispatched messages per second

Returns

Maximum number of messages dispatched per second

unsigned int messageRate ( ) const

inline

Get the rate of dispatched messages per second

Returns

Number of messages dispatched in the last second

static RunMode mode ( )

inlinestatic

Get the running mode of the engine

Returns

Engine's run mode as enumerated value

static const String& modulePath ( )

inlinestatic

The module loading path

static const String& moduleSuffix ( )

inlinestatic

Get the module filename suffix

Returns

The suffix for module files

static const String& nodeName ( )

inlinestatic

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

Returns

Node identifier string, defaults to host name

static const char* pathSeparator ( )

static

Get the canonical path element separator for the operating system

Returns

The operating system specific path element separator

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

unsigned int postHookCount ( )

inline

Get the number of post-handling hooks in the dispatcher

Returns

Count of hooks

References MessageDispatcher::postHookCount().

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

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

int run

(

)

Run the engine.

Returns

Error code, 0 for success

static unsigned int runId ( )

static

Get a - supposedly unique - instance ID

Returns

Unique ID of the current running instance

static const NamedList& runParams ( )

inlinestatic

Get the engine parameters specific to this run.

Returns

A reference to the list of run specific parameters

static Engine* self ( )

static

Get a pointer to the unique instance.

Returns

A pointer to the singleton instance of the engine

static void setAccept ( CallAccept  ca )

inlinestatic

Set call accept status

Parameters

ca	New call accept status as enumerated value

static void setCongestion ( const char *  reason = 0 )

static

Alter the congestion state counter.

Parameters

reason

Reason to enter congested state, NULL to leave congestion

void 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

References MessageDispatcher::setHook().

static const String& sharedPath ( )

inlinestatic

Get the application's shared directory path

Returns

The base path for shared files and directories

static SharedVars& sharedVars ( )

static

Access the engine's shared variables

Returns

Reference to the static variables shared between modules

static bool started ( )

inlinestatic

Check if the engine was started

Returns

True if the engine has gone through the start phase

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().

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

static void uninstallHook ( MessageHook *  hook )

static

Remove a message hook from the hooks list.

Parameters

hook	The hook to remove.

int usedPlugins

(

)

Get a count of plugins that are actively in use

Returns

Count of plugins in use

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