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)

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

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

◆ 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 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 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

◆ 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

◆ 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

References mode().

◆ 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

◆ messageCount()

unsigned int messageCount ( )

inline

Get the number of messages waiting in the queue

Returns: Count of messages in the queue

◆ 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

Referenced by main(), and pluginMode().

◆ 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

References mode().

◆ postHookCount()

unsigned int postHookCount ( )

inline

Get the number of post-handling hooks in the dispatcher

Returns: Count of hooks

◆ 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

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

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

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

◆ 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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ PluginMode

◆ RunMode

Constructor & Destructor Documentation

◆ ~Engine()

Member Function Documentation

◆ accept()

◆ buildCmdLine()

◆ cleanupLibrary()

◆ clearEvents()

◆ clientMode()

◆ config()

◆ configFile()

◆ configPath()

◆ configSuffix()

◆ dispatch() [1/3]

◆ dispatch() [2/3]

◆ dispatch() [3/3]

◆ engineCleanup()

◆ engineInit()

◆ enqueue() [1/2]

◆ enqueue() [2/2]

◆ events()

◆ exiting()

◆ extraPath()

◆ getCallAcceptStates()

◆ getCongestion()

◆ getStats()

◆ halt()

◆ handlerCount()

◆ help()

◆ init() [1/2]

◆ init() [2/2]

◆ initLibrary()

◆ initPlugins()

◆ install()

◆ installHook()

◆ loadPlugin()

◆ loadPluginDir()

◆ loadPlugins()

◆ main()

◆ messageAge()

◆ messageCount()

◆ messageMaxRate()

◆ messageRate()

◆ mode()

◆ modulePath()

◆ moduleSuffix()

◆ nodeName()

◆ pathSeparator()

◆ pluginLoaded()

◆ pluginMode()

◆ postHookCount()

◆ Register()

◆ resetMax()

◆ restart()

◆ run()

◆ runId()

◆ runParams()

◆ self()

◆ setAccept()

◆ setCongestion()

◆ setHook()

◆ sharedPath()

◆ sharedVars()

◆ started()

◆ trackParam()

◆ uninstall()

◆ uninstallHook()

◆ usedPlugins()

◆ userPath()