AAO DRAMA/DRAMA2 C++ Interface
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
drama::git::Path Class Reference

Detailed Description

A path object for communicating with DRAMA GIT tasks.

This class is a sub-class of drama::Path, which is used to communicate with tasks that obey the DRAMA GIT Specification. Methods are provided to Initalise GIT tasks (including loading and reset of * tasks), Poll tasks and to shut them down.

A set of GIT tasks can be easily run via these objects, with much of the detail hidden.

Additionally, tasks which are not really GIT tasks can be controlled by a sub-class overriding various implementation methods (e.g. DoGeth(), SendSimLevel(), SendInitialise(), GetVerInfo(), SendReset() and SendExit()). This should allow a control task to run a set of tasks in a consistent manner

Sub-classes can then implement additional methods for the particular type of task being controlled.

See also
Example gitpathtest.cpp
Author
Tony Farrell, AAO
Revision
1.45
Date
22-Feb-2016 14:09:57+11
Id
ACMM:Drama2/drama/gitpath.hh,v 1.45 22-Feb-2016 14:09:57+11 tjf
Examples:
gitpathtest.cpp.

#include "gitpath.hh"

Inheritance diagram for drama::git::Path:
drama::Path

Public Member Functions

 Path (std::weak_ptr< drama::Task > theTask, const std::string &name, const std::string &host="", const std::string &file="")
 Construct a drama::git::Path object. More...
 
virtual ~Path ()
 Destructor. More...
 
virtual void Exit (thread::TMessHandler *action)
 Cause a GIT task to exit. More...
 
virtual void Initialise (thread::TMessHandler *action)
 Perform the complete initialisation sequence for a GIT task. More...
 
virtual void Poll (thread::TMessHandler *action)
 Send POLL to the GIT task. More...
 
virtual void PollCancel (thread::TMessHandler *action)
 Cancel POLLing in the GIT task. More...
 
virtual void Report (thread::TMessHandler *action)
 Dump details using MsgOut. More...
 
virtual void SetFailed ()
 Set the task to failed state. More...
 
void SetPollMaxAttempts (unsigned int n)
 Set the maximum number of poll restarts. More...
 
void SetResetMode (ResetType &mode)
 Set the reset mode. More...
 
virtual void SetSimulation (const std::string &value, const float TimeBase=1.0, const std::string &string="")
 Set simulation and timebase. More...
 
- Public Member Functions inherited from drama::Path
 Path (Path &&source)=default
 Move copy constructor. More...
 
 Path (std::weak_ptr< Task > theTask, const std::string &name, const std::string &host="", const std::string &file="")
 Normal constructor. More...
 
 Path (std::weak_ptr< Task > theTask)
 Path to self constructor. More...
 
 Path (std::weak_ptr< Task > theTask, DitsPathType path)
 Construct from existing DITS path. More...
 
 Path ()
 Construct a null object. More...
 
virtual bool Active () const
 Indicate if a task is active. More...
 
virtual bool Busy () const
 Returns true if we can't send a message because path is busy. More...
 
virtual void ClearState ()
 Clear the task state. More...
 
