Detailed Description

A class which allows threads running in a User Interface or similar environments to send DRAMA messages.

Author: Tony Farrell, AAO

Revision: 1.45

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

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

#include "threaduface.hh"

Inheritance diagram for drama::thread::TUface:

Public Member Functions
	TUface (std::weak_ptr< Task > dramaTask)
	Create a DRAMA action/message handler object which runs a thread when the Obey message is received. More...

virtual	~TUface ()
	TUface destructor. More...

virtual const EntryInfo &	GetEntry () const
	Return the entry details. More...

Dits___CurActType	GetMessageContext () const override
	Get the DRAMA Context associated with the UFACE event. More...

std::shared_ptr< Task >	GetTask () const override
	Get a reference to the DRAMA task we are part of. More...

virtual bool	JoinThreads (std::chrono::steady_clock::time_point until) override
	Invoked when the drama::task::RunDrama() loop exits. More...

Task::mutexType &	Lock () 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...

virtual int	RunDramaHasExited () override
	Invoked when the drama::task::RunDrama() loop exits. More...

void	SetupWaitEvent (DitsTransIdType tid, drama::Path *pathObj) override
	Sets up a wait event for this thread. More...

Public Member Functions inherited from drama::thread::TMessHandler
	TMessHandler (const TMessHandler &source)=delete
	Copy constructor - deleted. More...

virtual	~TMessHandler ()
	Destructor. More...

TMessHandler &	operator= (const TMessHandler &rhs)=delete
	Assignment operator - deleted. More...

virtual const sds::PrintObjectCR &	SdsListToUser () const
	Get a reference to an SDS printer object which can be used to list an SDS object using MessageUser. 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...

Protected Member Functions
void	ClearWait (bool complete) override
	Clear the thread' waiting flag in _waitEventMap. More...

void	GrabEntryInfo ()
	Fetch the DRAMA Entry information. More...

void	WaitForTransactionFinish (const WaitEventData &details, TransEvtInfo const eventInfo, sds::IdPtr const arg)
	The wait for transaction operation has finished - tidy up. More...

WaitEventDetails *	WaitForTransactionStart ()
	Initiate waiting for a transaction and return a pointer to the item the wait event details. More...

Constructor & Destructor Documentation

drama::thread::TUface::TUface ( std::weak_ptr< Task > dramaTask )

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

Parameters

dramaTask The DRAMA Task we are part of. This is passed by pointer, but TUFace is not taking ownership of the subject object, which must continue to exist until the TUFace object is destroyed.

virtual drama::thread::TUface::~TUface ( )

virtual

TUface destructor.

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

Member Function Documentation

void drama::thread::TUface::ClearWait ( bool complete )

overrideprotectedvirtual

Clear the thread' waiting flag in _waitEventMap.

Parameters

complete If true, then it is known the transaction is actually complete. Set false if know to be not complete or unknown. Determines if we orphan the transaction.

Implements drama::thread::TMessHandler.

Referenced by WaitForTransactionFinish().

virtual const EntryInfo& drama::thread::TUface::GetEntry ( ) const

inlinevirtual

Return the entry details.

Returns: current entry details.

Dits___CurActType drama::thread::TUface::GetMessageContext ( ) const

overridevirtual

Get the DRAMA Context associated with the UFACE event.

Implements virtual baseclass TMessHander method.

Implements drama::thread::TMessHandler.

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

inlineoverridevirtual

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

Implements drama::thread::TMessHandler.

void drama::thread::TUface::GrabEntryInfo ( )

inlineprotected

Fetch the DRAMA Entry information.

References drama::EntryInfo::SetFromDits().

virtual bool drama::thread::TUface::JoinThreads ( std::chrono::steady_clock::time_point until )

overridevirtual

Invoked when the drama::task::RunDrama() loop exits.

Implements a method required by the RunDramaExitNotifier abstract class, which we sub-class. It provides a chance to join any threads created which have not yet been joined.

Note: The default implementation does nothing since TUface by itself does not deal with the threads. A sub-class might override this.

DRAMA Lock not taken when invoked.

Parameters

until The time point to wait for the join for.

Returns: The number of threads which were notified.

Implements drama::RunDramaExitNotifier.

Task::mutexType& drama::thread::TUface::Lock ( ) const

overridevirtual

Reference the DRAMA Task lock.

Implements virtual baseclass TMessHander method.

Implements drama::thread::TMessHandler.

void drama::thread::TUface::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.

This these will be sent in DRAMA's UFACE context, they will appear where ever the task is sending its UFACE MsgOut() messages. This is often set using DitsUfacePutMsgOut()

Implements drama::thread::TMessHandler.

virtual int drama::thread::TUface::RunDramaHasExited ( )

overridevirtual

Invoked when the drama::task::RunDrama() loop exits.

Implements a method required by the RunDramaExitNotifier abstract class, which we sub-class. It is used internally to notify any threads waiting on DRAMA messages that the message will never occur.

DRAMA Lock taken when invoked.

Returns: The number of threads which were notified.

Implements drama::RunDramaExitNotifier.

void drama::thread::TUface::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

tid	The 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.
pathObj	The drama::Path object we using to communicate with the target task. 0 (nullptr) for a kick message.

Implements drama::thread::TMessHandler.

void drama::thread::TUface::WaitForTransactionFinish	(	const WaitEventData &	details,
		TransEvtInfo *const	eventInfo,
		sds::IdPtr *const	arg
	)

inlineprotected

The wait for transaction operation has finished - tidy up.

References ClearWait().

WaitEventDetails* drama::thread::TUface::WaitForTransactionStart ( )

inlineprotected

Initiate waiting for a transaction and return a pointer to the item the wait event details.

Presumption is that SetupWaitEvent() has been invoked.

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

threaduface.hh

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation