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

GitTask Class Reference

#include <gittask.h>

Inheritance diagram for GitTask:

DcppTask List of all members.

Detailed Description

A class built on DcppTask which control AAO GIT Tasks.

DcppTask intended to abstract the control of tasks which obey the GIT specification.

The basic concept is that much of the time, we will want to perform the same operation (say INITIALISE/RESET) on every task we control. This class can implement that operation using the underlying DcppTask primitives providing us with a simple interface.

Then all we need to do to perform such an action is to loop round a list of the tasks invoking the appropiate function for each task.

Now when a particular type of task needs to modify such an operation, it can sub-class GitTask. Thus the general parts of a control such as Initialisation, are presented with a standard interface, regardless of the types of tasks being controlled.

Each GitTask object may be put on one of two internally supported lists, classes for both of which are defined in the assocaited include file. An object of class GitTaskActiveList is used to maintain a list of the currently controlled tasks. GitTaskKnownList is used to maintain a list of all known task objects, whether currently controlled or not. Note that both these lists are special purpose lists that make use of data storage within the GitTask object type and thus each task can only be on one of each type of this list at a time (which is normally all the the program requires).

We also define an Iterator class for each list type.

For each method which returns a DcppHandlerType, action rescheduling should be handled using DcppDispatch() (or via a DcppHandler object).

Each of these such methods also take an optional address of an object of type GitTaskResponseHandler. The CompleteOk() method of this object is invoked if the operation completes ok, whilst the CompleteWithError()method is invoked if it completes in error. The Triggered() method is invoked if a trigger message is received. This object is only used if the call returned DcppReschedule. If not supplied, then a default version is used with does nothing but return DcppFinished such that DcppDispatch()/ DcppHandler() know the action is complete.

An optional third argument, freeHandler, can be used to indicate the GitTaskResponseHandler object, if any, should be deleted using the delete operator after the CompleteOk/CompleteError method is invoked.

If you want notifiction of completion, you should subclass GitTaskResponseHandler appropiately.

There are a set of functions called when the state of the task is seen to change. These may be overriden as required, but the GitTask version should also be invoked. Most take a status argument, but SetFailed() and SetDied() need to work regardless so don't take a status argument.


Public Types

enum  SelfPathType
 Use to ensure the constructor knows it is constructing a self path. More...


Public Methods

 GitTask (const std::string &name, const std::string &node="", const std::string &file="")
 Construct a GitTask object.

 GitTask (SelfPathType self)
 Path to self constructor.

virtual void SetSimulation (const std::string &value, const float TimeBase, const std::string &string, StatusType *status)
 Set simulation and timebase.

virtual void SetResetMode (GitResetType &mode, StatusType *status)
 Set the reset mode.

virtual DcppHandlerRet Initialise (StatusType *status, GitTaskResponseHandler *responseHandler=0, bool freeResponse=false)
 Perform the complete initialisation sequence for a GIT task.

virtual DcppHandlerRet Poll (StatusType *status, GitTaskResponseHandler *responseHandler=0, bool freeResponse=false)
 Send POLL to the GIT task.

virtual DcppHandlerRet Exit (StatusType *status, GitTaskResponseHandler *responseHandler=0, bool freeResponse=false)
 Cause a GIT task to exit.

virtual void Report (StatusType *status)
 Dump details using MsgOut.

virtual int IsActive () const
 Returns true if the task is active (on active list).

virtual ~GitTask ()
 Destructor.


Protected Methods

virtual DcppHandlerRet SendSimulate (StatusType *status)
 Obey the SIMULATE_LEVEL action to the task.

virtual DcppHandlerRet GetVersionInfo (StatusType *status)
 Send the parameter get message which fetchs the version details.

virtual DcppHandlerRet GetInitialisedPar (StatusType *status)
 Send the parameter get message which fetchs the INITIALISED parameter.

virtual DcppHandlerRet HandleVerComp (StatusType *status)
 Continue on after fetch version information.