void Control (thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a control message to a task and blocks the current thread until the reply is received. More...
 
bool ControlWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a control message to a task and block the current thread until the reply is received or a timeout has occurred. More...
 
virtual void Delete (int force)
 Delete the task. More...
 
virtual void Died ()
 Note that a task has died. More...
 
const std::string & GetArgument () const
 Fetch the load argument. More...
 
virtual DitsPathType GetDitsPath (bool nothrow=false)
 Return the underlying DITS path object. More...
 
const std::string & GetHost () const
 Fetch the task host name. More...
 
void GetParam (thread::TMessHandler *action, const std::string &name, sds::IdPtr *const argOut, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a get parameter message to a task and blocks the current thread until it completes. More...
 
void GetParam (thread::TMessHandler *action, const std::initializer_list< std::string > names, sds::IdPtr *const argOut, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a get parameter message to a task and blocks the current thread until it completes. More...
 
bool GetParamWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, sds::IdPtr *const argOut, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a get parameter message to a task and blocks the current thread until it completes. More...
 
bool GetParamWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::initializer_list< std::string > names, sds::IdPtr *const argOut, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a get parameter message to a task and blocks the current thread until it completes. More...
 
void GetPath (thread::TMessHandler *action, thread::TransEvtProcessor *const eventProcessor=&_getPathEventProcessor)
 Get a path to a the task. More...
 
virtual void GetPathImmed ()
 Get a path to a task if DITS already has it. More...
 
bool GetPathLoaded () const
 Indicate if a the task was loaded. More...
 
bool GetPathWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, thread::TransEvtProcessor *const eventProcessor=&_getPathEventProcessor)
 Get a path to a the task. More...
 
virtual std::shared_ptr< TaskGetTask () const
 Get a reference to the DRAMA task we are part of. More...
 
const std::string GetTaskName () const
 Fetch the task name. More...
 
virtual bool Initial () const
 Return true if a GetPath operation is required. More...
 
virtual bool IsDead () const
 Return true if a previously active task has disconnected. More...
 
void Kick (thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message to a task and blocks the current thread until the reply is received. More...
 
void KickBulk (thread::TMessHandler *action, const std::string &name, BulkData *argIn, bool isSds, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message, with bulk data argument, to a task and blocks the current thread until the reply is received. More...
 
void KickBulk (thread::TMessHandler *action, const std::string &name, BulkDataSds *argIn, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message, with SDS bulk data argument, to a task and blocks the current thread until the reply is received. More...
 
bool KickBulkWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, BulkData *argIn, bool isSds, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message to a task and block the current thread until the reply is received or a timeout has occurred. More...
 
bool KickBulkWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, BulkDataSds *argIn, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message to a task and block the current thread until the reply is received or a timeout has occurred. More...
 
bool KickWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a kick message to a task and block the current thread until the reply is received or a timeout has occurred. More...
 
virtual void LogLoad (const bool Flag=true)
 Load use MsgOut() a lines indicating the load operations. More...
 
virtual void LosePath ()
 Lose the path and then set as if the task has died. More...
 
void MonitorCancel (thread::TMessHandler *action, int monId, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Send a Monitor Forward message to a task and block until it is complete. More...
 
void MonitorForward (thread::TMessHandler *action, const sds::Id &argIn, MessageEventHandler *const eventProcessor)
 Send a Monitor Forward message to a task and block until it is complete. More...
 
void MonitorStart (thread::TMessHandler *action, const sds::Id &argIn, MessageEventHandler *const eventProcessor)
 Send a Monitor Start message to a task and block until is it is complete. More...
 
void Obey (thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task and blocks the current thread until the action is complete. More...
 
void ObeyBulk (thread::TMessHandler *action, const std::string &name, BulkData *argIn, bool isSds, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task, with bulk data argument, and blocks the current thread until the action is complete. More...
 
void ObeyBulk (thread::TMessHandler *action, const std::string &name, BulkDataSds *argIn, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task, with SDS bulk data argument, and blocks the current thread until the action is complete. More...
 
bool ObeyBulkWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, BulkData *argIn, bool isSds, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task, with a bulk data argument, and blocks the current thread until the action is complete or a timeout has occurred. More...
 
bool ObeyBulkWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, BulkDataSds *argIn, unsigned notifyBytes=1024 *1024, sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task, with a SDS bulk data argument, and blocks the current thread until the action is complete or a timeout has occurred. More...
 
bool ObeyWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, const sds::Id &argIn=sds::Id::CreateNullItem(), sds::IdPtr *const argOut=nullptr, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends an obey message to a task and blocks the current thread until the action is complete or a timeout has occurred. More...
 
Pathoperator= (Path &&rhs)=default
 Move assignment operator. More...
 
void Report (thread::TMessHandler *action) const
 Dump details using MsgOut(). More...
 
virtual void SetArgument (const std::string &LoadArg, bool const Append=false)
 Set the load time argument string. More...
 
virtual void SetBuffers (const Buffers &buffs)
 Set the DRAMA path buffers. More...
 
virtual void SetFile (const std::string &File)
 Set the executable file name. More...
 
virtual void SetFlowControl ()
 Set the FLOW control flag. More...
 
virtual void SetHost (const std::string &Host)
 Set the task host name. More...
 
virtual void SetName (const std::string &TaskName)
 Set the task name. More...
 
virtual void SetNames (const bool Flag=true)
 Insist that symbols known to IMP_Master be known to the task. More...
 
void SetParam (thread::TMessHandler *action, const std::string &name, const sds::Id &argIn, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a set parameter message to a task and blocks the current thread until it completes. More...
 
bool SetParamWaitUntil (std::chrono::steady_clock::time_point until, thread::TMessHandler *action, const std::string &name, const sds::Id &argIn, MessageEventHandler *const eventProcessor=&_simpleEventProcessor)
 Sends a set parameter message to a task and blocks the current thread until it completes or a timeout has occurred. More...
 
virtual void SetPriority (const int Priority, const bool Absolute=false)
 Set the load time priority for a task when loaded. More...
 
virtual void SetProcess (const std::string &ProcessName)
 Set the process names. More...
 
virtual void SetProg (const bool Flag=true)
 Interpert file name as a program name. More...
 
virtual void SetStackSize (unsigned bytes)
 Set the stack size for the load. More...
 
virtual void SetSymbols (const bool Flag=true)
 Interpert file name as a symbol (VMS Target only) More...
 

Protected Member Functions

virtual void DoGetPath (thread::TMessHandler *action)
 Get the path to the task, loading if needed. More...
 
virtual void GetVerInfo (thread::TMessHandler *action)
 Get the tasks version information. More...
 
virtual void SendExit (thread::TMessHandler *action)
 Send the EXIT action to the task. More...
 
virtual void SendInitialise (thread::TMessHandler *action)
 Send the INTIIALISE action to the task. More...
 
virtual void SendReset (thread::TMessHandler *action, ResetType &mode)
 Send the RESET action to the task. More...
 
virtual void SendSimLevel (thread::TMessHandler *action, const std::string &simLevel, float timeBase, const std::string &simArg)
 Send the SIMULATE_LEVEL action to the task. More...
 
- Protected Member Functions inherited from drama::Path
virtual void Disconnected ()
 Invoked when the task we are talking to disappears. More...
 

Protected Attributes

bool _amExiting =false
 Set true when the EXIT message is sent. More...
 
std::string _devType
 From ENQ_DEV_TYPE parameter. More...
 
bool _failed =false
 Task has failed in some way and should be reset on Initiailse() More...
 
bool _firstTime =true
 Set true for first init attempt. More...
 
bool _havePath =false
 Set true when we have the path. More...
 
bool _initialised =false
 If task is found running, will have the value of the INITIALISED parameter. More...
 
bool _pollCanceling =false
 Polling is being canceled. More...
 
bool _pollDont =false
 If true, don't poll. More...
 
unsigned _pollMaxAttempts =5
 Maximum attempts at polling. More...
 
ResetType _resetMode =ResetEnum::Full
 The mode for the next reset. More...
 
bool _resetting =false
 Set true if we are resetting. More...
 
std::string _simArg
 Extra simulation level argument. More...
 
std::string _simLevel ="NONE"
 Simulate level. More...
 
float _simTimeBase =1
 Timebase for simulation. More...
 
std::string _taskDescr
 From ENQ_DEV_DESCR parameter. More...
 
std::string _verDate
 From ENQ_VER_DATE parameter. More...
 
std::string _verNum
 From ENQ_VER_NUM parameter. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from drama::Path
static std::chrono::steady_clock::time_point DeltaToTimePoint (int secs)
 Given a number of seconds, return a time point that number of seconds into the future. More...
 
static void HandleDisconnected (const char *task, DitsPathType path, StatusType *status)
 Handle task disconnection. More...
 

Constructor & Destructor Documentation

drama::git::Path::Path ( std::weak_ptr< drama::Task theTask,
const std::string &  name,
const std::string &  host = "",
const std::string &  file = "" 
)

Construct a drama::git::Path object.

Allows the the task name, host and file to be set

Parameters
theTaskThe DRAMA Task we are part of. This is passed by pointer, but Path is not taking ownership of the subject object, which must continue to exist until the Path object is destroyed.
nameThe name the task will be known as (unless loaded, when the name the task registers as will be used)
hostThe node name on which the task is running or is to be loaded. Only used if not already running locally or known locally.
fileThe 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.
virtual drama::git::Path::~Path ( )
inlinevirtual

Destructor.

Reimplemented from drama::Path.

Member Function Documentation

virtual void drama::git::Path::DoGetPath ( thread::TMessHandler action)
protectedvirtual

Get the path to the task, loading if needed.

This method does the getting of the path. The standard behavior is a standard drama::Path::GetPath operation, which is all that is needed in most cases, but A sub-class might want to override this.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::Exit ( thread::TMessHandler action)
virtual

Cause a GIT task to exit.

This method sends the EXIT action to the task. The SendExit() method is used to send the message.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::GetVerInfo ( thread::TMessHandler action)
protectedvirtual

Get the tasks version information.

This method fetches the values of the ENQ_VER_DATE, ENQ_VER_NUM, ENQ_DEV_DESCR, ENQ_DEV_TYPE and INITALISED parameters, setting the items _verDate, _verNum, _taskDescr, _devType and _initialised.

Note that if INITIALISED is false, then even if the task was not loaded, it will be sent the INITIALISE. If INITIALISED is true and the task was not loaded, then it is sent RESET rather then INITIALISE.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::Initialise ( thread::TMessHandler action)
virtual

Perform the complete initialisation sequence for a GIT task.

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

The method will block until INITIALISE is complete (standard DRAMA 2 approach).

INITIALISE is sent if the task was loaded, of it not loaded but its INITIALISED parameter value is zero, otherwise, the task will be RESET unless the reset mode is RECOVER and the task has not previously been set to failed.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::Poll ( thread::TMessHandler action)
virtual

Send POLL to the GIT task.

The POLL action is sent to the task. This method blocks until it completes (normal DRAMA 2 approach).

If POLL fails, it will be restarted, up to the number of attempts set by SetPollMaxAttempts(), except that if it is clear the task has died or we are canceling polling, then it will not be restarted.

If the POLL action is rejected due to already being active, then the running POLL action will be canceled and restarted by this task. This feature allows our task to take over polling that was started somewhere else.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::PollCancel ( thread::TMessHandler action)
virtual

Cancel POLLing in the GIT task.

The POLL action is canceled.

The method will block until kicking of the POLL is complete (standard DRAMA 2 approach). The order in which Poll() and PollCancel() complete is undefined.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::Report ( thread::TMessHandler action)
virtual

Dump details using MsgOut.

This call causes details of this object to be output using MsgOut().

virtual void drama::git::Path::SendExit ( thread::TMessHandler action)
protectedvirtual

Send the EXIT action to the task.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::SendInitialise ( thread::TMessHandler action)
protectedvirtual

Send the INTIIALISE action to the task.

Parameters
actionA pointer to the threaded action which is executing this operation.
virtual void drama::git::Path::SendReset ( thread::TMessHandler action,
ResetType mode 
)
protectedvirtual

Send the RESET action to the task.

Parameters
actionA pointer to the threaded action which is executing this operation.
modeThe reset mode to undertake.
virtual void drama::git::Path::SendSimLevel ( thread::TMessHandler action,
const std::string &  simLevel,
float  timeBase,
const std::string &  simArg 
)
protectedvirtual

Send the SIMULATE_LEVEL action to the task.

Parameters
actionA pointer to the threaded action which is executing this operation.
simLevelThe simulation level to set in the task.
timeBaseThe simulation timebase.
simArgAny argument to simulation. Not used in the standard implementation.
virtual void drama::git::Path::SetFailed ( )
inlinevirtual

Set the task to failed state.

This should be invoked after any event where the appropriate behavior at the next RESET RECOVER operation is to actually reset the task.

void drama::git::Path::SetPollMaxAttempts ( unsigned int  n)
inline

Set the maximum number of poll restarts.

Default value is 5.

void drama::git::Path::SetResetMode ( ResetType mode)
inline

Set the reset mode.

This Should be done prior to calling GitTask::Initialise

Parameters
modeThe required reset mode. Will never be RECOVER, if recover was requested and task had failed, will be set to FULL.
virtual void drama::git::Path::SetSimulation ( const std::string &  value,
const float  TimeBase = 1.0,
const std::string &  string = "" 
)
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.

(The SIMULATE_LEVEL action is sent as part of Initialise()).

Parameters
valueThe simulation level, as accpeted by the target task, and normally as appropiate for the GIT spec.
TimeBaseThe 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.
stringAn 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.

Member Data Documentation

bool drama::git::Path::_amExiting =false
protected

Set true when the EXIT message is sent.

std::string drama::git::Path::_devType
protected

From ENQ_DEV_TYPE parameter.

bool drama::git::Path::_failed =false
protected

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

bool drama::git::Path::_firstTime =true
protected

Set true for first init attempt.

bool drama::git::Path::_havePath =false
protected

Set true when we have the path.

bool drama::git::Path::_initialised =false
protected

If task is found running, will have the value of the INITIALISED parameter.

bool drama::git::Path::_pollCanceling =false
protected

Polling is being canceled.

bool drama::git::Path::_pollDont =false
protected

If true, don't poll.

unsigned drama::git::Path::_pollMaxAttempts =5
protected

Maximum attempts at polling.

ResetType drama::git::Path::_resetMode =ResetEnum::Full
protected

The mode for the next reset.

bool drama::git::Path::_resetting =false
protected

Set true if we are resetting.

std::string drama::git::Path::_simArg
protected

Extra simulation level argument.

std::string drama::git::Path::_simLevel ="NONE"
protected

Simulate level.

float drama::git::Path::_simTimeBase =1
protected

Timebase for simulation.

std::string drama::git::Path::_taskDescr
protected

From ENQ_DEV_DESCR parameter.

std::string drama::git::Path::_verDate
protected

From ENQ_VER_DATE parameter.

std::string drama::git::Path::_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@aao.gov.au 

Generated on Mon Feb 22 2016 15:57:53 for AAO DRAMA/DRAMA2 C++ Interface by doxygen 1.8.10