AAO DRAMA/DRAMA2 C++ Interface
Public Member Functions | List of all members
drama::thread::TAction Class Referenceabstract

Detailed Description

A class which implements a DRAMA Action with runs a thread.

Interface only. Users must sub-class and implement ActionThread(), which is invoked in a new thread created when the action is invoked.

Many of the methods of drama::MessageHandler are re-implemented to work within a thread, such as MessageUser and SendTrigger.

Methods are also available to wait for kick messages to be received. Threaded actions are required if you want to send messages to other DRAMA tasks.

These objects can then be supplied to the drama::Task::Add() methods

Warning
Threaded actions are not a good way of implementing actions which receive large arguments, The action must copy any SDS argument so that the thread can get it at any time. For large arguments this could be very expensive. Better in those cases to implement a normal action. DRAMA Bulk Data arguments are different, the copy is not needed.
Author
Tony Farrell, AAO
Revision
1.45
Date
22-Feb-2016 14:09:57+11
Examples:
gitpathtest.cpp, and threadbasic.cpp.

#include "threadaction.hh"

Inheritance diagram for drama::thread::TAction:
drama::MessageHandler drama::thread::TMessHandler drama::RunDramaExitNotifier

Public Member Functions

 TAction (std::weak_ptr< Task > dramaTask, double timeout=0)
 Create a DRAMA action/message handler object which runs a thread when the Obey message is received. More...
 
 TAction (const TAction &source)=delete
 Copy constructor - deleted. More...
 
virtual ~TAction ()
 TAction destructor. More...
 
void AbortMessageWaits (StatusType status)
 Tells any thread waiting for messages to abort the wait event. More...
 
void ClearExitOnCompletion ()
 Clear exit on completion. More...
 
bool DoWaitForKick (WaitEventDetails *waitEvent, sds::IdPtr *const arg=nullptr)
 Wait for a kick event with the waitEvent details given. More...
 
unsigned GetKickCount () const
 Returns the number of times this action has been kicked since started or the last reset of the count. More...
 
Dits___CurActType GetMessageContext () const override
 Get the DRAMA Context associated with the action event. More...
 
std::shared_ptr< TaskGetTask () const override
 Get a reference to the DRAMA task we are part of. More...
 
double GetTimeout () const
 Return the current action timeout. More...
 
Task::mutexTypeLock () const override
 Reference the DRAMA Task lock. More...
 
void MessageUser (const std::string &text) const override
 Use DRAMA to send a message to the user. More...
 
TActionoperator= (const TAction &rhs)=delete
 Assignment operator - deleted. More...
 
void PutKickHandler (MessageHandlerPtr obj)
 We cannot change the kick handler in a threaded action, it does not make sense. More...
 
void PutObeyHandler (MessageHandlerPtr obj)
 We cannot change the obey handler in a threaded action, it does not make sense. More...
 
void ResetKickCount ()
 Returns a shared pointer to the last kick message argument. More...
 
virtual const sds::PrintObjectCRSdsListToUser () const override
 Get a reference to an SDS printer object which can be used to list an SDS object using MessageUser. More...
 
void SendTrigger (const sds::Id &arg) const
 Send a trigger message to the parent action. More...
 
void SetExitOnCompletion ()
 Set exit on completion. More...
 
void SetReturnArg (const sds::Id &arg, bool copy=true)
 Set the argument to be sent as part of the action completion message. More...
 
void SetReturnArg (sds::Id *arg)
 Set the argument to be sent as part of the action completion message. More...
 
void SetTimeout (double newTimeout)
 Set a new timeout. More...
 
void SetupWaitEvent (DitsTransIdType tid, drama::Path *pathObj) override
 Sets up a wait event for this thread. More...
 
WaitEventDetails * SetupWaitForKick ()
 Set up to wait for a kick message. More...
 
template<class Clock , class Duration >
bool WaitEventTimeoutAt (EntryCode *event, const std::chrono::time_point< Clock, Duration > &abs_time, sds::IdPtr *const arg=0)
 Block the current thread until a signal/kick for the action is received or until a given time. More...
 
void WaitForEvent (EntryCode *event, sds::IdPtr *const arg=nullptr)
 Block the current thread until a kick/signal message for the action is received. More...
 
template<class Rep , class Period >
bool WaitForEventTimeoutIn (EntryCode *event, const std::chrono::duration< Rep, Period > &rel_time, sds::IdPtr *const arg=0)
 Block the current thread until a signal/kick for the action is received or a duration has passed. More...
 
bool WaitForEventTimeoutIn (EntryCode *event, unsigned seconds, sds::IdPtr *const arg=0)
 Block the current thread until a signal/kick for the action is received or a duration in seconds has passed. More...
 
void WaitForKick (sds::IdPtr *const arg=nullptr)
 Block the current thread until a kick for the action is received. More...
 
template<class Rep , class Period >
bool WaitForKickTimeoutIn (const std::chrono::duration< Rep, Period > &rel_time, sds::IdPtr *const arg=0)
 Block the current thread until a kick for the action is received or a duration has passed. More...
 
bool WaitForKickTimeoutIn (unsigned seconds, sds::IdPtr *const arg=0)
 Block the current thread until a kick for the action is received or a duration in seconds has passed. More...
 
template<class Clock , class Duration >
bool WaitKickForTimeoutAt (const std::chrono::time_point< Clock, Duration > &abs_time, sds::IdPtr *const arg=0)
 Block the current thread until a kick for the action is received or until a given time. More...
 
- Public Member Functions inherited from drama::MessageHandler
 MessageHandler ()
 Create a DRAMA action/message handler object. More...
 
 MessageHandler (const MessageHandler &source)=delete
 Assignment operator deleted. More...
 
 MessageHandler (MessageHandler &&source)=default
 Move assignment operator. More...
 
virtual ~MessageHandler ()
 MessageHandler destructor. More...
 
virtual const EntryInfoGetEntry ()
 Return the action entry details. More...
 
MessageHandleroperator= (const MessageHandler &rhs)=delete
 Copy operator deleted. More...
 
MessageHandleroperator= (MessageHandler &&rhs)=default
 Move operator. More...
 
virtual void PutKickHandler (MessageReceiveFunction func)
 Put a message handler function for the next Kick event. More...
 
virtual void PutObeyHandler (MessageReceiveFunction func)
 Put a message handler function for the next Obey reschedule event. More...
 
void SendBulkTrigger (BulkData *arg, DitsTransIdType *transId, bool isSds, unsigned notifyBytes=1024 *1024)
 Send a bulk data trigger message to the parent action. More...
 
void SendBulkTrigger (BulkDataSds *arg, DitsTransIdType *transId, unsigned notifyBytes=1024 *1024)
 Send a bulk data trigger message to the parent action. More...
 
void SendTrigger (const sds::Id &arg) const
 Send a trigger message to the parent action. More...
 
void SetReturnArg (const sds::Id &arg, bool copy=true)
 Set the argument to be sent as part of the action completion message. More...
 
void SetReturnArg (sds::Id *arg)
 Set the argument to be sent as part of the action completion message. More...
 
- Public Member Functions inherited from drama::thread::TMessHandler
 TMessHandler (const TMessHandler &source)=delete
 Copy constructor - deleted. More...
 
virtual ~TMessHandler ()
 Destructor. More...
 
TMessHandleroperator= (const TMessHandler &rhs)=delete
 Assignment operator - deleted. More...
 
virtual void WaitForTransaction (std::weak_ptr< Task > theTask, TransEvtInfo *const eventInfo, TransEvtProcessor *const eventProcessor, sds::IdPtr *const arg=nullptr)
 Block the current thread until a message for the transaction specified to SetupWaitEvent() occurs. More...
 
virtual bool WaitForTransactionUntil (std::weak_ptr< Task > theTask, TransEvtInfo *const eventInfo, TransEvtProcessor *const eventProcessor, std::chrono::steady_clock::time_point until, sds::IdPtr *const arg=nullptr)
 Block the current thread until a message for the transaction specified to SetupWaitEvent() occurs or until a certain time has passed. More...
 

Additional Inherited Members

