DRAMA C++ Intro   Class Hierarchy   Alphabetical List of types   List of Classes   File List   Class Member Index   File Members Index   Related Pages  

DcppHandler Class Reference

#include <dcpphandler.h>

List of all members.


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.


Public Methods

 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 void Install (StatusType *const status, int threads=1)
 Install this handler object for the current action.

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

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

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.

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

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

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

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

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

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

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

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

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

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

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

virtual ~DcppHandler ()
 Destructor.

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

void SetupTimeout (const float Timeout)
 Used internally.


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 [inline, virtual]
 

Return the status associated with the first error event.

virtual DcppVoidPnt DcppHandler::GetData   const [inline, virtual]
 

Return the client data value.

void DcppHandler::HandleReschedule StatusType *    status
 

Used internally to handle a reschedule event.

virtual void DcppHandler::Install StatusType *const    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   [inline, virtual]
 

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++ int    [inline]
 

Increase the thread count by one.

Deprecated:
Prefer DcppHandler::NewThread

void DcppHandler::operator++   [inline]
 

Increase the thread count by one.

Deprecated:
Prefer DcppHandler::NewThread

virtual void DcppHandler::SetData const DcppVoidPnt    ClientData [inline, virtual]
 

Change the handler routine client data item.

Parameters:
ClientData  Passed to the handler functions.

virtual void DcppHandler::SetError const DcppHandlerRoutine    ErrorHandler [inline, virtual]
 

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 [inline, virtual]
 

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 [inline, virtual]
 

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 DcppHandlerRoutine    TimeoutHandler,
const float    Timeout
[inline, virtual]
 

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.

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.

void DcppHandler::SetupTimeout const float    Timeout
 

Used internally.

virtual int DcppHandler::ThreadCount   const [inline, virtual]
 

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:

Click here for the DRAMA home page and here for the AAO home page.

For more information, contact tjf@aaoepp.aao.gov.au 

Generated on Tue Nov 3 09:09:56 2009 for AAO DRAMA C++ Interfaces by doxygen 1.2.18