virtual DcppHandlerRet HandleInitParGetComp (bool initialised, StatusType *status)
 Continue on after fetching the INITIALISED parameter value.

virtual DcppHandlerRet SendInitialise (StatusType *status)
 Actually send the initialise.

virtual DcppHandlerRet NoNetOnRemote (StatusType *status)
 Invoked when the get path operation finds that there is no network on the remote node.

virtual void SetInfo (const Arg &info, StatusType *status)
 Set the version information for the sub-tasks.

virtual void SetInitial (StatusType *status)
 Set task to its Initial state.

virtual void SetPathWait (StatusType *status)
 Indicate we are waiting for a path to the task.

virtual void SetInitialising (StatusType *status)
 Indicate we are Initialising the task.

virtual void SetResetting (StatusType *status)
 Indicate we are Restting the task.

virtual void SetIdle (StatusType *status)
 Indicate the task is idle.

virtual void SetExiting (StatusType *status)
 Indicate the task is exiting.

virtual void SetFailed ()
 Indicate an operation has failed.

virtual void SetDied ()
 Indicate the task has died.

virtual DcppHandlerRet RemoteNetStarted (StatusType *status)
 To be invoked when a REMOTE DRAMA network has started.

virtual DcppHandlerRet RemoteNetStartErr (StatusType *status)
 To be invoked when a REMOTE DRAMA network start has failed.

virtual bool RecoveryNeeded ()
 Returns true if recovery is needed.


Static Protected Methods

DcppHandlerRet HandleSimSuccess (DcppVoidPnt ClientData, StatusType *status)
 To be invoked when the SIMULATE_LEVEL action completes ok.

DcppHandlerRet HandleSimError (DcppVoidPnt ClientData, StatusType *status)
 To be invoked when the SIMULATE_LEVEL action fails.

DcppHandlerRet HandleInitSuccess (DcppVoidPnt ClientData, StatusType *status)
 To be invoked when the INITIAISE/RESET action completes ok.

DcppHandlerRet HandleInitError (DcppVoidPnt ClientData, StatusType *status)
 To be invoked when the INITIAISE/RESET action fails.


Protected Attributes

int pollDont
 If > PollRetry, don't poll.

bool pollCancelling
 Polling is being cancelled.

GitResetType resetMode
 Mode of reset.

std::string simulationLevel
 Simulate level.

std::string simulationArg
 Extra simulation level argument.

float timeBase
 Timebase for simulation.

bool havePath
 Set true when we have the path.

bool failed
 Task has failed in some way and should be reset on Initiailse().

bool amExiting
 Set true when the EXIT message is sent.

bool resetting
 Set true if we are resetting.

bool firstTime
 Set true for first init attempt.

std::string verDate
 From ENQ_VER_DATE parameter.

std::string verNum
 From ENQ_VER_NUM parameter.

std::string taskDescr
 From ENQ_DEV_DESCR parameter.


Static Protected Attributes

const int PollRetry = 5
 How many times to try poll.


Member Enumeration Documentation

enum GitTask::SelfPathType
 

Use to ensure the constructor knows it is constructing a self path.

This enum has one value, which is passed to the SelfPath constructor to ensure it


Constructor & Destructor Documentation

GitTask::GitTask const std::string &    name,
const std::string &    node = "",
const std::string &    file = ""
 

Construct a GitTask object.

Allows the the task name, location and file to be set. Details are the same as the DcppTask:: standard constructor.

Parameters:
name  The name the task will be known as (unless loaded, when the name the task registers as will be used)
node  The node name on which the task is running or is to be loaded. Only used if not already running locally or known locally.
file  The file of the task, as required by DitsLoad(). Normally a file name, but may be different depending on the location, e.g. on a VxWorks machine.

GitTask::GitTask SelfPathType    self [inline]
 

Path to self constructor.

Constructor a GitTask object which can be used to send messages to the invoking task itself.

Note:
It is unclear how usefull this constructor is, but it is provided for consistency with the equivalent DcppTask:: constructor.
Parameters:
self  Distingishes this constructor from the other constructor. Value is ignored, just specify GitTask::SelfPath (an enumerated value) .

virtual GitTask::~GitTask   [inline, virtual]
 

Destructor.


Member Function Documentation

virtual DcppHandlerRet GitTask::Exit StatusType *    status,
GitTaskResponseHandler   responseHandler = 0,
bool    freeResponse = false
[virtual]
 

Cause a GIT task to exit.

This method sends the EXIT action to the task

This function returns DcppReschedule if it sent a message. In that case, replies are expected and should be dispatched using DcppDispatch() when they arrive. This will ensure that future processing occurs correctly and the the appropaite handler is invoked when the operation completes.

Note:
This operation may return DcppFinished with status ok. This will occur if as a result of sub-classing no messages are sent.
Note:
If status is set bad on the call (as against during processing of responses, then the response handler is not invoked.
Parameters:
status  Inherited status
responseHandler  If non-null, then this is the address of an object which is notified of the completion of the exit sequence. The GitTaskResponseHandler::CompleteOk method will be invoked on successfull completion of exit whilst GitTaskResponseHandler::CompleteWithError will be invoked if exit operation fails.
freeResponse  If set true, then the response handler is deleted just after the ok or error completion handler is invoked.

virtual DcppHandlerRet GitTask::GetInitialisedPar StatusType *    status [protected, virtual]
 

Send the parameter get message which fetchs the INITIALISED parameter.

This method fetchs the parameter named INITIALISED from the task.

The default version sends a MGET message to the task to fetch the value of the INITIALISED parameter. parameters. It then returns DcppReschedule. On completion, it sets the values appropiately and invokes HandleInitParGetComp() to continue the operation. Inheritors which send the message themselves should also do this.

This call is only invoked the first time an attempt is made to initialise this task, any only if the task was not loaded.

Note:
The default implementation does not consider it an error if the INITIALISED parameter is not available and does not report such a failure (since many older GIT tasks do not support this parameter).
Returns:
DcppReschedule if a message was send, otherwise DcppFinished.
Parameters:
status  Inherited status

virtual DcppHandlerRet GitTask::GetVersionInfo StatusType *    status [protected, virtual]
 

Send the parameter get message which fetchs the version details.

This method fetchs the task version details

The default version sends a MGET message to the task to fetch the value of the ENQ_VER_DATE, ENQ_VER_NUM and ENQ_VER_DESCR parameters. It then returns DcppReschedule. On completion, it sets the values appropiately and invokes HandleVerComp() to continue the operation. Inheritors which send the message themselves should also do this.

Note:
The default implementation does not consider it an error if the version information is not available, through it does report the failure using ErsOut(), before invoking HandleVerComp().
Returns:
DcppReschedule if a message was send, otherwise DcppFinished.
Parameters:
status  Inherited status

DcppHandlerRet GitTask::HandleInitError DcppVoidPnt    ClientData,
StatusType *    status
[static, protected]
 

To be invoked when the INITIAISE/RESET action fails.

This function is a DcppTask callback which is invoked when the INITIALISE/RESET action completes with an error.

Note:
Inheritors which wish to override this function should invoke the GitTask version from the overriding function to ensure the object state is set correctly and the error call back invoked.
Parameters:
ClientData  Points to the GitTask object.
status  Inherited status.

virtual DcppHandlerRet GitTask::HandleInitParGetComp bool    initialised,
StatusType *    status
[protected, virtual]
 

Continue on after fetching the INITIALISED parameter value.

This function is used to continue after the value of the INITIALISED parameter is fetched. It is not normally overriden, but instead invoked by inheriting classes when they have completed the get operation. The returned value is returned to the caller.

Parameters:
initalised  Indicates the task was already initialised.
status  Inherited status

DcppHandlerRet GitTask::HandleInitSuccess DcppVoidPnt    ClientData,
StatusType *    status
[static, protected]
 

To be invoked when the INITIAISE/RESET action completes ok.

This function is a DcppTask callback which is invoked when the INITIALISE/RESET action completes successfully.

Note:
Inheritors which wish to override this function should invoke the GitTask version from the overriding function to ensure the object state is set correctly and the completion callback is invoked.
Parameters:
ClientData  Points to the GitTask object.
status  Inherited status.

DcppHandlerRet GitTask::HandleSimError DcppVoidPnt    ClientData,
StatusType *    status
[static, protected]
 

To be invoked when the SIMULATE_LEVEL action fails.

This function is a DcppTask callback which is invoked when the SIMULATE_LEVEL action completes with an error.

Note:
Inheritors which wish to override this function should invoke the GitTask version from the overriding function to ensure the state is set correctly.
Parameters:
ClientData  Points to the GitTask object.
status  Inherited status.

DcppHandlerRet GitTask::HandleSimSuccess DcppVoidPnt    ClientData,
StatusType *    status
[static, protected]
 

To be invoked when the SIMULATE_LEVEL action completes ok.

This function is a DcppTask callback which is invoked when the SIMULATE_LEVEL action completes successfully.

Note:
Inheritors which wish to override this function should invoke the GitTask version from the overriding function to send the INITIALISE action.
Parameters:
ClientData  Points to the GitTask object.
status  Inherited status.

virtual DcppHandlerRet GitTask::HandleVerComp StatusType *    status [protected, virtual]
 

Continue on after fetch version information.

This function is used to continue after the version details message is invoked. It is not normally overriden, but instead invoked by inheriting classes when they have completed the version get operation. The returned value is returned to the caller.

Parameters:
status  Inherited status

virtual DcppHandlerRet GitTask::Initialise StatusType *    status,
GitTaskResponseHandler   responseHandler = 0,
bool    freeResponse = false
[virtual]
 

Perform the complete initialisation sequence for a GIT task.

Initiate the sequence of operations required to Initialise/Reset a DRAMA task obeying the GIT spec. The sequence is as follows

  • DRAMA networking may be started if supported by a sub-class
  • The task is loaded if it is already running.
  • The path to the task is obtained.
  • The simulation level is set.
  • The task version numbers etc. are fetched.
  • The INITIALISE or RESET action is sent to the task.
This function returns DcppReschedule if it sent a message. In that case, replies are expected and should be dispatched using DcppDispatch() when they arrive. This will ensure that future processing occurs correctly and the the appropaite handler is invoked when the operation completes.

Note:
This operation may return DcppFinished with status ok. This will occur if as a result of sub-classing or as a result of the reset mode being Recover, no messages are sent.
Note:
If status is set bad on the call (as against during processing of responses, then the response handler is not invoked.
Parameters:
status  Inherited status
responseHandler  If non-null, then this is the address of an object which is notified of the completion of the initialisation sequence. The GitTaskResponseHandler::CompleteOk method will be invoked on successfull completion of initialisation whilst GitTaskResponseHandler::CompleteWithError will be invoked if initialisation fails.
freeResponse  If set true, then the response handler is deleted just after the ok or error completion handler is invoked.

virtual int GitTask::IsActive   const [inline, virtual]
 

Returns true if the task is active (on active list).

virtual DcppHandlerRet GitTask::NoNetOnRemote StatusType *    status [inline, protected, virtual]
 

Invoked when the get path operation finds that there is no network on the remote node.

Invoked if during a get path operation, it is discovered the DRAMA networking is not running on the remote node. By default, this does nothing and the get path operation will fail. But if an inheritor has some way of starting the remote DRAMA networking (say using the DRAMA Unix Start Server) then it should initiate that operation at this point and return DcppReschedule. It should then invoke either GitTask::RemoteNetStarted or GitTask::RemoteNetStartErr when it had ether started the networking or it has failed.

Parameters:
status  Inherited status

virtual DcppHandlerRet GitTask::Poll StatusType *    status,
GitTaskResponseHandler   responseHandler = 0,
bool    freeResponse = false
[virtual]
 

Send POLL to the GIT task.

The POLL action is sent to the task.

This function returns DcppReschedule if it sent a message. In that case, replies are expected and should be dispatched using DcppDispatch() when they arrive. This will ensure that future processing occurs correctly and the the appropaite handler is invoked when the operation completes.

Note:
This operation may return DcppFinished with status ok. This will occur if as a result of sub-classing no messages are sent.
Note:
If status is set bad on the call (as against during processing of responses, then the response handler is not invoked.
Parameters:
status  Inherited status
responseHandler  If non-null, then this is the address of an object which is notified of the completion of the poll action. The GitTaskResponseHandler::CompleteOk method will be invoked on successfull completion of polling whilst GitTaskResponseHandler::CompleteWithError will be invoked if polling fails. GitTaskResponseHandler::Triggered will be invoked each time a trigger message is received.
freeResponse  If set true, then the response handler is deleted just after the ok or error completion handler is invoked.

virtual bool GitTask::RecoveryNeeded   [protected, virtual]
 

Returns true if recovery is needed.

This function is invoked if GitTask is resetting the task and the reset mode is recover. In this case, this function should return true if a reset operation should be sent (argument to the RESET will be (RECOVER). Otherwise it should return false, and no RESET command will be sent to the task.

The default version of this function returns false all the time, such that we do not RESET tasks which we are already talking to, if the reset mode is RECOVER. An inheritor should consider the current state of the task.

virtual DcppHandlerRet GitTask::RemoteNetStarted StatusType *    status [protected, virtual]
 

To be invoked when a REMOTE DRAMA network has started.

If an inheritor is trying to start a REMOTE DRAMA network, after overriding GitTask::NoNetOnRemote it must invoke this method to tell GitTask that the remote DRAMA network has been started and GitTask can now try again to load the task

Parameters:
status  Inherited status.

virtual DcppHandlerRet GitTask::RemoteNetStartErr StatusType *    status [protected, virtual]
 

To be invoked when a REMOTE DRAMA network start has failed.

If an inheritor is trying to start a REMOTE DRAMA network after overriding GitTask::NoNetOnRemote, and that operation has failed, it must invoke this method to tell GitTask of the failure. The failure status should be available in DitsGetEntStatus()

Parameters:
status  Inherited status.

virtual void GitTask::Report StatusType *    status [virtual]
 

Dump details using MsgOut.

This call causes details of this object to be output using MsgOut(). (This adds the GIT task version details to the details normally output by the DcppTask::Report - hiding that function.)

virtual DcppHandlerRet GitTask::SendInitialise StatusType *    status [protected, virtual]
 

Actually send the initialise.

Actually sends the INITIALISE/RESET action to the task.

If the task is being reset, then the default vesion sends the RESET action with an appropiate argument. Otherwise, it sends the INITIALISE action. A task is RESET if it was already running (it did not have to be loaded). If a inheritor sends the message itself, then it should invoke GitTask::HandleInitSuccess / GitTask::HandleInitError when the operation completes, with the object address as the client data item. This will ensure the chain continues. If an inheritor is not sending a message it can just return DcppFinished.

Parameters:
status  Inherited status

virtual DcppHandlerRet GitTask::SendSimulate StatusType *    status [protected, virtual]
 

Obey the SIMULATE_LEVEL action to the task.

This method sends the SIMULATE_LEVEL action to the task.

The default version fetches the simulation string and timebase and sends these as parameters of a SIMULATE_LEVEL action. If a inheritor sends the message itself, then it should invoke GitTask::HandlerSimSuccess / GitTask::HandleSimError when the operation completes, with the object address as the client data item. This will ensure the chain continues. If an inheritor is not sending a message it can just return DcppFinished immediately.

Parameters:
status  Inherited status

virtual void GitTask::SetDied   [inline, protected, virtual]
 

Indicate the task has died.

virtual void GitTask::SetExiting StatusType *    status [inline, protected, virtual]
 

Indicate the task is exiting.

Invoked when an exit has been invoked.

Parameters:
status  Inherited status

virtual void GitTask::SetFailed   [inline, protected, virtual]
 

Indicate an operation has failed.

virtual void GitTask::SetIdle StatusType *    status [inline, protected, virtual]
 

Indicate the task is idle.

Invoke when Initialise/Reset has completed.

Parameters:
status  Inherited status

virtual void GitTask::SetInfo const Arg   info,
StatusType *    status
[protected, virtual]
 

Set the version information for the sub-tasks.

Invoked when the task details from the ENQ_VER_NUM, ENQ_VER_DATE and ENQ_TASK_DESCR parameters has been fetch. The argument contains the relevant values, which are by default put into the verNum, verData and taskDescr variables.

Parameters:
info  An Arg (SDS) structure containing all the details.
status  Inherited status

virtual void GitTask::SetInitial StatusType *    status [inline, protected, virtual]
 

Set task to its Initial state.

Invoked when GitTask does not know if has the a valid path to the task or if a GetPath operation has failed.

Parameters:
status  Inherited status

virtual void GitTask::SetInitialising StatusType *    status [inline, protected, virtual]
 

Indicate we are Initialising the task.

Invoked when we start initialising a loaded task.

Parameters:
status  Inherited status

virtual void GitTask::SetPathWait StatusType *    status [inline, protected, virtual]
 

Indicate we are waiting for a path to the task.

Invoked while we are waiting for the path to the task.

Parameters:
status  Inherited status

virtual void GitTask::SetResetMode GitResetType   mode,
StatusType *    status
[inline, virtual]
 

Set the reset mode.

This Should be done prior to calling GitTask::Initialise

Parameters:
mode  The required reset mode.
status  Inherited status

virtual void GitTask::SetResetting StatusType *    status [inline, protected, virtual]
 

Indicate we are Restting the task.

Invoked when we start the reset procedure.

Parameters:
status  Inherited status

virtual void GitTask::SetSimulation const std::string &    value,
const float    TimeBase,
const std::string &    string,
StatusType *    status
[virtual]
 

Set simulation and timebase.

Set the simulation level and timebase values to be used when the SIMULATE_LEVEL action is sent to the task.

Parameters:
value  The simulation level, as accpeted by the target task, and normally as appropiate for the GIT spec, Normally one of NONE or FULL.
TimeBase  The simulation time base. The meaning of this depends on the target target but it often means that any simulation runs this times faster then normal. Many GIT tasks ignore this value.
string  An extra string which is stored in the simulationArg protected variable. It may or may not be used as an extra argument to the simulation level action, depending on how a sub-class is implemented. The default implementation does not use this value.
status  Inherited status.


Member Data Documentation

bool GitTask::amExiting [protected]
 

Set true when the EXIT message is sent.

bool GitTask::failed [protected]
 

Task has failed in some way and should be reset on Initiailse().

bool GitTask::firstTime [protected]
 

Set true for first init attempt.

bool GitTask::havePath [protected]
 

Set true when we have the path.

bool GitTask::pollCancelling [protected]
 

Polling is being cancelled.

int GitTask::pollDont [protected]
 

If > PollRetry, don't poll.

const int GitTask::PollRetry = 5 [static, protected]
 

How many times to try poll.

GitResetType GitTask::resetMode [protected]
 

Mode of reset.

bool GitTask::resetting [protected]
 

Set true if we are resetting.

std::string GitTask::simulationArg [protected]
 

Extra simulation level argument.

std::string GitTask::simulationLevel [protected]
 

Simulate level.

std::string GitTask::taskDescr [protected]
 

From ENQ_DEV_DESCR parameter.

float GitTask::timeBase [protected]
 

Timebase for simulation.

std::string GitTask::verDate [protected]
 

From ENQ_VER_DATE parameter.

std::string GitTask::verNum [protected]
 

From ENQ_VER_NUM parameter.


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