- Protected Member Functions inherited from drama::MessageHandler
virtual void ActionEnd (bool taskExiting, StatusType actionEndStatus)
 Method Invoked when the action completes. More...
 
void GrabEntryInfo ()
 Fetch the DRAMA Entry information. More...
 

Constructor & Destructor Documentation

drama::thread::TAction::TAction ( std::weak_ptr< Task dramaTask,
double  timeout = 0 
)
inline

Create a DRAMA action/message handler object which runs a thread when the Obey message is received.

Parameters
dramaTaskThe DRAMA Task we are part of. This is passed by pointer, but TAction is not taking ownership of the subject object, which must continue to exist until the TAction object is destroyed.
dramaTaskA pointer to the DRAMA task we are part of.
timeoutThe default timeout on the thread. If the thread does not complete in this time the action will complete anyway. (BUT WHAT HAPPENS TO THE THREAD?) Only values greater then zero are valid. If you specify an invalid value (<=0) then no timeout is implemented.
virtual drama::thread::TAction::~TAction ( )
virtual

TAction destructor.

This is normally invoked as part of the Task being shutdown.

drama::thread::TAction::TAction ( const TAction source)
delete

Copy constructor - deleted.

Member Function Documentation

void drama::thread::TAction::AbortMessageWaits ( StatusType  status)

Tells any thread waiting for messages to abort the wait event.

Parameters
statusA DRAMA Error status to associate with the abort.
void drama::thread::TAction::ClearExitOnCompletion ( )
inline

Clear exit on completion.

If invoked, then task will not exit when this action completes.

bool drama::thread::TAction::DoWaitForKick ( WaitEventDetails *  waitEvent,
sds::IdPtr *const  arg = nullptr 
)
inline

Wait for a kick event with the waitEvent details given.

Currently this is only used by the KickNotifier. It may end up with wider use.

Parameters
waitEventitem address returned by SetupWaitForKick.
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.
Returns
false if woken up by SignalWaitingEvent with a code of EntryCode::DramaAbortWaits, true otherwise (normally a kick).

References D2LOG_DRAMA2.

unsigned drama::thread::TAction::GetKickCount ( ) const
inline

Returns the number of times this action has been kicked since started or the last reset of the count.

Dits___CurActType drama::thread::TAction::GetMessageContext ( ) const
overridevirtual

Get the DRAMA Context associated with the action event.

Implements virtual baseclass TMessHander method.

Implements drama::thread::TMessHandler.

std::shared_ptr<Task> drama::thread::TAction::GetTask ( ) const
inlineoverridevirtual

Get a reference to the DRAMA task we are part of.

Reimplemented from drama::MessageHandler.

Referenced by drama::thread::KickNotifier::WasKicked().

double drama::thread::TAction::GetTimeout ( ) const
inline

Return the current action timeout.

Task::mutexType& drama::thread::TAction::Lock ( ) const
overridevirtual

Reference the DRAMA Task lock.

Implements virtual baseclass TMessHander method.

Implements drama::thread::TMessHandler.

void drama::thread::TAction::MessageUser ( const std::string &  text) const
overridevirtual

Use DRAMA to send a message to the user.

The supplied text is send to the user using

See also
MsgOut(). Normally this appears the user interface.

If the message contains line feed characters (
), then they are used to break the message up.

Reimplemented from drama::MessageHandler.

Examples:
threadbasic.cpp.
TAction& drama::thread::TAction::operator= ( const TAction rhs)
delete

Assignment operator - deleted.

void drama::thread::TAction::PutKickHandler ( MessageHandlerPtr  obj)
virtual

We cannot change the kick handler in a threaded action, it does not make sense.

Instead, this will throw an exception

Reimplemented from drama::MessageHandler.

void drama::thread::TAction::PutObeyHandler ( MessageHandlerPtr  obj)
virtual

We cannot change the obey handler in a threaded action, it does not make sense.

Instead, this will throw an exception

Reimplemented from drama::MessageHandler.

void drama::thread::TAction::ResetKickCount ( )

Returns a shared pointer to the last kick message argument.

Will be a nullptr if there has been no such kickResets the kick count.

virtual const sds::PrintObjectCR& drama::thread::TAction::SdsListToUser ( ) const
inlineoverridevirtual

Get a reference to an SDS printer object which can be used to list an SDS object using MessageUser.

Returns
An object reference that can be passed to drama::sds::Id::List as an printer object.

Reimplemented from drama::MessageHandler.

References drama::thread::TMessHandler::SdsListToUser().

void drama::thread::TAction::SendTrigger ( const sds::Id arg) const

Send a trigger message to the parent action.

Parameters
argThe SDS Id of the argument to the trigger message.
void drama::thread::TAction::SetExitOnCompletion ( )
inline

Set exit on completion.

If invoked, then task will exit when this action completes.

void drama::thread::TAction::SetReturnArg ( const sds::Id arg,
bool  copy = true 
)
inline

Set the argument to be sent as part of the action completion message.

Parameters
argThe SDS ID of the structure to be sent with the completion message.
copyIf true, then the SDS structure is copied. If false, then no copy is made, but the user must ensure underlying SDS ID is NOT deleted until after the action has completed (For example, it is not deleted until the next DRAMA message is processed. This is more efficient for large messages but imposes management overheads on user code.
Examples:
threadbasic.cpp.

References drama::sds::Id::Copy(), and drama::sds::Id::ShallowCopy().

void drama::thread::TAction::SetReturnArg ( sds::Id arg)
inline

Set the argument to be sent as part of the action completion message.

This version of SetReturnArg() is to be used in cases where the user does not want the argument copied, but wants DRAMA to deal with tidying it up. DRAMA will take control of tidying it up.

Parameters
argThe SDS ID of the structure to be sent with the completion message.
void drama::thread::TAction::SetTimeout ( double  newTimeout)
inline

Set a new timeout.

The action timeout indicates when the DRAMA software should timeout. Only takes effect the next time the action is rescheduled.

Parameters
newTimeoutA timeout in seconds.
void drama::thread::TAction::SetupWaitEvent ( DitsTransIdType  tid,
drama::Path pathObj 
)
overridevirtual

Sets up a wait event for this thread.

This call allows a thread to later call WaitForTransaction() to cause the thread to be blocked until the specified transaction completes. This method must be invoked after the transaction is started but before the DRAMA lock is released, otherwise the DRAMA main loop may see any result of the transaction before WaitForTransaction() is invoked and not know how to dispatch it to this thread.

After calling this method, the DRAMA lock would then be released before calling WaitForTransaction().

Parameters
tidThe DITS Transaction we are setting up to wait on. Must have been returned by a DRAMA DITS routine, e.g. DitsPathGet() or DitsObey(). A special case of 0 (nullptr) is used to indicate waiting for kick message, and is an internal only feature.
pathObjThe drama::Path object we using to communicate with the target task. 0 (nullptr) for a kick message.

Implements drama::thread::TMessHandler.

WaitEventDetails* drama::thread::TAction::SetupWaitForKick ( )
inline

Set up to wait for a kick message.

This method allows the user to break waiting for a kick into a setup and wait component, to allow access to the details for the wait, so that the wait can be canceled.

Returns
Details of the wait event.
template<class Clock , class Duration >
bool drama::thread::TAction::WaitEventTimeoutAt ( EntryCode event,
const std::chrono::time_point< Clock, Duration > &  abs_time,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a signal/kick for the action is received or until a given time.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a signal/kick. They will all be woken up when the signal/kick occurs.

tparam Clock A clock class, such as system_clock, steady_clock, high_resolution_clock or a custom clock class. tparam Duration A duration type.

Parameters
eventThe entry reason. EntryCode::Kick or EntryCode::Signal. If a timeout occurs, will by EntryCode::DramaAbortWaits.
abs_timeA point in time at which the thread will stop blocking, allowing the function to return. time_point is an object that represents a specific absolute time.
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.
Returns
Returns true if the kick was received, false for a timeout.

References D2LOG_DRAMA2.

void drama::thread::TAction::WaitForEvent ( EntryCode event,
sds::IdPtr *const  arg = nullptr 
)
inline

Block the current thread until a kick/signal message for the action is received.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a kick/signal. They will all be woken up when the event occurs.

Parameters
eventThe entry reason. EntryCode::Kick or EntryCode::Signal
argThe argument to the kick/signal, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.

References D2LOG_DRAMA2.

template<class Rep , class Period >
bool drama::thread::TAction::WaitForEventTimeoutIn ( EntryCode event,
const std::chrono::duration< Rep, Period > &  rel_time,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a signal/kick for the action is received or a duration has passed.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a signal/kick. They will all be woken up when the signal/kick occurs.

Parameters
eventThe entry reason. EntryCode::Kick or EntryCode::Signal. If a timeout occurs, will by EntryCode::DramaAbortWaits.
Template Parameters
RepAn arithmetic type, or a class emulating an arithmetic type, to be used as the type for the internal count.
PeriodA ratio type that represents the period in seconds.
Parameters
rel_timeThe maximum time span during which the thread will block waiting to be notified. duration is an object that represents a specific relative time. Wait this length of time
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.
Returns
Returns true if the kick was received, false for a timeout.

References D2LOG_DRAMA2.

bool drama::thread::TAction::WaitForEventTimeoutIn ( EntryCode event,
unsigned  seconds,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a signal/kick for the action is received or a duration in seconds has passed.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a signal/kick. They will all be woken up when the signal/kick occurs.

Parameters
eventThe entry reason. EntryCode::Kick or EntryCode::Signal. If a timeout occurs, will by EntryCode::DramaAbortWaits.
secondsThe maximum time span during which the thread will block waiting to be notified. duration is in seconds.
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, this is not written to.
Returns
Returns true if the kick was received, false for a timeout.
void drama::thread::TAction::WaitForKick ( sds::IdPtr *const  arg = nullptr)
inline

Block the current thread until a kick for the action is received.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a kick. They will all be woken up when the kick occurs.

Parameters
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.

References DramaTHROW, and drama::Kick.

template<class Rep , class Period >
bool drama::thread::TAction::WaitForKickTimeoutIn ( const std::chrono::duration< Rep, Period > &  rel_time,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a kick for the action is received or a duration has passed.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a kick. They will all be woken up when the kick occurs.

Template Parameters
RepAn arithmetic type, or a class emulating an arithmetic type, to be used as the type for the internal count.
PeriodA ratio type that represents the period in seconds.
Parameters
rel_timeThe maximum time span during which the thread will block waiting to be notified. duration is an object that represents a specific relative time. Wait this length of time
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.
Returns
Returns true if the kick was received, false for a timeout.
Examples:
threadbasic.cpp.

References DramaTHROW, and drama::Kick.

bool drama::thread::TAction::WaitForKickTimeoutIn ( unsigned  seconds,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a kick for the action is received or a duration in seconds has passed.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a kick. They will all be woken up when the kick occurs.

Parameters
secondsThe maximum time span during which the thread will block waiting to be notified. duration is in seconds.
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, this is not written to.
Returns
Returns true if the kick was received, false for a timeout.
template<class Clock , class Duration >
bool drama::thread::TAction::WaitKickForTimeoutAt ( const std::chrono::time_point< Clock, Duration > &  abs_time,
sds::IdPtr *const  arg = 0 
)
inline

Block the current thread until a kick for the action is received or until a given time.

Note - in an action with multiple subsidiary threads, any number of the threads can block waiting for a kick. They will all be woken up when the kick occurs.

tparam Clock A clock class, such as system_clock, steady_clock, high_resolution_clock or a custom clock class. tparam Duration A duration type.

Parameters
abs_timeA point in time at which the thread will stop blocking, allowing the function to return. time_point is an object that represents a specific absolute time.
argThe argument to the kick, if any. An address of and sds::IdPtr is supplied. If you supply a null pointer, it is ignored. Otherwise, any argument to the kick is copied into here. If there is no argument to the kick, it will refer to a null SDS item.
Returns
Returns true if the kick was received, false for a timeout.

References DramaTHROW, and drama::Kick.


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