A DRAMA Action reschedule handler used in conjunction with DcppTask. More...

#include <dcpphandler.h>

Public Member Functions
	DcppHandler (const DcppHandlerRoutine FinishedHandler=0, const DcppHandlerRoutine ErrorHandler=0, const DcppVoidPnt ClientData=0, const float Timeout=-1)
	Construct a DcppHandler object. More...

	DcppHandler (DcppCallbackBase *CallbackObj, const float Timeout=-1)
	Construct a DcppHandler object. More...

virtual void	Install (StatusType *status, int threads=1)
	Install this handler object for the current action. More...

virtual void	DeInstall (StatusType *const status)
	Remove this handler. More...

virtual void	SetFinished (const DcppHandlerRoutine FinishedHandler)
	Change the finished handler routine. More...

void	Wait (DitsTransIdType transId, StatusType *status, double timeout=0)
	Wait for the completion of the action supplied with the transaction id. More...

void	WaitAll (StatusType *status, double timeout=0)
	Wait for all outstanding messages to complete. More...

virtual void	SetError (const DcppHandlerRoutine ErrorHandler)
	Change the error handler routine. More...

virtual void	SetData (const DcppVoidPnt ClientData)
	Change the handler routine client data item. More...

virtual void	SetTimeout (const float Timeout)
	Change the timeout. More...

virtual void	SetTimeout (const DcppHandlerRoutine TimeoutHandler, const float Timeout)
	Set a timeout handler routine and new timeout. More...

virtual void	SetMultiCallErrorMode (int enable=true)
	Set the multi error call mode. More...

virtual StatusType	ErrorStatus () const
	Return the status associated with the first error event. More...

virtual DcppVoidPnt	GetData () const
	Return the client data value. More...

virtual int	ThreadCount () const
	Return the number messages being controlled at the moment. More...

void	operator++ ()
	Increase the thread count by one. More...

void	operator++ (int)
	Increase the thread count by one. More...

virtual void	NewThread ()
	Increase the thread count by one. More...

virtual	~DcppHandler ()
	Destructor. More...

void	HandleReschedule (StatusType *status)
	Used internally to handle a reschedule event. More...

void	SetupTimeout (const float Timeout)
	Used internally. More...

Detailed Description

A DRAMA Action reschedule handler used in conjunction with DcppTask.

This class completely hides the details of action rescheduling in the case where an action is sending messages using DcppTask objects.

When a DcppHandler:: object is installed for the current action, it calls DitsPutObeyHandler(), supplying its own routine to handle future reschedules of the action. The idea is that the various handlers will be invoked when events occur and DcppDispatch() is invoked to handle replies to messages send by DcppTask:: class messages.

Handler functions, by returning DcppReschedule, indicate that rescheduling should occur. Otherwise they should return DcppFinished.

By default, the object handles one thread of control - i.e. messages resulting from one obey/kick etc. message. The user can handle multiple threads by ensuring their handlers return DcppReschedule if there are other messages outstanding.

Alternatively, the user may invoke the increment operator on the object (post or pre increment will work) once for each additional thread (each additional message sent)

Note, to allow consistency in calls, you may specify the optional threads argument to Install as 0, which means you must call the increment operator for every thread.

The finished handler is called after all threads have completed. By default, the error handler will be called instead of the finished handler if any thread completed with an error. The user may invoke ErrorStatus to get the status associcated with the first error while subsequence errors are reported using ErsRep. It is possible for the error handler to be invoked once for every thread which completes with an error. This is enabled by calling SetMultiCallErrorMode. In this case, if the last thread to complete completes without an error, then the finished handler will be invoked.

Warning: In that past some applications have deleted the DcppHandler object being used to rechedule the action from within one of the handler routines (either one of DcppHandler's callbacks or a DcppTask call back invoked by DcppHandler. This is incorrect as it means the object is destroyed before it is finished being used. The correct behaviour is to use DitsPutActEndRoutine() to insert a function to be invoked when the action completes. This function can then delete the handler. To support existing code, deletion of the DcppHandler object whilst being used is detected and will print a message to stderr before causing the action to complete.

Constructor & Destructor Documentation

DcppHandler::DcppHandler	(	const DcppHandlerRoutine	FinishedHandler = `0`,
		const DcppHandlerRoutine	ErrorHandler = `0`,
		const DcppVoidPnt	ClientData = `0`,
		const float	Timeout = `-1`
	)

Construct a DcppHandler object.

Note that to actually make this object responsiable for handling the rescheduling of an action, you should invoke DcppHandler::Install and DitsPutRequest(DITS_REQ_MESSAGE,status).

Parameters

FinishedHandler	A routine to be invoked when the all subsidary messages have completed and the DcppHandler:: object is intending to cause the action to complete. If it returns DcppReschedule, the action will continue. Otherwise the action will complete.
ErrorHandler	Invoked if an error occurs whilst dispatching a message. See class description for more details.
ClientData	Passed to the handler functions.
Timeout	If no messages are received for this number of seconds, the timeout handler, if any, is invoked. If there is no timeout handler, this event is triggered as an error. A negative value indicates no timeout is to be enabled.

DcppHandler::DcppHandler	(	DcppCallbackBase *	CallbackObj,
		const float	Timeout = `-1`
	)

Construct a DcppHandler object.

Note that to actually make this object responsiable for handling the rescheduling of an action, you should invoke DcppHandler::Install and DitsPutRequest(DITS_REQ_MESSAGE,status).

The DcppHandler takes ownership of the CallbackObj.

Parameters

CallbackObj	A callback object that defines 2 methods (i) Finished() and (ii) Error(). The Finished() method is invoked when all the subsidary messages have completed and the DcppHandler object is intending to cause the action to complete. The Error() method is invoked if an error occurs while dispatching a message. See DcppCallbackBase class description for mote details.
Timeout	If no messages are received for this number of seconds, the timeout handler, if any, is invoked. If there is no timeout handler, this event is triggered as an error. A negative value indicates no timeout is to be enabled.

virtual DcppHandler::~DcppHandler ( )

virtual

Destructor.

Member Function Documentation

virtual void DcppHandler::DeInstall ( StatusType *const status )

virtual

Remove this handler.

All this actually does is restore the value put by DitsPutActData() which was overwritten by DcppHandler::Install

Parameters

status Inherited status

virtual StatusType DcppHandler::ErrorStatus ( ) const

inlinevirtual

Return the status associated with the first error event.

virtual DcppVoidPnt DcppHandler::GetData ( ) const

inlinevirtual

Return the client data value.

void DcppHandler::HandleReschedule ( StatusType * status )

Used internally to handle a reschedule event.

virtual void DcppHandler::Install	(	StatusType *	status,
		int	threads = `1`
	)

virtual

Install this handler object for the current action.

This handler will now take over reschedule events for this action. Note that DitsPutActData() is invoked and the action data overwritten.

Parameters

status	Inherited status
threads	The number of simulateous messages which will be outstanding at any one time. Normally this is left as the default (1) or set to 0. In the later case, DcppHandler::NewThread is invoked each time a new message is sent.

virtual void DcppHandler::NewThread ( )

inlinevirtual

Increase the thread count by one.

This tell the handler that another message has been sent which is to be managed by this handler. The thread count is the number of times a DcppFinished value should be returned by a DcppTask:: handler functions before the action is allowed to complete.

void DcppHandler::operator++ ( )

inline

Increase the thread count by one.

Deprecated:: Prefer DcppHandler::NewThread

void DcppHandler::operator++ ( int )

inline

Increase the thread count by one.

Deprecated:: Prefer DcppHandler::NewThread

virtual void DcppHandler::SetData ( const DcppVoidPnt ClientData )

inlinevirtual

Change the handler routine client data item.

Parameters

ClientData Passed to the handler functions.

virtual void DcppHandler::SetError ( const DcppHandlerRoutine ErrorHandler )

inlinevirtual

Change the error handler routine.

Parameters

ErrorHandler Invoked if an error occurs whilst dispatching a message. See class description for more details.

virtual void DcppHandler::SetFinished ( const DcppHandlerRoutine FinishedHandler )

inlinevirtual

Change the finished handler routine.

Parameters

FinishedHandler A routine to be invoked when the all subsidary messages have completed and the DcppHandler:: object is intending to cause the action to complete. If it returns DcppReschedule, the action will continue. Otherwise the action will complete.

virtual void DcppHandler::SetMultiCallErrorMode ( int enable = true )

inlinevirtual

Set the multi error call mode.

When set true, this mode results in the error handler being invoked for all errors, instead of the default of just once.

virtual void DcppHandler::SetTimeout ( const float Timeout )

virtual

Change the timeout.

Parameters

Timeout If no messages are received for this number of seconds, the timeout handler, if any, is invoked. If there is no timeout handler, this event is triggered as an error. A negative value indicates no timeout.

virtual void DcppHandler::SetTimeout	(	const DcppHandlerRoutine	TimeoutHandler,
		const float	Timeout
	)

inlinevirtual

Set a timeout handler routine and new timeout.

Parameters

TimeoutHandler	Invoked if a timeout occurs
Timeout	The new timeout. A negative value indicates no timeout is to be enabled.

void DcppHandler::SetupTimeout ( const float Timeout )

Used internally.

virtual int DcppHandler::ThreadCount ( ) const

inlinevirtual

Return the number messages being controlled at the moment.

void DcppHandler::Wait	(	DitsTransIdType	transId,
		StatusType *	status,
		double	timeout = `0`
	)

Wait for the completion of the action supplied with the transaction id.

This method waits for the action with the given transaction id to complete. The main reason for this implementation is that sometimes, application code wants to issue an OBEY command and then instead of rescheduling the action, it wants to wait for this command/action to run to completion. One may be tempted to structure the code like this : DcppTask.Obey(ACTION_X,&transId....) DitsActionWait(....) DcppDispatch(....)

However, the above code segment may not work correctly when the number of messages which will be outstanding at any one time is greater than one i.e (thread count > 1). This is because the above code segment does not decrement the thread count when the action is finished.

The correct way of acheiving the above result is : DcppTask.Obey(ACTION_X,&transId....) DcppHandler.Wait(transId);

What the Wait() method does is as described below : (i) invokes DitsActionWait() on the supplied transaction id. (ii) invokes HandleReschedule() which in turns calls DcppDispatch(). It also correctly manages the thread count by decrementing the thread count by one everytime the DcppHandlerRoutine returns DcppFinished. (iii) If for any reason the DcppHandler object does not want to wait for more events, but your target event has not been seen, then the status will be set to DCPP__WAITFAIL. (other then timeout events, see timeout argument)

Remarks: Beware that if you invoke this function from a DcppTask message response handler function, then you must have incremented the thread count for each message you sent from that handler function. (Adding a DcppHandler.NewThread() call before the wait in the above example) You would then normally return DcppFinished from the invoking handler function.

Parameters

transId	transaction id of the action which is pending for completion
status	Inherited status
timeout	if positive, this is the timeout to apply for wait operation. If this is triggered, then the Timeout handler associated with the DcppHandler object is triggred. The default handler will set the status to DCPP__TIMEOUT. In eiter case, DitsGetEntReason() will return DITS_REA_RESCHED.

void DcppHandler::WaitAll	(	StatusType *	status,
		double	timeout = `0`
	)

Wait for all outstanding messages to complete.

This method waits for all outstanding messages which are being managed by this handler to complete.

Remarks: Beware that if you invoke this function from a DcppTask message response handler function, then you must have incremented the thread count for each message you sent from that handler function. You would then normally return DcppFinished from the invoking handler function.

Parameters

status	Inherited status
timeout	if positive, this is the timeout to apply for wait operation. If this is triggered, then the Timeout handler associated with the DcppHandler object is triggred. The default handler will set the status to DCPP__TIMEOUT. In eiter case, DitsGetEntReason() will return DITS_REA_RESCHED.

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

dcpphandler.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation