Detailed Description

A class which implements a DRAMA task.

Create one of these objects to turn your program into a DRAMA task. The normal approach is to subclass drama::Task and add actions, parameters and other features within the sub-class.

Use the Task::Add and Task::AddSpawnable methods to add actions to your task. Create drama::Parameter objects to add DRAMA Parameters to your task. Execute Task::RunDrama() to run your DRAMA task (read and dispatch messages).

Warning: Only one of these objects can exist in a program, any only one thread can call Task::RunDrama() at a given time.

See also: drama::CreateRunDramaTask for an easy way of creating and dealing with exceptions etc.; Example dramahello.cpp

Author: Tony Farrell, AAO

Revision: 1.45

Date: 22-Feb-2016 14:09:57+11

Examples:: dramahello.cpp, gitpathtest.cpp, monitor1.cpp, monitor2.cpp, threadbasic.cpp, and tocker.cpp.

#include "task.hh"

Inheritance diagram for drama::Task:

Public Types
typedef std::lock_guard< mutexType >	guardType
	Defines the type of a lock guard using our mutex type. More...

typedef std::recursive_timed_mutex	mutexType
	Defines the type of our mutex. More...

typedef std::unique_lock< mutexType >	uniqueLockType
	Defines the type of a unique_lock type using our mutex type. More...

Public Member Functions
	Task (const std::string &name, int buffer=DefBufSize, int flags=0, int selfBytes=DefSelfBufSize)
	Create a new DRAMA task of the specified name. More...

virtual	~Task ()
	Destructor - shut down the DRAMA task. More...

virtual void	_MessageUser (const std::string &text) const
	Use DRAMA to send a message to the user. More...

virtual void	Add (const std::string &name, MessageHandlerPtr obj)
	Add an action to the task. More...

virtual void	Add (const std::string &name, MessageHandler *obj)
	Add an action to the task. More...

virtual void	Add (const std::string &name, MessageReceiveFunction func)
	Add an action to the task. More...

void	AddOrphanToQueue (const OrphanDetails &orphan)
	Add an orphan to the queue of orphans to be processed before we next look at the DRAMA message queue. More...

virtual void	AddSpawnable (const std::string &name, SpawnablePtr obj)
	Add a spawnable action to the task. More...

virtual void	AddSpawnable (const std::string &name, Spawnable *obj)
	Add an action to the task. More...

void	CancelNotifyOnRunDramaExit (RunDramaExitNotifier *notifier)
	Cancel notification for when the DRAMA RunDrama() exits. More...

virtual double	GetJoinTimeout () const
	Get the thread join timeout. More...

std::thread::id	GetTaskThreadId () const
	Return the thread ID of the thread running RunDrama() More...

mutexType &	Lock ()
	Reference the DRAMA Task lock. More...

logging::Logger &	Logger ()
	Reference to DRAMA 2 Logger. More...

void	NotifyOnRunDramaExit (RunDramaExitNotifier *notifier)
	Arrange notification for when the DRAMA RunDrama() exits. More...

virtual void	RunDrama ()
	Run the DRAMA message loop in the current thread. More...

void	Signal (const std::string &name, sds::Id arg=nullptr, void data=nullptr)
	Trigger the rescheduling of an action, specifing the name of the action. More...

void	Signal (long int index, sds::Id arg=nullptr, void data=nullptr)
	Trigger the rescheduling of an action, specifying the index of the action. More...

std::string	TaskName () const
	Return task name. More...

std::weak_ptr< Task >	TaskPtr ()
	Returns a weak pointer to the task. More...

template<typename T >
std::shared_ptr< T >	TaskPtrAs ()
	Returns a shared pointer to the task, dynamically case to the template type. More...

Static Public Attributes
static const int	DefBufSize =20000
	Default global buffer size. More...

static const int	DefSelfBufSize =2000
	Default self buffer size. More...

Protected Member Functions
virtual void	OrphanHandler (const OrphanDetails &details)
	Orphan transaction handler. More...

Member Typedef Documentation

typedef std::lock_guard<mutexType> drama::Task::guardType

Defines the type of a lock guard using our mutex type.

typedef std::recursive_timed_mutex drama::Task::mutexType

Defines the type of our mutex.

It is recursive, since we might call it as the result of calls that have it locked.

If the macro DRAMA2_LOCK_DEBUG is defined, we use our "LockWithInfo", a slower lock that does give us some details on what is happening with the lock. Expected to only be used whilst debugging locking and all of DRAMA must be compiled with that macro defined.

typedef std::unique_lock<mutexType> drama::Task::uniqueLockType

Defines the type of a unique_lock type using our mutex type.

Constructor & Destructor Documentation

drama::Task::Task	(	const std::string &	name,
		int	buffer = `DefBufSize`,
		int	flags = `0`,
		int	selfBytes = `DefSelfBufSize`
	)

Create a new DRAMA task of the specified name.

See also: DitsAppInit()

Parameters

name	The name for the task.
buffer	The DRAMA Task global message buffer size (bytes). Defaults to DefBufSize (20000) which should be enough for small tasks. See DitsAppInit().
flags	DRAMA Initialization flags. See DitsAppInit() for possible values.
selfBytes	Size for the message buffer used to send messages to self. Only used if the DITS_M_SELF_BYTES flag is set. Default is DefSelBufSize (2000) bytes which enough for normal uses of DitsSignal() and releated functions.

virtual drama::Task::~Task ( )

virtual

Destructor - shut down the DRAMA task.

Other tasks will be notified that this task has shut down.

Reimplemented in drama::git::Task.

Member Function Documentation

virtual void drama::Task::_MessageUser ( const std::string & text ) const

virtual

Use DRAMA to send a message to the user.

This version MessageUser() should not normally be invoked by user code. They should prefer the drama::MessageHandler and drama::Thread methods. The results of this version are not well defined, but it is used to implement the high level versions.

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 (\n), then they are used to break the message up.

virtual void drama::Task::Add	(	const std::string &	name,
		MessageHandlerPtr	obj
	)

inlinevirtual

Add an action to the task.

An action of the specified name is added to the task. The MessageHandler pointed to by obj is used to handle the messages.

Parameters

name	Action name.
obj	MessageHandler object pointer, passed by std::shared_ptr().

Examples:: dramahello.cpp, gitpathtest.cpp, monitor1.cpp, monitor2.cpp, and tocker.cpp.

virtual void drama::Task::Add	(	const std::string &	name,
		MessageHandler *	obj
	)

inlinevirtual

Add an action to the task.

An action of the specified name is added to the task. The MessageHandler pointed to by obj is used to handle the messages.

Parameters

name	Action name.
obj	MessageHandler object.

virtual void drama::Task::Add	(	const std::string &	name,
		MessageReceiveFunction	func
	)

inlinevirtual

Add an action to the task.

An action of the specified name is added to the task. The function specified is invoked to handle messages.

Parameters

name	Action name.
func	A function to be invoked to handle messages. The argument to this function is a drama::MessageHandler object which can be used communicate with DRAMA. The function must return a reschedule request.

void drama::Task::AddOrphanToQueue ( const OrphanDetails & orphan )

inline

Add an orphan to the queue of orphans to be processed before we next look at the DRAMA message queue.

Thread/Lock Entry Info: Probably not running in DRAMA message thread. DRAMA Lock Taken.

Parameters

orphan The details on the orphan.

virtual void drama::Task::AddSpawnable	(	const std::string &	name,
		SpawnablePtr	obj
	)

inlinevirtual

Add a spawnable action to the task.

A spawnable action of the specified name is added to the task. The Spawnable object pointed to by obj is used to handle the messages.

Parameters

name	Action name.
obj	Spawnable object pointer, passed by std::shared_ptr().

virtual void drama::Task::AddSpawnable	(	const std::string &	name,
		Spawnable *	obj
	)

inlinevirtual

Add an action to the task.

A spawnable of the specified name is added to the task. The Spawnable object pointed to by obj is used to handle the messages.

Parameters

name	Action name.
obj	Spawnable object pointer

void drama::Task::CancelNotifyOnRunDramaExit ( RunDramaExitNotifier * notifier )

Cancel notification for when the DRAMA RunDrama() exits.

Parameters

notifier The object to no longer be notified.

virtual double drama::Task::GetJoinTimeout ( ) const

virtual

Get the thread join timeout.

This timeout value is specified when waiting to join outstanding threads when the task is shutting down. See the TUface/TAction implementations of RunDramaExitNotifier::JoinThreads.

Sub-classes can override this to provide a different value.

Returns: The join timeout in seconds. Default is 5 seconds.

std::thread::id drama::Task::GetTaskThreadId ( ) const

inline

Return the thread ID of the thread running RunDrama()

mutexType& drama::Task::Lock ( )

inline

Reference the DRAMA Task lock.

Is is important that you take the DRAMA Task Lock before accessing any DRAMA C routine.

logging::Logger& drama::Task::Logger ( )

inline

Reference to DRAMA 2 Logger.

You can use this reference to make explicit log calls.

Alternatively, you could use DitsLogMsg(), which would make your code independent of the DRAMA 2 system.

void drama::Task::NotifyOnRunDramaExit ( RunDramaExitNotifier * notifier )

Arrange notification for when the DRAMA RunDrama() exits.

Parameters

notifier The object to be notified, its RunDramaHasExited() method will be invoked when the loop exits.

virtual void drama::Task::OrphanHandler ( const OrphanDetails & details )

protectedvirtual

Orphan transaction handler.

This this is invoked to handle orphan transactions.

Orphaned transactions are those transactions which were not complete when their parent action (or UFACE thread) completed. This method will be invoked for each such transaction.

Subclasses can override this method to handle orphans in there preferred way. The base implementation will output a message to stderr.

The context of this call is that the DRAMA lock is taken, you are running in the thread that called RunDrama() and are in, but are not in any action context. At this point, to send messages, you must enable UFACE context in the traditional (C) DRAMA style.

It should also be noted that the transaction that triggered this call may have already been deleted by DRAMA, that is, the transaction ID in the details structure is referring to an invalid transaction ID. It will not have been reallocated as yet. You should only be using this value as a lookup, not as an argument to DRAMA calls.

Parameters

details Details of the orphaned transaction.

virtual void drama::Task::RunDrama ( )

virtual

Run the DRAMA message loop in the current thread.

void drama::Task::Signal	(	const std::string &	name,
		sds::Id *	arg = `nullptr`,
		void *	data = `nullptr`
	)

Trigger the rescheduling of an action, specifing the name of the action.

The method allows an action to trigger the rescheduling of another action in the current task.

This method can be used from an action or when there is no action context (such as in a thread).

The target action may be awaiting rescheduling for any reason (having put a request of RequestCode::Wait, RequestCode::Sleep, or RequestCode::Stage.

Since this routine is often used for communication between interrupt routines and main line code, the message is sent as a high priority message and will thus be put a the begining of the incoming message buffer.

       Note, as this routine is often used to allow non-DRAMA parts of a
       program to communicate with a DRAMA program, applications often get
       into trouble if this fail.  Ensure exceptions are at least reported.

WORKING WITH THREADED ACTIONS ???

       @param name The name of the action to signal
       @param arg   An argument to the action.   The drama::sds::Id::COut()
                    method will be applied with its outlives argument
                    set true.  The underlying SDS id is passed to the
                    action and the underlying SDS structure will be 
                    deleted when the action entry completes.  Pass nullptr
                    if there is no argument.
       @param data  A pointer which will be assoicated with
                    the signal.  The action can fetch this using

DitsGetSigArg(3), but only if not null.

void drama::Task::Signal	(	long int	index,
		sds::Id *	arg = `nullptr`,
		void *	data = `nullptr`
	)

Trigger the rescheduling of an action, specifying the index of the action.

The method allows an action to trigger the rescheduling of another action in the current task.

This method can be used from an action or when there is no action context (such as in a thread).

The target action may be awaiting rescheduling for any reason (having put a request of RequestCode::Wait, RequestCode::Sleep, or RequestCode::Stage.

Since this routine is often used for communication between interrupt routines and main line code, the message is sent as a high priority message and will thus be put a the begining of the incoming message buffer.

       Note, as this routine is often used to allow non-DRAMA parts of a
       program to communicate with a DRAMA program, applications often get
       into trouble if this fail.  Ensure exceptions are at least reported.

WORKING WITH THREADED ACTIONS ???

       @param index The action index. (WHO TO GET THIS?)
       @param arg   An argument to the action.   The drama::sds::Id::COut()
                    method will be applied with its outlives argument
                    set true.  The underlying SDS id is passed to the
                    action and the underlying SDS structure will be 
                    deleted when the action entry completes.  Pass nullptr
                    if there is no argument.
       @param data  A pointer which will be assoicated with
                    the signal.  The action can fetch this using

DitsGetSigArg(3), but only if not null.

std::string drama::Task::TaskName ( ) const

inline

Return task name.

std::weak_ptr<Task> drama::Task::TaskPtr ( )

inline

Returns a weak pointer to the task.

This operator allows references to the task to be passed around various locations and used as needed.

If the Task object itself was created as a std::shared_pnt, then the return values will be linked to that pointer. If it is not, then an internal shared_pnt will be created.

Returns: A weak pointer to the task. Note that it is expected the user will only convert this to a std::shared_ptr for short periods, such that the task does not shut down whilst user code holding it (immediately taking the drama lock makes this safer).

Examples:: monitor1.cpp, monitor2.cpp, and tocker.cpp.

template<typename T >

std::shared_ptr<T> drama::Task::TaskPtrAs ( )

inline

Returns a shared pointer to the task, dynamically case to the template type.

It is often required to downcast from drama::Task to one of its subclasses before accessing methods. This method uses std::dynamic_pointer_cast to do that safely.

Template Parameters

T	A sub-class of drama::Task.

Returns: A std::shared_ptr<T> to the task.

Member Data Documentation

const int drama::Task::DefBufSize =20000

static

Default global buffer size.

const int drama::Task::DefSelfBufSize =2000

static

Default self buffer size.

The documentation for this class was generated from the following file:

task.hh

Detailed Description

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

WORKING WITH THREADED ACTIONS ???

DitsGetSigArg(3), but only if not null.

WORKING WITH THREADED ACTIONS ???

DitsGetSigArg(3), but only if not null.

Member Data Documentation