---

GitTask Class Reference

#include <gittask.h>

Inheritance diagram for GitTask:

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:

• gittask.h

---