| |
|
|
|
3 REFERENCE
This section contains the man pages for all the functions of EVH.
All the references to EVH(5) have to be intended as references to the OVERVIEW section of this document. EVH(5) is an introductory man page for the library and is a short version of the OVERVIEW. As a consequence it has not been printed in this section but is only available on-line.
3.1 Functions and classes
This section contains the man pages for all the functions and classes provided by evh.
The following diagram shows the hierarchy of the available classes
This class is part of the Event Handling Toolkit (see EVH(5)).
It is used to define callbacks, i.e. functions that have to be
executed by the event handler (see evhHANDLER(3)) when a specific
event occurrs.
A callback is identified by a couple (procedure,udata) where:
- procedure is a pointer to a function of type evhCB_PROC or
evhCB_PROC2.
- udata is a void* used to pass data to the procedure.
Whenever the Run() method is called (like in the main loop of an
event handler, when the corresponding event occurs), the "procedure"
function is executed, having as arguments a message passed in the
Run() function call end the void pointer stored in the evhCALLBACK.
The function callback must be of type evhCB_PROC or evhCB_PROC2, i.e.
must have a prototype in one of the following forms:
evhCB_COMPL_STAT procedure(const msgRAW_MESSAGE &msg, void* udata);
evhCB_COMPL_STAT procedure(const msgMESSAGE &msg, void* udata);
where: - msg is a reference to a message in the form of ECCS(5)
msgRAW_MESSAGE or msgMESSAGE.
- udata is a void pointer used to pass user data. It is of
type void* so that any data structure can be passed.
- evhCB_COMPL_STAT is the return value from the callback.
It is a bitmask, built by putting in OR some of the
following values:
evhCB_FAILURE success/failure of the procedure
evhCB_SUCCESS The default is SUCCESS
evhCB_NO_DELETE the callback must be deinstalled
evhCB_DELETE or not from the event handler,
The default is NO_DELETE
evhCB_RETURN the main loop must return immediately.
No other callback will be executed.
evhCB_NOCALLS Not for users. Used internally by
the main loop to comunicate that
no callback has been executed for
a certain event.
Here are some examples of return values:
evhCB_DELETE SUCCESS and delete
evhCB_DELETE | evhCB_SUCCESS SUCCESS and delete
evhCB_DELETE | evhCB_FAILURE FAILURE and delete
evhCB_DELETE | evhCB_FAILURE FAILURE and delete
evhCB_NO_DELETE SUCCESS and do not delete
evhCB_FAILURE FAILURE and do not delete
The base class eccsERROR_CLASS(3) provides services for error handling.
PUBLIC METHODS:
evhCALLBACK();
evhCALLBACK(const evhCB_PROC procedure,void *udata = NULL);
evhCALLBACK(const evhCB_PROC2 procedure,void *udata = NULL);
evhCALLBACK(const evhCALLBACK &source);
Contructors. The empty constructor assumes NULL both for
the procedure and udata.
If procedure is given, but is equal NULL, the eccsERR_NULL_PTR
error is generated.
evhCALLBACK &Proc(const evhCB_PROC procedure) ;
evhCALLBACK &Proc(const evhCB_PROC2 procedure) ;
To set/replace the callback procedure.
If procedure == NULL the error eccsERR_NULL_PTR is generated.
evhCALLBACK &UserData(void *udata);
To set/replace the udata
virtual int IsEqual( const fndOBJECT& ) const;
Overwrite of the standard method of fndOBJECT.
evhCALLBACK &operator =(const evhCALLBACK &source);
Assignement operator
virtual evhCB_COMPL_STAT Run(const msgRAW_MESSAGE &msg);
Execute the callback procedure.
It pass as arguments the given message and void* udata.
Returns the bitmask returned by the callback
If object == null, the error evhERR_NULLOBJ is generated.
If procedure == null, the error evhERR_NULLCB is generated.
If the callback returns with the bit evhCB_FAILURE up,
the error evhERR_RUNCB is generated.
In case of error returns evhCB_FAILURE.
virtual evhCALLBACK *Clone() const;
Allocates on the heap a new object identical to this one and
return its address. It is a virtual method and is used
to make copies of subclasses of evhCALLBACK using polymorphism.
If the new object cannot be created, the error evhERR_CLONE
is generated.
PROTECTED METHODS:
void *UserData() const
Acess method for the userData private data member
PRIVATE DATA MEMBERS:
evhCB_PROC proc; Pointer to the function to be called
when the callback is run
void *userData; Pointer to be passed in the udata
argument of the callback.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
eccsERR_NULL_PTR - a method argument is NULL, but it should not
evhERR_NULLCB - a Run() method has been called, but procedure == NULL
evhERR_RUNCB - a Run() method has been called and the procedure
has failed.
evhERR_CLONE - the object could not be cloned
The Run() method return the evhCB_COMPL_STAT of the executed procedure
or evhCB_FAILURE.
The usage of the udata pointer to pass data to the callback procedure
is often cause of errors.
Usually callbacks are registered in a place and executed later in a
different context and scope. This means that the pointer given in udata
must be a valid pointer when the callback is executed, not only when it
is registered.
The following example shows a typical error:
//===================================
Init()
{
COORDINATES myCoords;
evhCALLBACK myCallback( (evhCB_PROC)Proc, &myCoord);
// exit from function: myCoords is automatically deleted
}
// if later on I execute the callback, i receive a pointer
// to a deallocated object
//===================================
Look in the examples and in the documentation of the X-windows
system's callbacks for standard ways of using the udata parameter
Look at the example files in the appendix of the user manual.
The following example shows the usage of the udata pointer.
Assume that you want to pass a structure of type COORDINATES to
a callback procedure, whenever it is executed.
//===================================
// This is the function to be called
evhCB_COMPL_STAT Proc(const msgRAW_MESSAGE &msg, COORDINATES *coord)
{
// Do something
}
// Creates the COORDINATES instance:
COORDINATES myCoords;
// Creates the evhCALLBACK setting the procedure and the udata.
// The cast to evhCB_PROC is necessary.
evhCALLBACK myCallback( (evhCB_PROC)Proc, &myCoord);
// This line executes the callback procedure:
myCallback.Run(aMessage);
//===================================
The function is called with the given message and the registered myCoord
as arguments.
It is important to remember that myCoord must exist when the callback is
executed, usually by the event handler when the corresponding event
occurrs.
EVH(5), evhHANDLER(3), eccsERROR_CLASS(3)
The documentation of the X-windows system contains a detailed
description of the concept of callback and of the usage of the
udata argument.
This class is used to handle a dictionary of callbacks lists.
It is internally used in the evhHANDLER class.
A dictionary is a collection of couples (key, value).
In this case the key is an instance of the class evhMSG_TYPE_KEY(3)
and identify an event, while the value is a list of callbacks, i.e.
of instances of evhCALLBACK. It is of type evhCALLBACK_LIST(3).
The class provides methods to add and delete callbacks to the list
identified by an event and to execute all the callbacks register in the
list identified by an event.
evhCALLBACK_DICT(const unsigned sz = fndDEFAULT_DICT_SIZE )
virtual ccsCOMPL_STAT AddCallback(const evhMSG_TYPE_KEY &key,
const evhCALLBACK &cb);
Add the new callback cb to the list identified by the key.
The callback is added at the end of the list.
If the list does not exist, it is created.
Always return SUCCESS.
virtual ccsCOMPL_STAT ClearCallback(const evhMSG_TYPE_KEY &key);
Clear the list identified by the key, if exist.
All callbacks are immediately deleted and the collector is not
used for performance reasons.
Always return SUCCESS.
virtual ccsCOMPL_STAT DelCallback(const evhMSG_TYPE_KEY &key,
const evhCALLBACK &cb);
Delete the callback cb by the list identified by the key, if exist.
The callback is not immediately deleted, but it is temporarerily
stored on a memory collector that is cleaned when we are back in the
Run() method after a call to callbacks or on explicit request of the
Collect() method.
This makes safer callback deletion from within a callback.
Always return SUCCESS.
virtual evhCB_COMPL_STAT Run(const evhMSG_TYPE_KEY &key,
const msgRAW_MESSAGE &msg);
Executes all the callbacks identified by the key.
Pass msg as message argument.
It returns the callback's bitmask returned
by the Run() method of the list.
In case of error generates the error evhERR_RUNCB.
If does not exist any callback for the given key
returns evhCB_NOCALLS
In case of multiple callbacks installed for messages of type
msgTYPE_COMMAND
msgTYPE_REPLY
msgTYPE_ERROR_REPLY
msgTYPE_TIMER
msgTYPE_EVENT
it is warranted that all the callbacks will receive the same
message.
For other message types,they will receive the same message, unless
the previous callback in the list has somehow modified it.
virtual ccsCOMPL_STAT Collect();
Force a memory collect for removed callbacks.
Whenevere a callback is removed, it is temporarily placed in the
memory collector before beeing actually destroyed.
Actual destroy happens on return from Run() or on explicity
call to the Collect() method.
This makes safer removing callbacks from inside the callback itself.
PROTECTED DATA MEMBERS:
fndLIST collector; memory collector for removed callbacks
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_RUNCB - The Run() method of a callback has failed.
The Run() method return the evhCB_COMPL_STAT of the executed
callback list of evhNO_CALLS if no callback has been executed.
EVH(5), evhHANDLER(3), evhMSG_TYPE_KEY(3), echCALLBACK(3),
evhCALLBACK_LIST(3), fndDICTIONARY(3), eccsERROR_CLASS(3)
This class is used to handle a list of callbacks, i.e. a list of instances
of objects of class evhCALLBACK(3), or subclasses.
It is internally used in the evhHANDLER(3) class.
It inherits from the foundation class fndLIST(3) all the capabilities of
handling lists of objects and from the class eccsERROR_CLASS(3) the
standard eccs error handling.
The only new method provided is the Run() method.
evhCALLBACK_LIST();
evhCB_COMPL_STAT Run(const msgRAW_MESSAGE &msg);
Executes all the callbacks in the list, in the same order
they where inserted in the list (see fndLIST(3)).
Pass msg as message argument.
If a callback returns with the evhCB_DELETE bit set,
it deletes the callback.
If a callback returns with the evhCB_FAILURE bit set,
the error evhERR_RUNCB is generated and the method returns
immediately, i.e. the remaining callbacks in the list are not
executed.
If a callback returns with the evhCB_RETURN bit set,
it returns immediately, i.e. the remaining callbacks in the list
are not executed.
It returns the callback's bitmask of the last executed callback
In case of multiple callbacks installed for messages of type
msgTYPE_COMMAND
msgTYPE_REPLY
msgTYPE_ERROR_REPLY
msgTYPE_TIMER
msgTYPE_EVENT
it is warranted that all the callbacks will receive the same
message.
For other message types,they will receive the same message, unless
the previous callback in the list has somehow modified it.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_RUNCB - The Run() method of a callback has failed.
Whenever an application sends a command, it must be able to handle:
- One or more reply to the command
- An error reply
- A timeout
The handling of these events, with all the interactions, is quite
complex. For example, if an error reply is received, we have to detach
the callbacks for the normal replies and the timeout, because the
command is failed...
Using an instance of this class it is possible to define callbacks to
be used for the reply, error reply and timeout to a command and send
the command.
All the installation/deinstallation of the callbacks is done
internally to the class on the global, predefined,
event handler (see evhHANDLER(3)).
After a call to the Send() method the object waits for the replies or
for the expiration of the timeout.
Whenever a reply or error reply to that specific command (i.e. message
type, command name and command ID) is received, the corresponding callback
is executed.
If the callback itself return with the evhCB_DELETE bit set, the object
is Reset() and can be used to send another command. Otherwise it is
necessary first to explicitly reset it: it is not possible to send a new
command when replies are pending for the previous one.
The timeout will be deinstalled only when the handling of the replies to
a command is completed, i.e. when the one reply has returned evhCB_DELETE
or a Reset() has been explicitly issued.
The class makes use of the default evhHandler to handle callbacks (EVH(5)).
evhCOMMAND();
~evhCOMMAND();
virtual ccsCOMPL_STAT Send(msgMESSAGE &msg);
This method is used to send as a command the message given as
parameter and to install the callbacks to handle the replies.
It is not allowed to send a new command by using this object
if a reply from the previous one is pending. In this case the
error evhERR_HANDLE_COMMAND is generated.
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
If the function fail while sending the command, the error
evhERR_SEND_COMMAND is generated.
If the function fails while setting up the callbacks, the error
evhERR_INST_COMMAND is generated.
virtual vltLOGICAL Status() const;
Returns TRUE if a command has been sent and replies are pending,
FALSE if no replies are pending
virtual ccsCOMPL_STAT Reset();
If the object is waiting for replies, its status is reset
and all the callbacks are deleted. After a Reset() it is possible
to issue a new Send().
Always return SUCCESS
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
virtual ccsCOMPL_STAT Reply(evhCALLBACK &cb);
virtual ccsCOMPL_STAT ErrReply(evhCALLBACK &cb);
virtual ccsCOMPL_STAT Timeout(evhCALLBACK &cb, eccsTIMEVAL interval);
Functions to set the callbacks to be used for replies, error
replies and timeout.
If not set, nothing is installed and incoming messages are ignored.
If Timeout is not set, the callbacks are installed until a
reply or an error reply have been received and the callback
has returned with the evhCB_DELETE flag set.
Passing NOOBJECT as argument, resets to the default behaviour.
virtual ccsCOMPL_STAT Timeout(eccsTIMEVAL interval);
This function let to change the timeout value, without
changing an already set timeout callback
const char *Command() const;
msgCMDID CommandId() const;
Access methods to get the command name and id for the last command
sent.
virtual int _ReplyCB(msgMESSAGE &msg, void *udata);
virtual int _ErrReplyCB(msgMESSAGE &msg, void *udata);
virtual int _TimeoutCB(msgMESSAGE &msg, void *udata);
These are the actual callback functions installed by the object
to receive the replies and to handle the timeout.
They perform some administrative work (like resetting the object
when necessary) and takes care of executing the user defined
callback functions.
In case of error they generate the error evhERR_RUNCB
virtual evhCOMMAND &Status(vltLOGICAL newStatus);
Set the status of the instance (TRUE means that a reply is pending,
FALSE that it is ready to send commands.
evhCALLBACK *Reply() const;
evhCALLBACK *ErrReply() const;
evhCALLBACK *Timeout() const;
Access methods to return pointers to the callbacks intalled
ccsCOMPL_STAT SetCallbacks(msgMESSAGE &msg);
ccsCOMPL_STAT ResetCallbacks();
Install and deinstall all the callbacks
ccsCOMPL_STAT SetTimeout();
ccsCOMPL_STAT ResetTimeout();
Install and deinstall the timeout
vltLOGICAL status; Object's status flag. TRUE if replies pending,
FALSE is nothing pending, i.e. if ready to
send commands.
evhCALLBACK *reply; Callbacks used to handle replies and timeouts
evhCALLBACK *errReply;
evhCALLBACK *timeout;
eccsTIMEVAL interval; Length of the timeout
evhTIMEOUT *timeHndl; Handler for the timeout.
msgCMD command; Name and ID for the last command sent
msgCMDID commandId;
evhDB_COMMAND_CLASS
This define identifies in a unique way the evhDB_COMMAND class.
It is of type 'classType' (see fnd(4) documentation).
Internally it is a pointer to the CreateNew() method and can be used
to create instances of the class.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_HANDLE_COMMAND Try to send a command when the previous one was
pending.
evhERR_SEND_COMMAND Error while sending command
evhERR_INST_COMMAND Error in callbacks setup
evhERR_RUNCB Error running a callback
evhERR_INVALID_EVH Invalid event handler
An evhCOMMAND object dynamically allocated can be deleted inside a
callback for replies or timeout, but the callback itself MUST
return evhCB_NODELETE, otherwise the application will have unpredictable
behaviour.
Obviously in this case the user must take care that no pointers to the
deallocated object are left in the application.
It is often usefull to delete an evhCOMMAND object used to send just a
command when the last reply is received.
Notice also that if the destination process field in the message is
not set, i.e. the default empty string is used, the command is sent to
the process itself.
This is a special class, used privately only by the class evhSYNC(3) to
hold the conditions to be tested.
An instance of this class defines a condition to be tested by the evhSYNC
as a set of:
- an event key of type evhMSG_TYPE_KEY
- a pointer to a flag to be checked
- a required value for the flag
evhCONDITION();
evhCONDITION(const evhMSG_TYPE_KEY &key,int *flag = NULL,int value = TRUE);
virtual ccsCOMPL_STAT Reset(evhCALLBACK &ocb);
Reset the objects, receiving as parameter the corresponding callback
(in a better implementation the paramenter should be not necessary, but
since the class is used only internally by evhSYNC, does not matter)
virtual ccsCOMPL_STAT Run(evhCALLBACK &ocb);
Activate the condition check over the given callback
virtual int Status();
Return TRUE is the condition is satisfied, FALSE if not
virtual ccsCOMPL_STAT TryUpdate(msgMESSAGE &msg);
Given the following received message, try to update the condition.
It checks if the messages is for itself and if is correspond
to what it was waiting in order to set the condition to true..
virtual int IsEqual( const fndOBJECT& ) const;
evhCONDITION &operator =( const evhCONDITION& );
Overwrite of standard fndOBJECT methods
virtual evhMSG_TYPE_KEY &Key();
virtual evhCONDITION &Key(evhMSG_TYPE_KEY &key);
Get/set the key to be used to identify received events
virtual evhCONDITION &Status(int status);
Set the status to identify if the condition is matched or not
int Value();
Returns the value that must be matched by the tested
reference variable 'flag' (if any).
evhMSG_TYPE_KEY key; Event key
int *flag; Pointer to the flag to be checked
int value; Value required for the flag
int status; TRUE if the event corresponding to key
already occurred.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
evhCRONOMETER()
Constructor for the class.
~evhCRONOMETER();
Destructor.
ccsCOMPL_STAT Start()
Start running the cronometer.
vltUINT32 Stop( vltLOGICAL unit=CRONOMETER_MSEC)
Stops the cronometer. Returns the time ( default in mseconds )
since the Start() was issued. Other possible units are:
CRONOMETER_MSEC milliseconds
CRONOMETER_USEC microseconds
CRONOMETER_SEC seconds
ccsCOMPL_STAT Reset()
Stop the cronometer and resets it to zero.
vltLOGICAL Status()
returns the status of the cronometer:
CRONOMETER_RUNNING
CRONOMETER_STOPPED
vltUINT32 ElapsedSec(), vltUINT32 ElapsedUsec(), vltUINT32 ElapsedMsec()
The count of seconds/usec/msecs from Start to Stop() of the cronometer.
If the cronometer was not previuosly stopped it returns the
number of seconds from Start(), to the moment this function is
called. The cronometer stays running.
eccsTIMEVAL *Elapsed()
returns a pointer to a eccsTIMEVAL which contains the amount of time
elapsed since the Start() of the cronometer.
vltLOGICAL status;
status of the cronometer. It can be either:
CRONOMETER_RUNNING or
CRONOMETER_STOPPED
eccsTIMEVAL start_time;
Structure with the elapsed time since 01.01.1970 00 00 00 to
the moment the Start() was called for this cronometer.
eccsTIMEVAL stop_time;
Structure with the elapsed time since 01.01.1970 00 00 00 to
the moment the Stop() was called for this cronometer.
eccsTIMEVAL elapsed;
Structure with the elapsed time between the last Start()/Stop().
// Status
#define CRONOMETER_RUNNING 1
#define CRONOMETER_STOPPED 0
// Units
#define CRONOMETER_MSEC 2
#define CRONOMETER_USEC 1
#define CRONOMETER_SEC 0
#include "evhCRONOMETER.h"
main(int argc,char **argv){
evhCRONOMETER mycronometer;
ccsInit(argv[0]);
mycronometer.Start();
{
.
.
st = Process();
.
.
}
cout << "milliseconds On previuos block = " << mycronometer.Stop()
<< "\n";
}
evhDB_CMD_SEND - Send a command to a target defined on the database
Optionally waits for another command to be completed.
This class is used to send a command to a specified target.
The target is read from the on-line database, so that it is configurable.
Whenever the Send() method is called, a "sendId" unique identification
code is assigned to the command.
If no synchronization with other commands has been requested, then the
command is sent, otherwise the object waits for the completion of the
command with the specified "sendId".
The states of the object are:
IDLE when it is doing nothing or has received a final OK reply
to a sent command
WAITING when it has to send a command, but first has to wait
for another one to be completed.
During this phase, no timeout is considered, since no
command has been sent.
BUSY when it has sent a commmand to the target and is waiting
for the final reply.
Here the timeout time is taken into account.
ERROR if it has received an error reply or the timeout is expired
for a sent command.
This is a transient state and the object switches
automatically in IDLE state after having temporarily
switched to ERROR state.
Although if it is a transient state, it will be reflected
on the database.
The object is always ready to send a new command.
If it is requested to send a new command while in BUSY state, the replies
from the previous command are ignored.
Users of the class can be informed of what happens monitoring the
database attribute containing the state of the object, that is always
kept up to date.
Objects interested in error conditions, can monitor the state for the
transient ERROR state placing an event on that exact condition. The
object will immediately switch to IDLE, but the event will be generated
anyway and the error code can be retrieved from the database.
It is always assumed that a command is succesfully completed whenever the
last reply is received, no regard of the contents of the message buffer.
Some methods allow to directly register callbacks to be executed when
the last reply, an error reply or the timeout event occurr.
The class inherits from the base class evhDB_TASK(4) the support for the concept
of "db read/write" and "db read only" instances.
"db read only" instances only read their configuration parameters from the database
but never write any information on the database
"db read/write" instances also write their state and configuration in the database.
This allows for more instances to use the same database point as a
base for their configuration values. In this way it is possible to
dynamically create objects without having to know in advance
how many instances will be used and to put as many support
points in the database.
evhDB_CMD_SEND(const dbSYMADDRESS dbPoint, evhDB_COMMAND_TYPE type);
evhDB_CMD_SEND();
The constructor's parameter evhDB_COMMAND_TYPE type is used to
customize the target's handling.
The base class evhDB_COMMAND(4) provides handling of a single
target, whose adress is stored in the database.
Any subclass of this can be passed, used the evhDB_COMMAND_TYPE
identifier provided.
In particular evhDB_LIST_COMMAND(4) is able to send the command
to a list of targets, defined in a table stored in the database
virtual ccsCOMPL_STAT Init();
Read configuration parameters from the database
virtual ccsCOMPL_STAT Reset();
Reset the object, making it ready to send new commands.
A previous command under execution is considered completed
with failure.
The object goes transiently in ERROR state and notify
waiting objects that the previous command is completed
ccsCOMPL_STAT Send(const msgCMD command,
const char *newBuffer, msgLENGTH newBuflen=0,
evhDB_SEND_ID *sendId=NULL,
evhDB_SEND_ID waitId=0)
Send to the target defined in the database the given command
with the given data buffer.
If necessary, aborts a previous command not completed.
Generates a new sendId for the command to be sent.
static attribute lastId) and, if the id parameter is
not NULL, return its value in the parameter "sendId".
If waitId is not 0, does not actually send the command, but waits
for the one with identification "waitId" to be completed.
If the command name is an EMPTY string, no command is sent and it
is only used for syncronizzation purposes.
If the command can be sent, calls SendCommand(), otherwise
register the command on the notification list of the command it
is waiting for.
ccsCOMPL_STAT Timeout(int timeout)
Set a value for the timeout to be used waiting replies for a
sent command.
virtual ccsCOMPL_STAT Completed(evhCALLBACK &cb);
virtual ccsCOMPL_STAT Error(evhCALLBACK &cb);
virtual ccsCOMPL_STAT Timeout(evhCALLBACK &cb);
Register the given callback for the to be called when the command
has been succesfully executed (the final OK reply is received),
an error reply has been received or the timeout is expired.
Passing NOOBJECT as argument, resets to the default behaviour.
Should not be necessary to have the following methods public:
protected should be OK, but it seems that GCC has some problems
ccsCOMPL_STAT Register(evhDB_CMD_SEND *who, vltUINT32 id);
ccsCOMPL_STAT UnRegister(evhDB_CMD_SEND *who, vltUINT32 id);
Add/remove the object passed in the 'who' parameter to the list
of instances to be notified when the command identified by 'id'
is completed.
virtual ccsCOMPL_STAT SendCommand(evhDB_SEND_ID &);
Actually send the command ready to be executed, by using ActualSendCommand().
It handle dummy syncronizzation commands (with command name == empty
string.
With respect to the called sub-function, it just takes care of setting the
state to IDLE at the end if necessary.
This splitting will be used in subclasses (see evhDB_CMD_SERIAL), when
more than one command can be queued and having sent successfully a command
and received the final reply will not mean that the object can go to IDLE
state.
const char *Destination();
Return the symbolic address of the destination for commands
This is read from the database.
static evhDB_SEND_ID noWaitId;
Static variable used as default when no wait is requested for other
commands.
virtual ccsCOMPL_STAT ActualSendCommand();
Actually send the command ready to be executed.
It handle dummy syncronizzation commands (with command name == empty
string.
virtual ccsCOMPL_STAT Notify();
Used to notify all the instances in the waiting list that the
command is completed.
This correspond to call the SendCommand() method for all the
instances waiting, passing its own wait id.
ccsCOMPL_STAT SetCommand(const msgCMD command,
const char *newBuffer, msgLENGTH newBuflen=0);
Defines the command to be sent
virtual evhCB_COMPL_STAT CompletedCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT ErrorCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT TimeoutCB(msgMESSAGE &msg, void *udata);
Hook functions to implement a user defined behaviour on completion
They can be overloaded in subclasses.
Now they do nothing.
virtual evhCB_COMPL_STAT EventCompletedCB(msgMESSAGE &msg, void *udata);
This callback is executed when a reply is received
for the sent command.
It first executes the corresponding hook fuction CompletedCB().
If has received a last reply, it assumes that the command is completed
and calls Notify(), then sets the state to IDLE
virtual evhCB_COMPL_STAT EventErrorCB(msgMESSAGE &msg, void *udata);
This callback is executed when an error reply is received
for the sent command.
It first executes the corresponding hook fuction ErrorCB().
Then it assumes that the command is completed and calls Notify(),
then sets the state first to ERROR and than to IDLE
virtual evhCB_COMPL_STAT EventTimeoutCB(msgMESSAGE &msg, void *udata);
This callback is executed when the timeout for the sent command
expires.
It first executes the corresponding hook fuction TimeoutCB().
Then it assumes that the command is completed and calls Notify(),
then sets the state first to ERROR and than to IDLE
virtual evhCALLBACK *Completed();
virtual evhCALLBACK *Error();
virtual evhCALLBACK *Timeout();
Functions to retrieve the user installed callbacks
ccsCOMPL_STAT SetId();
Generates a new wait id (using the internal static variable lastId)
and sets in id to this new value.
vltUINT32 Id();
Retrieves the internal id for this instance
fndLIST &WaitingList();
Retrieves a reference to the waiting list for the instance
virtual evhDB_COMMAND *Cmd();
Retrieves the pointer to the internal instance ov evhDB_COMMAND
evhDB_COMMAND *NewCmd(const dbSYMADDRESS dbPoint,evhDB_COMMAND_TYPE type);
Creates a new dynamical instance of evhDB_COMMAND and initializes it.
It can be any subclass of evhDB_COMMAND, as specified by the 'type'
parameter.
evhCALLBACK *completed;
evhCALLBACK *error;
evhCALLBACK *timeout;
Pointers to callbacks used to handle the final OK reply, error
replies and timeouts
evhDB_COMMAND *cmd;
Pointer to the internal, dynamically allocated instance of
evhDB_COMMAND (or any subclass). It is used to actually
send commands.
msgMESSAGE msg;
Message structure to be sent with the command
vltUINT32 id;
Internal id for the sent command
evhDB_SEND_ID waitingFor;
Internal id of the command we are waiting for
fndLIST waitingList;
List of instances waiting for completion of our current command
static vltUINT32 lastId;
Last id used in this application
Notice that if an instance of this class is requested to wait for a
command already completed and served (i.e. the id has been written on
the database and the evhHANDLER has already received and handled the
corresponding database event), it will never be notified.
To be sure that this never happens, the request must be done in the same
callback that sends the command we want to wait for (we must never enter
the main loop between the two calls).
Error handling should be improved.
3.1.7.1 State transition diagram
evhDB_CMD_SERIAL - Send a commands to a target defined on the database
Commands are serialized. A command can be suspended
to wait for another one to be completed.
This class is used to send commands to a specified target.
The target is read from the on-line database, so that it is configurable.
The class can accept request for a new command to be sent before that
the previous one has been completed.
The new commands are queued and the first one in the queue is sent as
soon as an OK last reply is received for the one currently under
execution.
In case of error the queue is reset and no more commands are sent.
The states of the object are:
IDLE when it is doing nothing.
WAITING when it has to send a command, but first has to wait
for another one to be completed.
During this phase, no timeout is considered, since no
command has been sent.
BUSY when it has sent a commmand to the target and is waiting
for the final reply
ERROR if it has received an error reply or the timeout is expired
for a sent command.
This is a transient state and the object switches
automatically in IDLE state after having temporarily
switched to ERROR state.
Although if it is a transient state, it will be reflected
on the database.
QUEUE CHECK if it is checking for new commands waiting to be sent on
the queue, after having received an OK last reply from
the previous command.
This is a transient state (not reflected on the database).
If no more commands are waiting, it will immediately jump
on IDLE, otherwise it will jump on BUSY and send the command
The object is always ready to handle a new command, putting it on the
queue.
Users of the class can be informed of what happens monitoring the
database attribute containing the state of the object.
Objects interested in error conditions, can monitor the state for the
transient ERROR state placing an event on that exact condition. The
object will immediately switch to IDLE, but the event will be generated
anyway and the error code can be retrieved from the database.
The class inherits from the base class evhDB_TASK(4) the support for the concept
of "db read/write" and "db read only" instances.
"db read only" instances only read their configuration parameters from the database
but never write any information on the database
"db read/write" instances also write their state and configuration in the database.
This allows for more instances to use the same database point as a
base for their configuration values. In this way it is possible to
dynamically create objects without having to know in advance
how many instances will be used and to put as many support
points in the database.
evhDB_CMD_SERIAL(const dbSYMADDRESS dbPoint, evhDB_COMMAND_TYPE type);
~evhDB_CMD_SERIAL();
The constructor's parameter evhDB_COMMAND_TYPE type is used to
customize the target's handling.
The base class evhDB_COMMAND(4) provides handling of a single
target, whose adress is stored in the database.
Any subclass of this can be passed, used the evhDB_COMMAND_TYPE
identifier provided.
In particular evhDB_LIST_COMMAND(4) is able to send the command
to a list of targets, defined in a table stored in the database
virtual ccsCOMPL_STAT Init();
Overloading of the inherited method.
virtual ccsCOMPL_STAT Reset();
Overloading of the inherited method.
Reset only the command that is currently under handling (sent and
waiting for reply or waiting to be executed).
Other queued commands remain on the queue and, if possible, the first
one is the queue is sent.
virtual ccsCOMPL_STAT Send(const msgCMD command,
const char *newBuffer, msgLENGTH newBuflen=0,
evhDB_SEND_ID *sendId = NULL,
evhDB_SEND_ID waitId = evhDB_CMD_SEND::noWaitId);
Overloading of the inherited method.
If IDLE, the command is immediately sent, otherwise it is queued
to wait for the previous one to be completed.
virtual ccsCOMPL_STAT Timeout(int timeout);
Overloading of the inherited method.
virtual ccsCOMPL_STAT SendCommand(evhDB_SEND_ID &);
Overloading of the inherited method.
evhDB_CMD_SERIAL(); The protected constructor with no parametrs cannot
be used to build real instances.
It is provided in order to allow the implementation
of the standard foundation class methods
virtual ccsCOMPL_STAT Notify();
virtual ccsCOMPL_STAT SelfClean(evhDB_SEND_ID &);
This method is internally used whenever a command is completed and
is called inside Notify().
It checks if some commands in the queue where defined to be
waiting for this one. If so, they are cleaned and become ready to be
executed as soon as they are at the top of the queue.
virtual evhCB_COMPL_STAT EventCompletedCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT EventErrorCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT EventTimeoutCB(msgMESSAGE &msg, void *udata);
Overloading of the inherited corresponding methods.
Before returning they also check is there is something else in the
queue waiting to be executed.
virtual evhDB_COMMAND *Cmd();
Overloading of the inherited corresponding method.
It takes into account what of the two command handlers (the inherited
and the alternate) is currently under use and must be returned.
Subclasses should use this method only for reading in the evhDB_COMMAND
as if it was a const method.
ccsCOMPL_STAT QueueCheck();
Checks in the queue to see if there is another command waiting and ready
to be executed. If so prepares the data and call SendCommand() for it.
fndLIST queue;
List with the queued commands. Incoming commands are appended
to the end, executed command are extracted from top.
evhDB_COMMAND *cmdAlt;
Pointer for the alternate command handler
vltLOGICAL cmdSwitchFlag;
Flag used to define if the standard (FALSE) or alternate (TRUE)
command handler has to be used.
see evhDB_CMD_SEND(4)
Because of internals in current implementation, sub-classes of
evhDB_COMMAND used inside this class should not be modified
using the Cmd() method.
It is only allowed to use this method to read (as if it was a const method)
A better implementation could avoid this problem.
3.1.8.1 State transition diagram
This class is used to send commands to a process, like the base class
evhCOMMAND, but the name of the destination process is stored in the
on-line database, so that it is configurable.
The name of the destination process can include an environment name
in the format:
"@envName:procName"
using the same syntax used to identify a remote environment for database
accesses.
evhDB_COMMAND(const dbSYMADDRESS dbPoint)
The constructor gets as parameter the symbolic address
of the database point where the configuration data are stored
~evhDB_COMMAND();
const char *Destination();
Returns the destination for commands, read from the database
support point
const char *DbPoint();
Returns the simbolic address of the database support point
virtual ccsCOMPL_STAT DbPoint(const dbSYMADDRESS dbPoint);
Set a new database support point from where to read the target for
commands.
virtual ccsCOMPL_STAT Send(msgMESSAGE &msg);
Overload the corresponding method inherited from the base class.
Send a command using the given msgMESSAGE structure.
The specification for the target contained in the msgMESSAGE
structure is ignored and is read from the database.
virtual ccsCOMPL_STAT CopyConfig(evhDB_COMMAND &cmd);
Copies the configuration of an evhDB_COMMAND into this.
For example copies the name of the database support point.
It is to be used to configure an evhDB_COMMAND so that it
bahaves just like another one, sending to the same destination.
It is mainly important when developing sub-classes and is used
by the evhDB_CMD_SERIAL class.
ccsCOMPL_STAT ParseTarget(ccsENVNAME destEnv, ccsPROCNAME destProc,
const char *target);
Internally used to parse the target string (target parameter)
and extract the environment and process name of the destination
for commands.
dbSYMADDRESS dbPoint;
Symbolic address of the database base point
vltBYTES32 destination;
To hold the destination of commands when loaded.
It is returned by the Destination() method.
evhDB_COMMAND_CLASS
This define identifies in a unique way the evhDB_COMMAND class.
It is of type 'classType' (see fnd(4) documentation).
Internally it is a pointer to the CreateNew() method and can be used
to create instances of the class.
The class assumes that the database point, set in the constructor or with
a call to the DbPoint() method, has an attribute called 'destination' of
type bytes32.
Usually can be used an instance of the dbl class evhDB_COMMAND:
CLASS BASE_CLASS evhDB_COMMAND
BEGIN //
// Attribute containing the destination for commands
ATTRIBUTE bytes32 destination "NOT_USED" //
END //
This attribute is read every time a command is sent an can be dynamically
changed with the DbPoint() method.
The name of the destination process can include an environment name
in the format:
"@envName:procName"
using the same syntax used to identify a remote environment for database
accesses.
There is no other dependency from the database.
Many instances of the class can rely on the same database support point,
since it is used only for read.
The default value for destination is "NOT_USED", to generate an error
sending a message to a not existing process is not set.
Please notice that an empty string sends the command to the process itself.
This is a special class, used privately only by the class evhDB_SYNC(4) to
hold the conditions to be tested.
An instance of this class defines a condition to be tested on a database
attribute.
The condition is verified when the database attribute gets the value
specified in the constructor.
evhDB_CONDITION();
evhDB_CONDITION(const dbSYMADDRESS attr,
int value = TRUE);
The constructor gets as parameters the attribute to be monitored
and the required value for the condition to be satisfied.
virtual ccsCOMPL_STAT Reset(evhCALLBACK &ocb);
virtual ccsCOMPL_STAT Run(evhCALLBACK &ocb);
virtual int Status();
virtual ccsCOMPL_STAT TryUpdate(msgMESSAGE &msg);
Overload of the inherited methods
evtEVENT evt;
evtEVENT object used to monitor the batabase value
dbTYPE dataType;
The type of the database attribute to be monitored.
Can be dbLOGICAL or dbINT32
eccsDB_ATTR attribute;
Database access object to read the value of the monitored atttribute
The generic eccsDB_ATTR type is used to allow accessing bothe
dbLOGICAL and dbINT32 attributes
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(4) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
This class is used to send commands to a list of processes.
The same command is sent to all the processes in the list (that is read
from a vector stored in the database, to be configurable).
It is assumed that these processes, if everything is OK, will reply with
a last reply containing in the buffer the OK message.
The reply callback will be called when all the processes have sent their
OK last reply.
If any of the processes return an error or if the timeout expires, the
error or timeout callbacks are executed.
This class is quite general and can be reused in many different
situations.
In particular there are some cases where it is necessary to have lists
that change dynamically with time (mode switching, tracking).
It has to be discussed if it is better to handle these dynamic lists on
the database or in memory; in any case the class will contain methods
to deal with dynamic lists
evhDB_LIST_COMMAND(const dbSYMADDRESS dbPoint)
The constructor gets as parameter the symbolic address
of the database point where the configuration data are stored
~evhDB_LIST_COMMAND();
virtual ccsCOMPL_STAT Send(msgMESSAGE &msg);
Overload the corresponding method inherited from the base class.
Send a command using the given msgMESSAGE structure.
The specification for the target contained in the msgMESSAGE
structure is ignored and is read from the database.
All the targets specified in the list will receive the command.
The command is sent with the same command id to all the targets
(it is logically the same command).
This is the method to be overloaded in sub-class to implement
a different bevaviour (such as using a list store in a different
format, like a table instead of a vector of BYTES32).
virtual ccsCOMPL_STAT Reset();
Overload the corresponding method inherited from the base class.
const char *Destination();
This inherited method is redefined to return just
string to tell that the target is a list.
It returns the value of the define evhDB_LIST_DEST
("List of destinations")
virtual int _ReplyCB(msgMESSAGE &msg, void *udata);
Overload the corresponding method inherited from the base class.
It take updated the number of final replies it has to wait for.
vltINT32 counter;
This counter contains the number of commands sent and not already
completed (i.e. that have not send a last OK reply).
evhDB_LIST_COMMAND_CLASS
This define identifies in a unique way the evhDB_COMMAND class.
It is of type 'classType' (see fnd(4) documentation).
Internally it is a pointer to the CreateNew() method and can be used
to create instances of the class.
The class assumes that the database point set in the constructor or with
a call to the DbPoint() method contains the following attributes:
ATTRIBUTE bytes32 destination
ATTRIBUTE Vector targets(64, bytes32)
Usually can be used an instance of the dbl class evhDB_LIST_COMMAND:
CLASS evhDB_COMMAND evhDB_LIST_COMMAND
BEGIN \\
ATTRIBUTE Vector targets(64, bytes32) \\
END \\
This attributes are read every time a command is sent an can be dynamically
changed with the DbPoint() method.
The vector contains a list of targets to which the commands must
be sent.
Is an address is contained in the 'destination' attribute, it is ignored.
There is no other dependency from the database.
Many instances of the class can rely on the same database support point,
since it is used only for read.
The Send() method leave CommandId() set to "manual". In case of errors,
the succesfully sent commands are anyway registered and waited for.
This class is used along with evhDB_CMD_SEND(4) and its subclasses
to provide a mean to sincronize commands to be sent.
Whenever one instance of evhDB_CMD_SEND(4) (or subclasses) sends a command
(or register a command for sending), it generates a unique evhDB_SEND_ID,
that can be used later for syncronizzation.
Users of the classes never have to deal with the data contained in this
class, it is only internally used by evhDB_CMD_SEND(4).
evhDB_SEND_ID(evhDB_CMD_SEND *cmd = NULL, vltUINT32 id = 0);
evhDB_SEND_ID(const evhDB_SEND_ID &newId);
evhDB_CMD_SEND *cmd;
Pointer to instance of evhDB_CMD_SEND that generated the id
vltUINT32 id;
Id for the sent (or registered for sending) command
#include "evhDB_SERIAL_DATA.h"
evhDB_SERIAL_DATA myData(command, newBuff, newBuffLen, sendId, waitId)
Instances of thi class describes a command to be send by an instance
of evhDB_CMD_SERIAL(4). They contain the command to be sent (command name,
message buffer and length of the message buffer), the send id assigned to
the command and the id of the command it has to wait for completion before
that the command is sent.
Instances of this class are stored on the internal queue of
evhDB_CMD_SERIAL(4).
evhDB_SERIAL_DATA(const msgCMD command,
const char *newBuffer,
msgLENGTH newBuflen,
evhDB_SEND_ID sendId,
evhDB_SEND_ID waitId = evhDB_CMD_SEND::noWaitId);
evhDB_SERIAL_DATA(const evhDB_SERIAL_DATA &newId);
~evhDB_SERIAL_DATA();
msgCMD command;
char *buffer;
msgLENGTH buflen;
evhDB_SEND_ID sendId;
evhDB_SEND_ID waitId;
These data members describe in a complete way a command to be send
and that can be used for sync purposes
The buffer is dynamically allocated in the constructor and deleted
by the destructor and holds a copy of the given parameter.
evhDB_SYNC - Class to handle syncronizzation between several events
in the EVH toolkit. Syncronizzation can be based
also on value of a vltLOGICAL or vltINT32 database attribute
This class behaves like the base class evhSYNC(4), but it allows
also to syncronize on values of database attributes.
The attribute MUST be a vltLOGICAL or vltINT32 and the condition is considered
true when the attribute gets a specific value, assigned when the
condition is registered.
evhSYNC();
~evhSYNC();
ccsCOMPL_STAT AddCondition(const evhMSG_TYPE_KEY &key,
int *flag = NULL, int value = TRUE);
ccsCOMPL_STAT AddCondition(const dbSYMADDRESS attr,
int value = TRUE, int check = FALSE);
Overloading of the inherited method to register a new condition
for sync.
The second method let add a condition over the value of a database
attribute (that must be of type vltLOGICAL or vltINT32).
The first parameter is the attribute's symbolic address.
The second parameter is the value for the attribute that will
make the condition true.
The third one is a check flag( default = FALSE ). If TRUE the value of
the parameter is immediately checked when the AddCondition is called,
otherwise it is checked only when its value changes. If all conditions defined
are over database attributes and all check flags are set to TRUE, the object will
inmediatly syncronize, executing the ActionCB callback at the moment the Run() is
call( see evhSYNC and CUATIONs section on this page ).
virtual evhCB_COMPL_STAT HandlerCB(msgMESSAGE &msg, void *udata);
Overloading of the inherited method to handle database events
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_HANDLE_SYNC Instance already handling a syncronizzation
evhERR_INST_SYNC Cannot install the syncronizzation instance
evhERR_RUNCB Error while running a callback
evhERR_INVALID_EVH Invalid event handler
Because the object can syncronize before the event handler enters on its
MainLoop, it is recommended to check for the status of the DB_SYNC object right after
the Run() method is called. Use the Status() method which return TRUE in case
the object still active and FALSE otherwise. The ActionCB callback is called by the Run()
method in case that all conditions are TRUE and the object becames inmediatly inactive.
Run() method called from inside a callback function is always ignored.
EVH(5), evhSYNC(4), evhHANDLER(4), eccsERROR_CLASS(4), evhMSG_TYPE_KEY(4),
evhCALLBACK(4), evhOBJ_CALLBACK(4), evhTIMEOUT(4)
This is the base class for task objects having a database support point
in the database where run time and configuration values are stored.
Thus it provides a constructor to assign the symbolic address for this
attribute and a public access function to retrieve the state.
It provides also the concept of "object state": the object has a state,
normally stored in the online database as an integer value. The State()
overloaded method is available to read and change the state. External objects
can read the database attribute.
The class support the concept of "db read/write" and "db read only" instances.
"db read only" instances only read their configuration parameters from the database
but never write any information on the database
"db read/write" instances also write their state and configuration in the database.
This allows for more instances to use the same database point as a base
for their configuration values. In this way it is possible to dynamically
create objects without having to know in advance how many instances
will be used and to put as many support points in the database.
This is controlled by the value found in the database at creation time for the
.dbWriteEnabled attribute: if TRUE (dafault) the instance is considered "readwrite",
and is allowed to write state and other information in the database, if FALSE.
it is not supposed to write anything in the database.
More "db read/write" instances can also use the same database point.
In this case they share the values store in database and in particular the state.
Whenever one instance writes a new value in the database this is seen immediately
by all the other instances sharing the same point.
Sub-classes MUST use the protected method DbWriteEnabled() to ask to the object
if it is read/write or read only. In the latter case they have to take care
not to write anything in the database.
evhDB_TASK(const dbSYMADDRESS dbPoint)
~evhDB_TASK
The constructor receives the symbolic address of
online database support point for the object, i.e. the point
where the object can find configuration and run time values.
The constructor set the state to evhSTATE_LOADED
The destructor set the state to evhSTATE_OFF
vltINT32 State() const
Retrieve the state of the object, as it in on the database
const char* StateName();
Retrieve the state in the format of a string
const char *DbPoint() cons
Return the symbolic address of the support database point
vltLOGICAL DbWriteEnabled()
TRUE if the object is allowed to write on the databse its own state and config. on db
FALSE if it is not allowed to write on the db.
eccsCOMPL_STAT State(vltINT32 state)
Set the state
const fndNAME_MAP *StateNames() const;
Retrieve the table mapping states values and states names
ccsCOMPL_STAT SetStateNamesTable(fndNAME_AND_INDEX *newTable,
unsigned int nelem);
ccsCOMPL_STAT SetStateNamesTable(fndNAME_MAP *newNameMap);
Set the table mapping states values and states names.
Set first method builds a private internal table starting
from a map of fndNAME_AND_INDEX couples (name,index),
the second one uses a given table and only stores a pointer to it.
They are called in the constructor to customise state names in
sub-classes.
evhDB_TASK(); The protected constructor with no parametrs cannot
be used to build real instances.
It is provided in order to allow the implementation
of the standard foundation class methods
dbSYMADDRESS dbPoint; Symbolic address of the support db point
vltLOGICAL dbWriteEnabled; Flag for instances that can write status on db.
Filled at creation time based on the
value of the db attribute .dbWriteEnabled
vltINT32 state; Current state value.
eccsDB_INT32 dbState; Database access object for the state
fndNAME_MAP *stateNames; Pointer to the state names table
vltLOGICAL privStateNames;
Flag to specify if the state names table is a private one
(and must be deleted by the destructor, or just a pointer to a
global one
static fndNAME_AND_INDEX stateNamesTable[];
Default class state names table
The methods InitCB() and ExitCB(), callbacks for evhINIT_CMD and
evhEXIT_CMD commands, returns a last reply to the caller if and only if
there is just 1 instance of evhTASK (and sub classes) allocated in the
application, otherwise it is duty of the application to overload the
callbacks in one of the instances and send the last reply.
evhDUMMY, evhDUMMY_REP_DATA, evhDUMMY_CB_DATA - Base class to
develop dummy processes and related support classes.
class evhDUMMY: public evhTASK
class evhDUMMY_REP_DATA: public fndOBJECT
class evhDUMMY_CB_DATA: public fndOBJECT
The evhDUMMY class can be dynamically configured via a command
interface to reply to any command. You can dynamically tell to the
class how to behave when it receives any command:
- What kind of reply it has to send (normal/error)
- What message buffer to send
- What error code in case of error reply
- After how many seconds from the receiving of the command it
must send the reply.
The evhDUMMY_REP_DATA class is a support class containing the
description of the way a specific received command should be handled.
The evhDUMMY_CB_DATA class is a support class containing all the
information necessary to send back the reply for a received command
that is wayting that the requested waiting time before the sending of the
reply expires.
There is no limit to the number of commands that can be
handled by the same instance of the dummy and on the dynamic
configuration changes you can request while it is running.
The class can be asked to read from a file an initial
configuration containing a list of commands and reply descriptions.
Empty lines are ignored and lines starting with '#' are comments.
Every record in the file has comma delimited fields with the
following meaning:
<cmd name>,<reply buffer>,<err reply>,<err code>,<timeout>
The <reply buffer> can be enclosed in quotes (for example
in order to define replies containing commas). The enclosing
quotes are removed. It is not possible to register replies
containing quotes.
The file is searched calling the standard ccsOpenFile() function
The class accepts the following configuration
commands:
REGCMD <cmd name>,<reply buffer>,<err reply>,<err code>,<timeout>
Register command
To add a new command to the list of accepted commands or
to change the behaviour of an existing one.
The <reply buffer> can be enclosed in quotes (for example
in order to define replies containing commas). The enclosing
quotes are removed. It is not possible to register replies
containing quotes.
UREGCMD Un-register command
To delete a command from the list of accepted commands
PRNCMD Print command list
To print on standard output the list of accepted commands
and their configuration parameters.
DMEXIT Exit the program
All the informations about commands received and replies sent
are exensively logged on stdout and/or on the CCS logging system.
The class can be used in the following ways:
- During development to easily replace not yet available processes.
- During testing of a process to replace the processes this
one has to send commands. A test script sets the dummy
configuration, then stymulate the program under test to send
commands to it, then changes the dummy configuration and so
on. In this way it is much easier to test the dynamical
behaviour of a process, taking into account also timeouts
and timing constraints.
The log report can be used to verify the tests and, along
with eccsTestDriver, to write automatic tests.
The class is easily extensible and new features (if
necessary) can be added.
evhDUMMY class:
evhDUMMY();
Constructor. Initialyze the object and installs the callbacks
for the basic commands.
virtual evhCB_COMPL_STAT GenericCB(msgMESSAGE &msg, void *udata);
Generic callback used to receive commands.
Whenever a non standard command is received, this callback is called.
It searches the internal dictionary for a definition of the received
command.
If no definition exist, an error reply is sent back to the caller
If a definition exist, handles it:
- send reply if timeout == 0
- calls RegirsterReply() if timeout != 0 to install the handlers
to be used when time to send the reply comes.
ccsCOMPL_STAT LoadCommands(char *fname);
Search for the specified configuration file (by using ccsOpenFile())
and loads the commands adding new entries or replacing already
existing entries with a new definition.
evhCB_COMPL_STAT PrintCmdListCB(msgMESSAGE &msg, void *udata);
Print a list of the currently configured commands
evhCB_COMPL_STAT RegisterCB(msgMESSAGE &msg, void *udata);
Register a new command (or replace an existing one with a new
definition) in the dictionary of handled commands.
evhCB_COMPL_STAT UnregisterCB(msgMESSAGE &msg, void *udata);
Remove a command from the list of handled commands.
virtual ccsCOMPL_STAT StdMain(int argc, char *argv[]);
Method to execute a complete evhDUMMY application with
just one call.
Once an instance of the evhDUMMY class has been created,
a call to this method takes care of parsing the standard
command line arguments, initialyzing CCS and enter the main
loop. When the DMEXIT command is received, everything is cleaned
up and the method return after having also closed CCS.
In this way a complete application requires a main() function
with just two lines of code (see example).
virtual ccsCOMPL_STAT ParseArguments(int argc, char *argv[]);
Convenience function to parse the standard comman line arguments.
It is used by StdMain() and can be overwritten in sub classes
still allowing to use StdMain().
It gets the main() arguments coming from the command line
and initialyse and set the procName and dataFile data members.
virtual ccsCOMPL_STAT PrintCLineHelp(void);
Convenience function, used in ParseArguments() to print
a standard comman line help in case of error.
Can be overloaded in sub classes.
evhDUMMY_REP_DATA class
void PrintOn( ostream& ) const;
Prints on the give stream a description of the command handling
parameters.
evhDUMMY_CB_DATA class
evhDUMMY_CB_DATA(msgMESSAGE &m,evhDUMMY_REP_DATA &d)
~evhDUMMY_CB_DATA();
Constructor and destructor.
The contructor gets two parameters:
m is the message for the received commands, with the message
buffer and all the sender identification data necessary
to be able to send back to it a reply .
d is a reference to an object of type evhDUMMY_REP_DATA describing
the reply to be sent.
evhDUMMY_REP_DATA class
fndSTRING reply; // Message buffer
fndINT errReply; // FALSE/TRUE (error reply)
fndINT errCode; // 0 or code for error reply
fndINT timeout; // Timeout in seconds (0 == no timeout)
evhDUMMY_CB_DATA class
msgMESSAGE msg; // message struct with the received command
evhDUMMY_REP_DATA data; // description of command handling
evhTIMEOUT *timeout;
We save here, if any, the pointer to the timeout for the
waiting before sending the reply. In this way is at garbage
collection the timeout is not expired, it will be cleanly
deleted
evhDUMMY_REP_DATA &Lookup(fndSTRING &cmd);
Query the dictionary of configured commands and returns
the configuration of the requested command or NOOBJECT
if not exist.
It can be used in subclasses that implement a special behaviour
for some commands to get access to the command definition
data structure.
virtual ccsCOMPL_STAT ParseCommandDesc(const char *mbuffer,
fndSTRING &cmd, evhDUMMY_REP_DATA &data)
This method parses a command buffer used to decribe a command
to be registered in the dictionary of handled commands.
The mbuffer parameter is a string containing the record as it
is stored in a configuration file OR in the message buffer for
the "REGCMD" command (the method is called internally by
LoadCommands() and RegisterCB().
The string has the following format:
<name>,<reply buffer>,<err reply>,<err code>,<timeout>
The command name is stored in the cmd parameter of type fndSTRING,
the command handling description is stored in the data parameter
of type evhUMMY_REP_DATA.
ccsCOMPL_STAT RegisterReply(msgMESSAGE &msg, evhDUMMY_REP_DATA &data);
This method, called by GenericCB() when a new command is received
and it cannot be handled immediately,
- allocates dynamically an object of type evhDUMMY_CB_DATA
to store all the information necessary to send back the
reply to the command
- installs a timer to expire when the reply has to be sent
and to call SendReplyCB() passing the allocated object.
The object will have to be deallocated by SendReplyCB().
All the allocated objects are stored in a collector to allow
clean-up in case of exit or error conditions.
virtual ccsCOMPL_STAT SendErrorReply(msgMESSAGE &msg);
This method is used to send back a generic error reply on
unknown commands.
virtual ccsCOMPL_STAT SendReply(msgMESSAGE &msg, evhDUMMY_REP_DATA &data);
This method build and actually send the reply to a command, parsing
the data in the given data object of type evhDUMMY_REP_DATA and
building the body of the corresponding normal or error reply.
virtual evhCB_COMPL_STAT SendReplyCB(msgMESSAGE &msg, evhDUMMY_CB_DATA *d);
This callback is executed when the time to send a reply for a
previously received and registered command occurs.
It receives in the d parameter a structure of type evhDUMMY_CB_DATA
describing how the reply must be formed.
It sends the proper reply by cakking SendReply()
and deallocates d (that has been previously dynamically allocated
by RegisterReply() when the command was received).
fndDICTIONARY &RegCommands();
Returns a reference to the dictionary containing the current
registered commands.
fndDICTIONARY cmdDict;
Dictionary of configured commands.
Contains one entry for every application command that the object
must be able to handle.
The command name is the search key.
An object of type evhDUMMY_REP_DATA is the value of the record
and describes how the command must be handled.
fndLIST collector;
List to contain dynamic objects created by RegisterReply()
of type evhDUMMY_CB_DATA. This allow garbage collection of
all the memory used for replies waiting to be sent when
the object is deleted.
char *procName;
Name of the evhDUMMY process, used to register the process with
ccsInit(). Passed on the command line and set by ParseArguments()
char *dataFile;
Name of the data configuration file containing the initial configuration
of commands. Passed on the command line and set by ParseArguments()
The class evhFILEIO is used to attach and detach a file descriptor
to the handler.
Whenever an attached file descriptor is "ready" (read the standard unix
documentation about the select(2) system call for more details) an internal
command is generated with
the following key:
MsgType : msgTYPE_COMMAND
Command : evhFILE_IO_CMD
CommandId : file descriptor
If there are callbacks associated to that command they are executed.
evhFILEIO::evhFILEIO(int fd)
~evhFILEIO();
Constructor method storing the value for the file descriptor in the
object. It is necessary to create an instance of the evhFILEIO
class for each file descriptor there shall be selected on.
If the given file descriptor is out of range, the error
evhERR_ILLEGAL_FD is generated.
void evhFILEIO::Attach()
Attach the file descriptor for this instance of
evhFILEIO. If there is an input on this file descriptor, this
will be detected and the installed callbacks, if any, will be
executed.
If the file descriptor is already attached, the error
evhERR_FD_ATTACHED is generated.
void evhFILEIO::Detach()
Detach the file descriptor for this instance of evhFILEIO.
int evhFILEIO::Fd()
Returns the file descriptor associated to the evhFILEIO object
vltLOGICAL evhFILEIO::Status() const
Returns ccsTRUE if the fd for this object is attached
and ccsFALSE if not.
ccsCOMPL_STAT evhFILEIO::BuildMsg(int fd, msgMSG *fileIoMsg)
Static method that generates a 'synthetic' CCS Message with
the given file descriptor and write the message in the given
msgMSG.
It is used in the evhHANDLER class to generate the internal
message when an attached file descriptor becomes ready.
The fd is copied into the Command ID of the msgMSG message.
The other parameters which it is necessary to set, are set to
appropriate values:
command: evhFILE_IO_CMD
commandId: fd
timeStamp: now
responseFlag: msgRESPOND
buffer: empty
It generates the eccsERR_NULL_PTR if fileIoMsg == NULL.
const int *evhFILEIO::FdsList()
Return the pointer to the list containing all the attached
file descriptors.
int file;
File descriptor associated to this instance
static int fds[evhMAX_NO_OF_FDS];
Static list of file descriptor. Every entry set to TRUE correspond
to an attached file descriptor.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_ILLEGAL_FD is an object is created with an illegal file desc.
evhERR_FD_ATTACHED the file descriptor is already attached
eccsERR_NULL_PTR if a parameter has a NULL value, where a legal pointer
was expected
It is not a good practice to use the evhFILEIO::Select() method to wait
for input from standard files. This is only for sockets, pipes, terminal
outputs, etc. This is due to a specific behaviour of the select()
system call on unix files: selecting on a standard file descriptor
will return immediately stating that data is ready in the file, also if
the file pointer is at end of file.
This class is the core of the Event Handling Toolkit.
A general introduction to the EVH toolkit can be found in the EVH(5)
man page.
It is an event dispatcher that receives all the events directed to the
application (coming from the outside world or generated internally),
parses them and searches in an internal dictionary for a list of
functions (callbacks) that must be called to handle that particular event.
If such a list of functions exist, they are called in sequence.
Upon return from the last callback, the dispatcher is ready to manage
other events.
The callback lists associated with events are dynamic and evhHANDLER
provides methods to add and delete elements from the list.
The following types of events are handled:
- Command
- Reply
- Error reply
- Timeout
- Timer
- Database events
- I/O avialable from unix file descriptors
- Unix signals
- Alarms
The include file <evhHandler.h> defines a global, predefined,
event handler.
It is accessible through the global variable:
evhHANDLER *evhHandler;
For debugging purposes, it is possible to log a trace of all the
messages received and sent by the system and to monitor the execution
time of callbacks. This can be controlled by the application or
setting proper environment variables.
It is also possible to force checking of incoming commands based on the CDT.
Since commands are assumed to be checked by the sender, a warning
is issued if by checking a commands it turns out not having been checked.
This feature cannot be used if the application has to handle binary formatted
commands.
evhHANDLER();
Constructor: build an instance of evhHANDLER.
Never fails except for memory allocation problems.
ccsCOMPL_STAT AddCallback(const evhMSG_TYPE_KEY &key,
const evhCALLBACK &cb);
Add the specified callback to the list for the event defined by
the given key (look at evhMSG_TYPE_KEY(3) and evhCALLBACK(3)
for more details).
Always return SUCCESS.
ccsCOMPL_STAT ClearCallback(const evhMSG_TYPE_KEY &key);
Delete all the callbacks from the list the event defined by
the given key (look at evhMSG_TYPE_KEY(3) and evhCALLBACK(3)
for more details).
If the callback list is empty, nothing happen.
Always return SUCCESS.
ccsCOMPL_STAT DelCallback(const evhMSG_TYPE_KEY &key,
const evhCALLBACK &cb);
Delete the specified callback from the list for the event
defined by the given key (look at evhMSG_TYPE_KEY(3) and
evhCALLBACK(3) for more details).
If the callback does not exist, nothing happen.
Always return SUCCESS.
ccsCOMPL_STAT SetCallback(const evhMSG_TYPE_KEY &key,
const evhCALLBACK &cb);
Clear the callback list for the event defined by the given key
and install the specified callback (look at evhMSG_TYPE_KEY(3)
and evhCALLBACK(3) for more details).
If the callback list is empty, nothing happen.
Always return SUCCESS.
ccsCOMPL_STAT AddCmdCallback(const msgCMD cmd,
const evhCB_PROC procedure);
ccsCOMPL_STAT AddCmdCallback(const msgCMD cmd,
fndOBJECT *obj,
const evhCB_METHOD procedure);
ccsCOMPL_STAT DelCmdCallback(const msgCMD cmd,
const evhCB_PROC procedure);
ccsCOMPL_STAT DelCmdCallback(const msgCMD cmd,
fndOBJECT *obj,
const evhCB_METHOD procedure);
ccsCOMPL_STAT SetCmdCallback(const msgCMD cmd,
const evhCB_PROC procedure);
ccsCOMPL_STAT SetCmdCallback(const msgCMD cmd,
fndOBJECT *obj,
const evhCB_METHOD procedure);
Set of convenience functions to add/delete/set callbacks
for commands.
They are just a simplified interface to the most commonly used
call where only the command name, the callback procedure
and the object (in the case of methods) are specified.
ccsCOMPL_STAT UseSelect(vltLOGICAL mode = TRUE);
If mode = TRUE (default), activates the use of the select()
system call to catch the events. In this case it is possible
to setup callbacks for ready file descriptors and unix signals
It always returns SUCCESS.
ccsCOMPL_STAT MainLoop();
Handle the events main loop.
An application calls this function when it is ready to handle
events, usually in the main() function after initializzation
of the basi application's objects.
Inside this function events are received and callbacks dispatched.
Whenever a callback returns, execution is resumed by the MainLoop()
that is ready to handle the following event.
The function can return only if:
- a callback has asked explicitly for a return from the
main loop, rising the evhCB_RETURN bit in its return code.
In this case MainLoop() returns SUCCESS
- a callback has returned with an error condition, rising
the evhCB_FAILURE bit in its return code.
In this case MainLoop() returns FAILURE.
- an internal error occurred in the handling of events.
In this case MainLoop() returns FAILURE
Errors are also properly logged
If the callback returns with the DELETE flag up, it is
always deleted, no regard of the other flags.
If the callback returns with the FAILURE and/or RETURN flag
up, no other callback in the callback lists is called, but
the main loop exit immediately.
If the callback returns with the NOCALLS bit up AND it is
the last callback in the list, the flag is passed to the
main loop, the assumes that no callback has been called. As
a consequence it will search for other callbacks, relaxing the
event description.
In case of multiple callbacks installed for messages of type
msgTYPE_COMMAND
msgTYPE_REPLY
msgTYPE_ERROR_REPLY
msgTYPE_TIMER
msgTYPE_EVENT
msgTYPE_ALARM
msgTYPE_ALARM_CONN
it is warranted that all the callbacks will receive the same
message.
For other message types,they will receive the same message, unless
the previous callback in the list has somehow modified it.
At the end of every callback and before waiting for the next event,
the method checks also that the error stack is clean and empty.
If a callback is returned with no error code and the error stack
is not clean, this means that some error has occurred in the
callback, but it has not been properly handled.
In this case the main loop logs an error and close the otherwise
pending error stack.
The programmer should check for these errors to identify
bad error handling in the code.
ccsCOMPL_STAT SetDefCmdHandler(evhCB_PROC newHandler = NULL);
Install a new default command handler.
If newHandler = NULL (default), restore the standard one.
The default command handler is called any time it is received
a message of type msgTYPE_COMMAND, but no callback has been
installed to handle it.
The standard default command handler is the static function
DefCmdHandler() and it logs an error and send back an error reply
to the sender of the message.
If the command name was evhTIMEOUT_CMD, it is ignored.
It always returns SUCCESS.
static ccsCOMPL_STAT Trace(vltLOGICAL mode = TRUE);
This method is used for debugging purposes.
If mode = TRUE, activates a tracing of all the messages
received/sended while in the MainLoop().
A description of all messages sent and received including
message type, command name and command id
is logged using the logData() function.
Any value for mode != TRUE and FALSE is considered FALSE.
It always returns SUCCESS.
The same effect of calling Trace() can be obtained by
setting the environment variable EVH_TRACE to TRUE
before running the evh application.
static ccsCOMPL_STAT CheckCmd(vltLOGICAL mode = TRUE);
This method is used for debugging purposes.
If mode = TRUE, activates a checking of all the incoming
commands. In this case, whenever a command is received
it is checked, an error is procuded if checking fails
and an error reply is sent to the originator.
If checking is successsfull, but it turns out that checking
was not performed on the sending side, the checked command if
accepted but a warning is issued.
It always returns SUCCESS.
The same effect of calling CheckCmd() can be obtained by
setting the environment variable EVH_CHECKCMD to TRUE
before running the evh application.
ccsCOMPL_STAT CbTimeMonitor(vltLOGICAL mode = TRUE, vltUINT32 msec = 100);
This method is used for debugging purposes.
If mode = TRUE, activates the monitoring of callbacks
execution time. The time is compared with a configurable value
given in milliseconds as second optional parameter
(default: 100msec ). If it measure a time bigger than this,
it issues a warning.
Any value for mode != TRUE and FALSE is considered FALSE.
It always returns SUCCESS.
The same effect of calling CbTimeMonitor() can be obtained by
setting the environment variable EVH_CBMON to TRUE before
running the evh application.
ccsCOMPL_STAT UseSelect(vltLOGICAL mode = TRUE);
This method is switch ON (mode = TRUE) / OFF (mode = FALSE)
the use of select() system call to receive messages and events.
This enables the handling of input from unix files and signals.
Any value for mode != TRUE and FALSE is considered FALSE.
It always returns SUCCESS.
msgRAW_MESSAGE *Parse(msgHEADER *msgh);
This method is used inside the main loop to parse the received
CCS message and can be overloaded in sub classes to provide a
different behaviour to extend it to new message types.
It receives as parameter a pointer to a msgHEADER, containing
the message as returned by msgRecvMsg().
Then it checks if the message corresponds to a msgTYPE_EVENT
or not and parses it using the proper function.
A pointer to the parsed message is returned in a generic
pointer to msgRAW_MESSAGE and stored in an internal buffer
of the proper message type ( msgRAW_MESSAGE(3) is the base
virtual class for all the different kinds of messages).
The returned pointer to msgRAW_MESSAGE can be cast to its
actual message type to have access to the internal details.
ccsCOMPL_STAT Receive(msgHEADER **msgh);
This method is used inside the main loop to actually receive
pending CCS messages and can be overloaded in sub classes to
provide a different behaviour or to extend types of events.
In this implementation a standard msgRecvMsg(3) CCS call is used,
unless UseSelect() is TRUE. In this case the internal instance
of the class evhSELECT(3) is used to handle CCS messages,
ready file descriptors or unix signals.
evhCB_PROC GetDefCmdHandler() const;
Return the procedure used as the default command handle
evhCALLBACK_DICT &Dictionary();
Return a reference to the internal dictionary used to store
the callback lists
evhSELECT &Select();
Return a reference to the object used to handle the select
algorithm for receiving messages
vltLOGICAL TraceStatus();
Return the value of the trace status flag
vltLOGICAL CheckCmdStatus();
Return the value of the check incoming commands' status flag
vltLOGICAL CbTimeMonitor() const;
Return the value of the cbtimemonitor status flag
vltLOGICAL UseSelect() const;
Return the value of the select status flag
vltLOGICAL trace; flag (TRUE/FALSE) for trace debugging
vltLOGICAL checkCmd; flag (TRUE/FALSE) for command checking
vltLOGICAL cbtimemonitor; flag (TRUE/FALSE) for time monitoring
vltUINT32 cbtimedefault; Maximum allowed callback exec. time
evhCALLBACK_DICT dict; dictionary for callbacks
evhCB_PROC defCmdHandler; function pointer for default command
handler
vltLOGICAL useSelect; flag (TRUE/FALSE) for select strategy
evhSELECT select; to receive events using select()
msgMESSAGE cmdMsg; to store CCS messages
evtEVENT_MSG evtMsg; to store CCS database events
alrmMESSAGE alrmMsg; to store CCS alarm events
The MainLoop() method is used to receive events and dispatch them to the
corresponding callback functions.
Whenever an event is received the following actions are taken:
- the message is received and parsed
- the dictionary is searched for a list of callbacks matching:
- message type
- command
- command id.
- if such a list exist all the callback procedures inside the list
are executed, in the same order in wich they where registered.
- if there are no callbacks matching the key, the dictionary is
searched for a list of callbacks matching:
- message type
- command
but NOT the command id
- if such a list exist all the callback procedures inside the list
are executed, in the same order in wich they where registered.
- if there are no callbacks matching the key, the dictionary is
searched for a list of callbacks matching:
- message type
but NOT the the command and the command id
- if again the re are no callbacks matching the key, and the message
type was msgTYPE_COMMAND, the default command handler is called.
All the other messages are received and discarded
The implementation of a default command handler warranties the EVERY
command received is dealt with and a proper reply is sent back to the
originator.
Every application including evhHANDLER.h has access to a global event
handler installed in the extern variable evhHandler.
This contains an instance of class evhHANDLER and should be enough for
most of the cases.
In some special situations it may be usefull to replace this global object
with an instance of a more specialized subclass.
To do this it is necessary to create the required instance and to assign
its address to the global handler:
evhHANDLER = new evhSUBCLASS_OF_HANDLER;
this must be done BEFORE any call to methods of the original object.
In particular this must be done before having added callbacks and before
entering the main loop.
Usually the first lines of the main() function are a safe place.
EVH_TRACE if set to TRUE activates tracing of all messages received/sent
EVH_CBMON if set to TRUE activates monitoring of callback execution time
EVH_CHECKCMD if set to TRUE activates checking of incoming commands
Checking of incoming commands cannot be used if the application has
to handle binary formatted commands.
The data structure evhMSG_TYPE_KEY holds a triplet:
- vltUINT8 msgType
- msgCMD command
- msgCMDID commandId
Such a triplet of parameters is part of the msgMESSAGE data
structure for any CCS message and event and has been choosen in the
evhHANDLER(3) class as the "search key" for callbacks (see EVH(3)
for more details).
The AddCallback() method of the evhHANDLER(3) class provides the basic
mechanism to associate an event to a callback procedure.
Notice thar all the access methods to set a parameter, returns a reference
to the object itself, so that they can be formally chaned, like in the
following example:
aKey.MsgType(msgTYPE_COMMAND).Command(prsSTOP_CMD);
evhMSG_TYPE_KEY(const vltUINT8 type = 0 ,
const msgCMD cmd = msgNULL_CMD,
const msgCMDID cmdId = 0);
evhMSG_TYPE_KEY(const evhMSG_TYPE_KEY &source);
Constructors.
Never fail
evhMSG_TYPE_KEY &MsgType(const vltUINT8 type);
vltUINT8 MsgType() const;
Access methods to set/retrieve the message type
Never fail
evhMSG_TYPE_KEY &Command(const msgCMD cmd);
const char *Command() const;
Access methods to set/retrieve the command
Never fail
evhMSG_TYPE_KEY &CommandId(const msgCMDID cmdId);
msgCMDID CommandId() const;
Access methods to set/retrieve the command id
Never fail
virtual int IsEqual( const fndOBJECT& ) const;
virtual hashValueType HashValue() const;
virtual void PrintOn( ostream& ) const;
Overwrite of standard methods of the fndOBJECT base class.
The method HashValue() implements the algorithm that calculates
and returns an hash value for the object. This allows to insert
and retrieve instances of this class from fndHASH_TABLE and
fndDICTIONARY objects.
Never fail
evhMSG_TYPE_KEY &operator =( const evhMSG_TYPE_KEY& );
Assignement operator
Never fail
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
This class is part of the Event Handling Toolkit (see EVH(5)) and is
a subclass of evhCALLBACK.
It is used to define callbacks, i.e. functions that have to be
executed by the event handler (see evhHANDLER(3)) when a specific
event occurrs.
This subclass of evhCALLBACK is used when the callback procedure is a
method of an object and not a function.
In this case the callback is defined by the triplet:
(object, procedure,udata)
where:
- object is the object for wich the method has to be executed.
It MUST be an instance of a subclass of fndOBJECT(3)
- procedure is a pointer to a method of type evhCB_METHOD or
evhCB_METHOD2.
- udata is a void* used to pass data to the procedure.
Whenever the Run() method is called (like in the main loop of an
event handler, when the corresponding event occurs), the "procedure"
method of "object" is executed, having as arguments a message passed
in the Run() function call end the void pointer stored in the
evhOBJ_CALLBACK.
The function callback must be of type evhCB_METHOD or evhCB_METHOD2, i.e.
must be a virtual method of a subclass of fndOBJECT and have a prototype
in one of the following forms (look at evhCALLBACK(3) for details):
evhCB_COMPL_STAT procedure(const msgRAW_MESSAGE &msg, void* udata);
evhCB_COMPL_STAT procedure(const msgMESSAGE &msg, void* udata);
evhOBJ_CALLBACK();
evhOBJ_CALLBACK(fndOBJECT *obj,
const evhCB_METHOD procedure = NULL,void *udata = NULL);
evhOBJ_CALLBACK(fndOBJECT *obj,
const evhCB_METHOD2 procedure,void *udata = NULL);
evhOBJ_CALLBACK(const evhOBJ_CALLBACK &source);
Contructors. The empty constructor assumes NULL for all
the object, procedure and udata.
evhOBJ_CALLBACK &Object(fndOBJECT *obj);
To set/replace the pointer to the object.
If obj == NULL the error eccsERR_NULL_PTR is generated.
evhOBJ_CALLBACK &Proc(const evhCB_METHOD procedure) ;
evhOBJ_CALLBACK &Proc(const evhCB_METHOD2 procedure) ;
To set/replace the callback procedure.
If procedure == NULL the error eccsERR_NULL_PTR is generated.
virtual int IsEqual( const fndOBJECT& ) const;
Overwrite of the standard method of fndOBJECT.
evhOBJ_CALLBACK &operator =(const evhOBJ_CALLBACK &source);
Assignement operator
virtual evhCB_COMPL_STAT Run(const msgRAW_MESSAGE &msg);
Overwrite of the Run() method in the base class to
execute the callback procedure as a method of the registered
object, i.e. executes the following instruction:
object->procedure(msg, udata);
It pass as arguments the given message and void* udata.
Returns the bitmask returned by the callback
If procedure == null, the error evhERR_NULLCB is generated.
If the callback returns with the bit evhCB_FAILURE up,
the error evhERR_RUNCB is generated.
In case of error returns evhCB_FAILURE.
virtual evhCALLBACK *Clone() const;
Overwrite of the Clone() method of the base class.
Allocates on the heap a new object identical to this one and
return its address. It is a virtual method and is used
to make copies of subclasses of evhCALLBACK using polymorphism.
If the new object cannot be created, the error evhERR_CLONE
is generated.
fndOBJECT *object; pointer to the object to be referenced
evhCB_METHOD method; pointer to object method
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
eccsERR_NULL_PTR - a method argument is NULL, but it should not
evhERR_NULLOBJ - a Run() method has been called, but object == NULL
evhERR_NULLCB - a Run() method has been called, but procedure == NULL
evhERR_RUNCB - a Run() method has been called and the procedure
has failed.
evhERR_CLONE - the object could not be cloned
The Run() method return the evhCB_COMPL_STAT of the executed procedure
or evhCB_FAILURE.
The usage of the udata pointer to pass data to the callback procedure
is often cause of errors.
Usually callbacks are registered in a place and executed later in a
different context and scope. This means that the pointer given in udata
must be a valid pointer when the callback is executed, not only when it
is registered.
The following example shows a typical error:
//===================================
Init()
{
OBJECT obj;
COORDINATES myCoords;
evhOBJ_CALLBACK myCallback(obj, (evhCB_PROC)Proc, &myCoord);
// exit from function: obj and myCoords are automatically deleted
}
// if later on I execute the callback, I receive a pointer
// to deallocated object and coordinates
//===================================
Look in the examples and in the documentation of the X-windows
system's callbacks for standard ways of using the udata parameter
Remember also that callbacks MUST be vitual methods and CANNOT BE
INLINE, due to some special properties of C++ pointers to functions.
Not following this rule can, under certain circumstances, produce
unpredicable behaviour, althought usually does not give any problem.
EVH(5), evhCALLBACK(3), evhHANDLER(3), eccsERROR_CLASS(3), fndOBJECT(3)
The documentation of the X-windows system contains a detailed
description of the concept of callback and of the usage of the
udata argument.
The evhSELECT class is used internally by the evhHANDLER class for
handling asynchronous wait for incoming events.
In this way it is possible to associate callbacks not only to CCS
events, but also to ready unix files (true files, pipes, sockets..)
and to signals.
The only interface of this class, a part from constructor and destructor,
if the Select() method, used to perform an asyncronous wait for
incoming events.
The include files contains the following defines used internally:
#define evhMAX_NO_OF_FDS 256 Maximum number of files descriptors
that can be opened at the same time
for any process
#define evhNO_OF_SIGNALS 30 Maximun signal identification value
evhSELECT(); Constructor and destructor
~evhSELECT();
ccsCOMPL_STAT evhFILEIO::Select(msgHEADER **msgHeader)
This method performs an asynchroneous wait for events to come in.
It returns whenever a new CCS message is received, a unix file
descriptor attached (see evhFILEIO(3)) is ready or a signal is catched.
Upon return the parameter msgHeader, that must be a valid msgHEADER **
will point to the message corresponding to the occurred event.
The first time this function is called, it activates the monitoring
or the Rtap queue via socket. It generates the error evhERR_GET_MSGQ_FD
in case of failure and returns ccsFAILURE.
If a signal has been catched, but thwe signal handler has failed, it
generates the error evhERR_GET_MSGQ_FD and returns ccsFAILURE.
If the Select() fails while receiving a CCS message, it
generates the error evhERR_RECV_MSG and returns ccsFAILURE.
If the value for the ready file descriptor is illegal, it
generates the error evhERR_MISMATCH_FDS and returns ccsFAILURE.
If the Select() fails for any other reason, it
generates the error evhERR_SELECT_FDS and returns ccsFAILURE.
PRIVATE DATA MEMBERS:
static msgMSG msg;
Static instance of msgMSG, used by all the instances of the the class
to temporarily store an incoming CCS message.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
eccsERR_NULL_PTR - a method argument is NULL, but it should not
evhERR_GET_MSGQ_FD - error installing the monitoring of the Rtap queue via
sockets
evhERR_MISMATCH_FDS - illegal file descriptor
evhERR_SIGNAL_HANDL - signal handler failed
evhERR_RECV_MSG - Error in the message receive
evhERR_SELECT_FDS - select failed for any other reason
It is not possible to use the evhFILEIO::Select() method to wait for
input from standard files. This is only for sockets, pipes, terminal
outputs, etc. Entering a standard file descriptor to the method, it
will return immediately stating that data is ready in the file, also if
0 bytes.
The returned message is stored for performances reasons in a static
buffer common to all the instances of evhSELECT.
The contained data will be ovewritten in the subsequent call to Select()
and it responsibility of the user to save them when necessary (this
is relevant only when writing applications using directly the evhSELECT:
standard applications using evhHANDLER never need to access directly
instances of this class).
evhSIGNAL(int sig);
The constructor creates an instance of evhSIGNAL to handle the
given unix signal and registers it.
If the given signal number is illegal, generates the error
evhERR_SIGNAL_ILLEGAL.
If a signal handler has already been registerd for this signal, i.e.
if does exist another evhSIGNAL object with that signal, the error
evhERR_SIGNAL_REG is generated.
virtual ~evhSIGNAL();
The destructor deinstalls and deregisters the signal
virtual ccsCOMPL_STAT Install();
Installs the EVH signal handler for the specified signal.
After this and up to the next call to the Deinstall() method,
the signal will be catched and the SignalHandler() static method
called to handle it.
If the handler is already installed for this signal, the error
evhERR_SIGNAL_INST is generated.
If the signal number is illegal, generates the error
evhERR_SIGNAL_ILLEGAL.
If the installation of the signal handler fails, the error
evhERR_INST_SIGNAL is generated.
virtual ccsCOMPL_STAT Deinstall();
Deinstalls the installed EVH signal handler for the specified signal
and restore the default signal handler.
If no signal handler was installed for this signal, the error
evhERR_SIGNAL_NOT_INST is returned.
If the installation of the default signal handler fails, the error
evhERR_INST_SIGNAL is generated.
int Sig() const;
Returns the signal registered for this object
vltLOGICAL Status() const;
Returns TRUE if the EVH signal handler is installed for this signal,
FALSE if not.
static ccsCOMPL_STAT BuildMsg(int sig, msgMSG *signalMsg);
Static method that generates a 'synthetic' CCS Message with
the given signal id and write the message in the given
msgMSG.
It is used in the evhHANDLER class to generate the internal
message when a signal is catched for an installed signal handler.
The fd is copied into the Command ID of the msgMSG message.
The other parameters which it is necessary to set, are set to
appropriate values:
command: evhSIGNAL_CMD
commandId: signal id
timeStamp: now
responseFlag: msgRESPOND
buffer: the data prepared by the signal handler and
stored in the static data member signalData.
It generates the eccsERR_NULL_PTR if signalMsg == NULL.
This call also clears the signal status calling ResetSignal(),
because this call implyes that the signal has been treated
and the class is ready to handle a new signal.
These static methods are used to retrieve the information prepared
by the signal handler whenever it catches a registered signal.
static int LastSignal();
Last signal catched. 0 if no signal has been catched.
static void ResetSignal();
Reset the signal status to 0
static const char *SignalData();
Returns the static data buffer where the signal handler writes
the information data about the last signal catched.
static int SignalErrStatus();
Returns the error status for the last execution of the signal
handler.
static void SignalHandler(int sig);
This static method is the signal handler used to catch registered
signals.
It performs the following steps:
- Blocks concurrent interrupts on the same signal
- Checks first if another signal was waiting to be handled
(signalHandle != 0); if this is the case fails and the old
pending signal is lost.
- If the signal is a SIGCHLD, wait() for the died process
and put its pid in the signalData member in binary
format.
- Reinstalls the EVH signal handler for this signal
- Unblock the signal
Since a signal handler cannot directly call other functions
in a safe way, it just sets some class static data members (see
next section:
signalHandle
signalData
signalErrStatus
The user (namely the evhHANDLER class) had to take care of
reading these variables to verify is the handler has been executed
and to retrieve the information it has stored there.
int sig; signal handled in this instance
static SIG_STATUS signalsInst[evhNO_OF_SIGNALS];
This static array contains a flag for every allowed signal number.
The value of this flag can be one of the following:
SIG_FREE = nothing installed,
SIG_REGISTERED = signal handler registerd, but not installed,
SIG_INSTALLED = signal handler installed
as defined by the following enum:
enum SIG_STATUS { SIG_FREE, SIG_REGISTERED, SIG_INSTALLED };
These static variables are used for handling the signal
and are set by the signal handler:
static int signalHandle;
Contains the signal id for the last catched and not jet
handled signal or 0 if none.
Its value can be retrieved using LastSignal().
When the signal has been handled, it must be reset
using the method ResetSignal().
If there is a pending signal when a new one is received, the signal
handler fails.
static char signalData[evhSIG_DATA_SIZE];
Buffer to pass back data containing more details about the catched
signal. Up to now, it is only used for the SIGCHLD to store the pid
of the died process.
static int signalErrStatus;
Contains the return status of the signal handler: SUCCESS
if the signal has been properly catched or FAILURE if not
They are the only way the signal handler can comunicate and exchange
information with the rest of the application.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_SIGNAL_ILLEGAL illegal signal number
evhERR_SIGNAL_REG signal already registered
evhERR_SIGNAL_INST signal already installed
evhERR_INST_SIGNAL error installing the signal handler
evhERR_SIGNAL_NOT_INST signal not installed
eccsERR_NULL_PTR if a parameter has a NULL value, where a
legal pointer was expected
When an installed signal is deinstalled, the default signal handler
(SIG_DFL) is reinstalled.
The implementation has some limits: it assumes tha signals does not
occurr often or in bunches. Is a new signal occurs before another
one is served by the event handler, the old one gets lost.
A solution to this problem is to handle a queue of incoming signals.
This will be for a future release.
Remember that a signal handled in this way is not treated any more as
a real signal, because the callback in called later from the main loop
A more general solution could let the user to install also a real
signal handler (next release).
evhSIMPLE_TASK, evhTASK - Sample basic classes for applications using
the EVH(5) Event Handling toolkit
These are two very basic classes to be used as base classes for objects
using the event handling toolkit.
Future releases will provide other classes implementing commonly used
proramming patterns and standard behaviour and protocols defined for
the VLT project.
They are called evh*TASK because it is assumed that an instance of such
a class will be used in an application to take the responsibility of a
specific logical "task" or duty. This name is not directly related with
the concept of unix "process" and in one unix process can live several
evhTASK ojects at the same time.
They are subclasses of fndOBJECT, so that their methods can be used
as callback procedures, and of eccsERROR_CLASS, that provides errors
support to the classes.
evhSIMPLE_TASK only adds the concept of "name" of the task,
evhTASK() adds a standard way of handling the evhEXIT_CMD and
evhINIT_CMD commands
The classes makes use the default evhHandler to handle callbacks (EVH(5)).
evhSIMPLE_TASK:
evhSIMPLE_TASK(); Constructor
const char *Name() const; To retrieve the task name
evhTASK:
evhTASK(); Constructor
virtual ~evhTASK(); Destructor
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
virtual evhCB_COMPL_STAT ExitCB(msgMESSAGE &msg, void *udata);
This method is called whenever the evhEXIT_CMD command is
received. The callback is installed by the class constructor.
A standard behaviour is implemented only if there is just
one instance of evhTASK (or subclasses) in the application.
In this case, it prints and logs some diagnostics,
sends back an error reply and returns with the evhCB_RETURN bit
up, forcing in this way the MainLoop() method of the
evhHANDLER(3) to return.
If there are more instances, no action is taken (and no reply
is sent). Only a message is logged.
It is a duty of the application to overload the method for
a least one instance, in order to implement the desired
behaviour and send the final reply.
To change this behaviour a subclass need only to overwrite
the method.
evhCB_COMPL_STAT InitCB(msgMESSAGE &msg, void *udata)
This is the callback executed whenever a evhINIT_CMD command
is received.
By default it just calls the Init() hook method.
If there is only one instance of evhTASK (and subclasses)
in the application, is also sends a final reply back to
the caller
If there are more instances no reply is sent.
It is a duty of the application to overload the method for
a least one instance, in order to implement the desired
behaviour and send the final reply.
To change this behaviour a subclass need only to overwrite
the method.
ccsCOMPL_STAT Init()
Hook method to implement the evhINIT_CMD command.
By default it does nothing.
It is called by the InitCB method when the evhINIT_CMD command
is received.
It has been implemented as a separate method, so that it is
possible to call it directly programmatically, and not only
in response to an incoming command.
static ccsCOMPL_STAT LogExitWarning(vltLOGICAL=TRUE);
Static method used to turn ON/OFF logging of the warning
on EXIT command in case of multiple evhTASK instances.
By default the warning is ON and must be explicitely
turned OFF by the implementor, to insure that proper
handling of the EXIT command is implemented.
evhTASK:
static vltUINT32 TaskInstances()
Returns the number of instances of evhTASK (and sub classes)
currently allocated in the application
evhTASK:
static vltUINT32 counter;
Counter to store the number of instances of evhTASK (and sub
classes) currently allocated in the application
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_INVALID_EVH Invalid event handler
evhERR_SEND_REPLY Error sending a reply
This class gives a default implementation for the standard commands
that any VLT workstation application must provide.
These commands are:
// Command names
#define evhSTATE_CMD "STATE"
#define evhSTATUS_CMD "STATUS"
#define evhSTANDBY_CMD "STANDBY"
#define evhONLINE_CMD "ONLINE"
#define evhOFF_CMD "OFF"
#define evhSELFTST_CMD "SELFTST"
#define evhTEST_CMD "TEST"
#define evhSIMULAT_CMD "SIMULAT"
#define evhSTOPSIM_CMD "STOPSIM"
#define evhVERBOSE_CMD "VERBOSE"
#define evhVERSION_CMD "VERSION"
#define evhSTOP_CMD "STOP"
// Commands names already implemented in anchestor classes
// #define evhEXIT_CMD "EXIT" -> evhTASK
// #define evhPING_CMD "PING" -> evhTASK (now CCS)
// #define evhINIT_CMD "INIT" -> evhTASK
// Special commands handled by CCS
#define evhKILL_CMD "KILL"
#define evhBREAK_CMD "BREAK"
It also provides virtual methods that can be overloaded in sub-classes
to implement a specific behaviour.
Any application based on the evh toolkit should have an instance of this
class.
If a command must be handled in a specific way, the corresponding method
must be overloaded.
It is also possible to specify which commands must be handled by this
object, so that the remaining commands can be handled by other
more specialized objects.
If the object is not able to send a reply for a received command, an
error is logged, but it is immediately recovered, since it does not
matter if the requester of a command is not waiting any more for the
reply.
The class inherits from the base class evhDB_TASK(4) the support for the concept
of "db read/write" and "db read only" instances.
"db read only" instances only read their configuration parameters from the database
but never write any information on the database
"db read/write" instances also write their state and configuration in the database.
This allows for more instances to use the same database point as a
base for their configuration values. In this way it is possible to
dynamically create objects without having to know in advance
how many instances will be used and to put as many support
points in the database.
evhSTD_COMMANDS(const dbSYMADDRESS dbPoint,
int commands = evhSTD_CMD_ALL,
const char *version = "No version set")
The constructor receives the symbolic address of the
online database support point for the object, i.e. the point
where the object can find configuration and run time values.
It also register the callbacks for all the selected commands (by
default all the commands).
The second (optional) parameter contains the list of the selected
commands, obtained putting in OR the defines corresponding to
each command (it is a bit-mask):
// All commands
#define evhSTD_USE_ALL
// Standard commands
evhSTD_USE_STATE
evhSTD_USE_STATUS
evhSTD_USE_STANDBY
evhSTD_USE_ONLINE
evhSTD_USE_OFF
evhSTD_USE_SELFTST
evhSTD_USE_TEST
evhSTD_USE_SIMULAT
evhSTD_USE_STOPSIM
evhSTD_USE_VERBOSE
evhSTD_USE_VERSION
evhSTD_USE_EXIT
evhSTD_USE_STOP
evhSTD_USE_INIT
// Special commands handled by CCS
evhSTD_USE_KILL
evhSTD_USE_BREAK
evhSTD_USE_PING
The version parameter must be a pointer to a constant string:
the used string is not copied internally.
Usually it is just an RCS keyword, like in the following example.
const char *version =
"Version: @(#) $Id: evhSTD_COMMANDS.C,v 1.113 2001/09/18 10:50:19 vltsccm Exp $ Compiled:" __DATE__ " " __TIME__);
This provides the RCS version and the compile date and time.
~evhSTD_COMMANDS()
The destructor unregisters all the callbacks
The following methods implement the standard behaviour for the standard
commands and can be overloaded in sub classes.
virtual evhCB_COMPL_STAT StateCB(msgMESSAGE &msg, void *udata);
Reply with the current state. The buffer contains the string name
virtual evhCB_COMPL_STAT StatusCB(msgMESSAGE &msg, void *udata);
Reply with the current state. The buffer contains the message:
"State: %s", where %s is ste current state name
virtual evhCB_COMPL_STAT StandByCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT OnlineCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT OffCB(msgMESSAGE &msg, void *udata);
Sets the state to what requested and send a reply.
virtual evhCB_COMPL_STAT SelfTestCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT TestCB(msgMESSAGE &msg, void *udata);
Return an "OK" last reply
virtual evhCB_COMPL_STAT SimulatCB(msgMESSAGE &msg, void *udata);
virtual evhCB_COMPL_STAT StopSimCB(msgMESSAGE &msg, void *udata);
Turn ON/OFF simulation setting the database attribute to the
requested value and send a reply
virtual evhCB_COMPL_STAT VerboseCB(msgMESSAGE &msg, void *udata);
Turn ON/OFF verbose mode setting the database attribute to the
requested value and send a reply
virtual evhCB_COMPL_STAT VersionCB(msgMESSAGE &msg, void *udata);
Return a reply with the objects version
virtual evhCB_COMPL_STAT StopCB(msgMESSAGE &msg, void *udata);
Returns an "OK" reply
vltLOGICAL Simulation();
ccsCOMPL_STAT Simulation(vltLOGICAL value);
Retrieves/sets the value of the "simulation" flag from database
vltLOGICAL Verbose();
ccsCOMPL_STAT Verbose(vltLOGICAL value);
Retrieves/sets the value of the "verbose" flag from database
evhSTD_COMMANDS(); The protected constructor with no parametrs cannot
be used to build real instances.
It is provided in order to allow the implementation
of the standard foundation class methods
virtual evhCB_COMPL_STAT SetStateCB(vltINT32 newState,
msgMESSAGE &msg,
void *udata);
Used internally to set the state to the requested value and send
back a reply to the sender of 'msg'.
vltUINT32 commands; // Bitmap of the handled commands
const char *version; // Pointer to the string with the version id
eccsDB_LOGICAL simulation;
eccsDB_LOGICAL verbose;
Database access objects to retrieve and set 'simulation' and 'verbose'
flags
class evhDB_TASK evhSTD_COMMANDS
BEGIN //
ATTRIBUTE LOGICAL simulation // simulation mode
ATTRIBUTE LOGICAL verbose // verbose mode
END //
The class evhSYNC can be used whenever an application needs to be waked
up after a set of conditions is verified, with no regard for the order
in which they occurr.
When an instance of this class is used, it is possible to specify:
- A set of requested conditions.
- The callback procedure to trigger when all the conditions are
satisfied.
- An optional timeout and a callback procedure to be triggered if
not all the conditions are satisfied when the timeout expire.
In the simplest case, a condition is just an event, as described by a
evhMSG_TYPE_KEY(3).
It is also possible to specify a flag to be tested for a specific
value. This can be used when it is important that not only the required
event occurs, but also that some condition defined by the event will be
verified also later, when another of the required events occurrs.
Whenever one of the registerd events occurrs, a check is made to
verify if all the requested events have occurred AND all the
(optional) flags have the required value. If the check is positive,
the installed callback procedure is triggered.
When the conditions and the callbacks have been set, a call to the Run()
method activates the object..
After the call to the Run() method, the object listen for the
requested events and it is not possible to modify the installed callback
procedures or trigger conditions.
The method Check() forces the evhSYNC() to check the conditions. If
all the conditions are satisfied, the installed action is triggered.
The method Reset() can be used to force a disable of the monitoring.
When the monitoring is desabled (after a Reset(), after a triggering
of the installed action or after a timeout) it is possible to change
the callback procedures and the actions calling AddCondition() to add
new conditions or ClearConditions() to clean up the list of conditions.
The class makes use the default evhHandler to handle callbacks (EVH(5)).
evhSYNC();
~evhSYNC();
Constructor and destructor. The destructor calls Reset()
before deleting the object and removes all the callbacks.
ccsCOMPL_STAT Action(evhCALLBACK &newCB = NULL);
Set the callback to be executed when all the conditions are
satified. The argument is a reference to an evhCALLBACK(3) (or
subclass) instance.
If the object is already handling a syncronizzation (i.e. the
Run() method has already been executed and the monitoring
of the events is taking place), the error evhERR_HANDLE_SYNC
is generated.
If any other error occurs, the error evhERR_INST_SYNC is generated.
ccsCOMPL_STAT AddCondition(const evhMSG_TYPE_KEY &key,
int *flag = NULL, int value = TRUE);
This method is used while initializzating the evhSYNC object
to add a new condition to the list what has to be monitored.
In the simplest case, the condition is just a CCS event as
defined by passing as argument a reference to an instance of
evhMSG_TYPE_KEY(3).
It is also possible to specify a flag to be tested for a specific
value. In this case it is necessary to pass also the following
arguments:
int *flag - a pointer to a variable of type int. This
variable is property of some other object living
in the application and must exist for the whole
lifetime of the evhSYNC. Whenever an event
occurrs, the evhSYNC will read this variable
to check if it has the required value.
int value - the required value for flag. TRUE by default.
If the object is already handling a syncronizzation (i.e. the
Run() method has already been executed and the monitoring
of the events is taking place), the error evhERR_HANDLE_SYNC
is generated.
ccsCOMPL_STAT Timeout(evhCALLBACK &cb, eccsTIMEVAL interval);
ccsCOMPL_STAT Timeout(eccsTIMEVAL interval);
Set the callback to be executed when the timeout expires before
that all the required conditions are satisfied.
The first argument is a reference to an evhCALLBACK(3)
(or subclass) instance., the second is the length of the timeout.
If no timeout is set, the evhSYNC waits until all conditions are
verified or and explicit Reset() of the object is requested.
If the object is already handling a syncronizzation (i.e. the
Run() method has already been executed and the monitoring
of the events is taking place), the error evhERR_HANDLE_SYNC
is generated.
If any other error occurs, the error evhERR_INST_SYNC is generated.
virtual int Check();
This method scans all the conditions to verify if they all have
occurred AND the flag (if any) has the requested value.
If the response is affirmative returns TRUE, otherwise
returns FALSE.
virtual ccsCOMPL_STAT ClearConditions();
Executes a Reset() and clear all the conditions.
It can be used to clean the object when a completely new set
of conditions has to be installed.
virtual ccsCOMPL_STAT Reset();
Reset the object deleting all the callbacks for pending events.
If the object was not waiting for events, nothing happens.
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
virtual ccsCOMPL_STAT Run();
This method activates the object, starting waiting for the
occurring of the events and of the timeout.
It always checks first if all the requested conditions are
already satisfied. In this case, it immediately executes
the callback registered with the Action() method. If this
callback returns with the evhCB_FAILURE bit up, the error
evhERR_RUNCB is generated.
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
If any other error occurs, the error evhERR_INST_SYNC is generated.
Run() called inside a callback function is ignored.
virtual vltLOGICAL Status();
Returns thetatus of the object: TRUE if it is active, FALSE is not
virtual evhCB_COMPL_STAT HandlerCB(msgMESSAGE &msg, void *udata);
Default handler function called when one of the registered
events occuurs.
It is called by _HandlerCB and is meant to make easier the
implementation of special behaviours.
Subclasses can overload it to implement special handling,
but must not overload _HandlerCB that provides the basic engine
features.
The default behaviour impelmented by HandlerCB is to:
- return evhCB_DELETE on a last reply
- return evhCB_NO_DELETE and send an "OK" default reply
on receiving a command
- return evhCB_NO_DELETE in all other cases
virtual evhCB_COMPL_STAT _HandlerCB(msgMESSAGE &msg, void *udata);
This protected method is the callback procedure actually executed
whenever one of the registered events occurs.
Whenever it is called, it:
- Search for the event in the list of all the registered
events and update its status .
- Checks if all the requested conditions are verified.
- If so:
- immediately executes the callback registered with
the Action() method.
- if this callback returns with the evhCB_FAILURE bit up,
the error evhERR_RUNCB is generated.
- executes a Reset(), because the task is complete
- else returns to the event handler with evhCB_DELETE,
because each event is monitored only once.
virtual evhCB_COMPL_STAT _TimeoutCB(msgMESSAGE &msg, void *udata);
This protected method is the callback procedure actually executed
whenever the timeout occurrs.
Whenever it is called, it:
- Checks if all the requested conditions are verified.
- If so, immediately executes the callback registered with
the Action() method.
- Else executes the callback registered with
the Timeout() method.
- If this callback returns with the evhCB_FAILURE bit up,
the error evhERR_RUNCB is generated.
- executes a Reset(), because the task is complete
vltLOGICAL status;
Status of the object: TRUE if it is active, FALSE is not
evhCALLBACK *cb;
Pointer to the evhCALLBACK object holding the information
for the callback to be executed when all the conditions are
satisfied.
The object itself is dynamically allocated.
evhCALLBACK *timeout;
Pointer to the evhCALLBACK object holding the information
for the callback to be executed when the timeout expires
and the conditions are not satisfied.
The object itself is dynamically allocated.
eccsTIMEVAL interval;
The length of the timeout (0 if no timeout)
evhTIMEOUT *timeHndl;
The instance of evhTIMEOUT(3) used to handle the timeout.
The object itself is dynamically allocated.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_HANDLE_SYNC Instance already handling a syncronizzation
evhERR_INST_SYNC Cannot install the syncronizzation instance
evhERR_RUNCB Error while running a callback
evhERR_INVALID_EVH Invalid event handler
Run() method called from inside a callback function is always ignored.
An event set with AddCondition() if considered "happened" when the first
CCS message matching the key is received. No check is done on the
event itself. For example it is not checked if it is the last reply or not.
In order to specialyze the behaviour of the class, it is necessary to
derive a subclass overloading the _HandlerCB() method.
Future releases will provide new classes to implement a specific protocol,
when the requirements will be available.
EVH(5), evhHANDLER(3), eccsERROR_CLASS(3), evhMSG_TYPE_KEY(3),
evhCALLBACK(3), evhOBJ_CALLBACK(3), evhTIMEOUT(3)
An instance of the class evhTIMEOUT can be used whenever an application
needs to be waked up after a certain ammount of time
When an instance of the class is created, it installs a callback
procedure. This will be triggered when the timeout expires.
The received CCS message will contain the following event:
message type: msgTYPE_COMMAND
command name: evhTIMEOUT_CMD
command id : unique number
where the unique number is generated automatically and uniquelly
identify the timeout among all the timeouts installed by the running
application.
Upon return from the callback procedure, the evhTIMEOUT destroy itself
cleaning up all the used resources.
An explicit delete of the timeout object BEFORE the callback procedure
after the timeout is called, cleanup the timeout itself.
The class makes use the default evhHandler to handle callbacks (EVH(5)).
evhTIMEOUT(evhCALLBACK &user_cb, eccsTIMEVAL interval);
Constructor.
It gets as arguments an evhCALLBACK reference to define the callback
procedure that must be executed when the timeout expires and
the length of the timeout.
It also generates a unique identification number for the timeout
that will be sent as command ID when the timeout expires.
The timeout is immediately active and starts counting down.
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
If any other error occurrs the error evhERR_INST_TIMEOUT is generated
~evhTIMEOUT();
Destructor.
If the timeout was running cancel the timer request (if
pending) and the callbacks installed, then deletes all the
dynamically allocated data members.
If the standard evhHandler instance of evhHANDLER(3) is not
properly allocated, generates the error evhERR_INVALID_EVH
virtual int IsEqual( const fndOBJECT& ) const;
Overwrite of standard fndOBJECT methods
evhTIMEOUT(evhCALLBACK &user_cb);
This protected constructor can be used by subclasses.
It behaves the same of the public one, but does not activate
the object.
vltLOGICAL Status() const;
Returns TRUE if the object is active, i.e. if the timer is counting
down, FALSE if not.
virtual int TimeoutCB(msgMESSAGE &msg, void *udata);
This protected method is the callback procedure actually executed
whenever the timeout occurrs.
Whenever it is called, it immediately executes the callback
registered in the constructor.
If this callback returns with the evhCB_FAILURE bit up,
the error evhERR_RUNCB is generated.
Before returning, the object deletes themself and cannot be
used any more.
It returns the bitmask returned by the executed callback.
void Init(evhCALLBACK &user_cb);
This method is used by the constructors to have in a single place
the common code.
vltUINT32 requestId;
Id for the CCS timer request
evhCALLBACK *cb;
Pointer to the evhCALLBACK object holding the information
for the callback to be executed when the timeout expires.
The object itself is dynamically allocated.
evhMSG_TYPE_KEY key;
Key to identify the timer event (used when adding and deleting
callbacks).
static vltUINT32 count;
This static class data member is a progressive counter used to
uniquely identify the sent timer request.
static msgMESSAGE cmd;
Static data buffer where to temporarily store the incoming
messages.
These protected data members will become PRIVATE in the next release
of the software and protected access methods will provide an interface
toward them.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_INST_TIMEOUT Error installing the timeout
evhERR_INVALID_EVH Invalid event handler
evhERR_RUNCB Error while running a callback
The evhTIMEOUT object automatically deletes itself when the timeout
expires and the callback procedure has been executed. This means that
the user must never trust on pointers to instances of the class but
it must use other techniques to check from outside if a timeout is
running or not.
Subclasses could implement a special behaviour and more powerfull
clases could be issued for the next release of the library.
The evhTimeout class base assigns automatically a new identifier to
each instance using a counter kept in a static data member:
static vltUINT32 count;
This counter is defined as a vltUINT32, but is actually
handled internally by the CCS message system as a vltUINT16
This means that after MAXSHORT ( 65535 ) it overflows.
This normally should not have major consequences but on
applications which are creating many timer and that keep them
running for a long time, it is possible that a new evhTimeout gets
an identifier already in use by another instance, with
unpredictable behavior.
Spr.19980435 describes this problem and identifies a strategy to
implement a solution.
On the other hand, this has never caused practical problems
and has been decided not to modify core components of the system
unless a practical situation imposes to do that.
An instance of the class evhTIMER can be used whenever an application
needs to be waked up periodically.
When an instance of the class is created, it installs a callback
procedure. This will be triggered periodically with the defined time
interval.
The received CCS message will contain the following event:
message type: msgTYPE_COMMAND
command name: evhTIMEOUT_CMD
command id : unique number
where the unique number is generated automatically and uniquelly
identify the timeout among all the timeouts installed by the running
application.
Upon return from the callback procedure, the evhTIMER destroy itself
if the callback return value was evhCB_DELETE. If it was
evhCB_NO_DELETE the timer keeps running.
An explicit delete of the timer object, cleanup the timer itself.
The evhTIMER is a subclass ov evhTIMEOUT and all the same
considerations applies.
The class makes use the default evhHandler to handle callbacks (EVH(5)).
evhTIMER(evhCALLBACK &user_cb, eccsTIMEVAL interval);
evhTIMER(evhCALLBACK &user_cb, eccsTIMEVAL interval, ccsTIMEVAL startTime);
Constructors.
They installs a periodic timer with the given time interval.
The first one starts immediately the timer, the second one will
start the timer at the given absolute time startTime.
If any specific error occures, the error evhERR_INST_TIMER is
generated.
virtual int TimeoutCB(msgMESSAGE &msg, void *udata);
Overwrite of the method inherited from the base class evhTIMEOUT.
This protected method is the callback procedure actually executed
whenever a timer tick occurrs.
Whenever it is called, it immediately executes the callback
registered in the constructor.
If the callback return with the evhCB_DELETE bit up or is no
callback is registered, the object deletes itself, otherwise
it is ready for another timer tick.
If this callback returns with the evhCB_FAILURE bit up,
the error evhERR_RUNCB is generated.
Before returning, the object deletes themself and cannot be
used any more.
It returns the bitmask returned by the executed callback.
If the function prototype allows, methods return ccsCOMPL_STAT.
If it is not possible, error conditions can be retrieved using the
services provided by the parent class eccsERROR_CLASS(3) (when
an error is generated, it is logged on the error stack and the status
is set to ccsFAILURE).
Methods can generate the following errors:
evhERR_INST_TIMER Error while installing the timer
The evhTIMER object automatically deletes itself when the callback
returns evhCB_DELETE. This means that the user must never trust on
pointers to instances of the class but it must use other techniques
to check from outside if a timeout is running or not.
Subclasses could implement a special behaviour and more powerfull
clases could be issued for the next release of the library.
The evhTimeout class base assigns automatically a new identifier to
each instance using a counter kept in a static data member:
static vltUINT32 count;
This counter is defined as a vltUINT32, but is actually
handled internally by the CCS message system as a vltUINT16
This means that after MAXSHORT ( 65535 ) it overflows.
This normally should not have major consequences but on
applications which are creating many timer and that keep them
running for a long time, it is possible that a new evhTimeout gets
an identifier already in use by another instance, with
unpredictable behavior.
Spr.19980435 describes this problem and identifies a strategy to
implement a solution.
On the other hand, this has never caused practical problems
and has been decided not to modify core components of the system
unless a practical situation imposes to do that.
3.2 Utilities and programs
The program can be dynamically configured via a command
interface to reply to any command. You can dynamically tell to the
program how to behave when it receives any command: - What kind of
reply it has to send (normal/error) - What message buffer to send -
What error code in case of error reply - After how many seconds from
the receiving of the command it must send the reply.
There is no limit to the number of commands that can be
handled by the same instance of the dummy and on the dynamic
configuration chanes you can request while it is running.
When the program is started it can read from a file an initial
configuration containing a list of commands and reply descriptions.
Empty lines are ignored and lines starting with '#' are comments.
Every record in the file has comma delimited fields with the
following meaning:
<cmd name>,<reply buffer>,<err reply>,<err code>,<timeout>
The <reply buffer> can be enclosed in quotes (for example
in order to define replies containing commas). The enclosing
quotes are removed. It is not possible to register replies
containing quotes.
The file is searched calling the standard ccsOpenFile() function
Using the command line option -n procName, it is possible to register
to the message system the evhDummy process with the given process
name. This name will have to be used to send it messages in place
of the executable's name.
Using the command line option -d dbstate, allows appropriate state changes
of the given database state attribute. It must be of type INT32.
The commands OFF, INIT, STANDBY and ONLINE are supported.
While it is running it accepts the following configuration
commands:
REGCMD <cmd name>,<reply buffer>,<err reply>,<err code>,<timeout>
Register command
To add a new command to the list of accepted commands or
to change the behaviour of an existing one.
The <reply buffer> can be enclosed in quotes (for example
in order to define replies containing commas). The enclosing
quotes are removed. It is not possible to register replies
containing quotes.
UREGCMD Un-register command
To delete a command from the list of accepted commands
PRNCMD Print command list
To print on standard output the list of accepted commands
and their configuration parameters.
DMEXIT Exit the program
All the informations about commands received and replies sent
are exensively logged on stdout and/or on the CCS logging system.
The program can be used in the following ways:
- During development to easily replace not yet available processes.
- During testing of a process to replace the processes this
one has to send commands. A test script sets the dummy
configuration, then stymulate the program under test to send
commands to it, then changes the dummy configuration and so
on. In this way it is much easier to test the dynamical
behaviour of a process, taking into account also timeouts
and timing constraints.
The log report can be used to verify the tests and, along
with eccsTestDriver, to write automatic tests.
The program is easily extensible and new features (if
necessary) can be added.
The class evhDUMMY used as a basic component is available
as a public evh class to develop user specific dummies.
This is a small control panel that can be used to interactively send commands to an instance of evhDummy, in order to configure it.
The following figure shows the interface of the panel and describes the available functionalities
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
