DcppHandler Class Reference

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.
	DcppHandler (DcppCallbackBase *CallbackObj, const float Timeout=-1)
	Construct a DcppHandler object.
virtual	~DcppHandler ()
	Destructor.
virtual void	DeInstall (StatusType *const status)
	Remove this handler.
virtual StatusType	ErrorStatus () const
	Return the status associated with the first error event.
virtual DcppVoidPnt	GetData () const
	Return the client data value.
void	HandleReschedule (StatusType *status)
	Used internally to handle a reschedule event.
virtual void	Install (StatusType *status, int threads=1)
	Install this handler object for the current action.
virtual void	NewThread ()
	Increase the thread count by one.
void	operator++ ()
	Increase the thread count by one.
void	operator++ (int)
	Increase the thread count by one.
virtual void	SetData (const DcppVoidPnt ClientData)
	Change the handler routine client data item.
virtual void	SetError (const DcppHandlerRoutine ErrorHandler)
	Change the error handler routine.
virtual void	SetFinished (const DcppHandlerRoutine FinishedHandler)
	Change the finished handler routine.
virtual void	SetMultiCallErrorMode (int enable=true)
	Set the multi error call mode.
virtual void	SetTimeout (const DcppHandlerRoutine TimeoutHandler, const float Timeout)
	Set a timeout handler routine and new timeout.
virtual void	SetTimeout (const float Timeout)
	Change the timeout.
void	SetupTimeout (const float Timeout)
	Used internally.
virtual int	ThreadCount () const
	Return the number messages being controlled at the moment.
void	Wait (DitsTransIdType transId, StatusType *status, double timeout=0)
	Wait for the completion of the action supplied with the transaction id.
void	WaitAll (StatusType *status, double timeout=0)
	Wait for all outstanding messages to complete.

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.

---

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

• dcpphandler.h