Detailed Description

Message event handling objects.

When waiting for transactions in response to messages sent, objects of this type are used to process messages. A user may sub-class this and override the virtual methods in order to change the processing for events.

#include "path.hh"

Inheritance diagram for drama::MessageEventHandler:

Public Member Functions
virtual void	BulkDone (thread::ProcessInfo messInfo)
	Invoked if a bulk data done message is received. More...

virtual void	BulkTransferred (thread::ProcessInfo messInfo, DitsBulkInfoType bulkInfo)
	Invoked if a bulk data transferred message is received. More...

virtual void	ErrorReport (thread::ProcessInfo messInfo, const std::string &task, const ErsMessageVector &messages)
	Invoked if an error report for the user is received. More...

virtual bool	KickReceived (thread::ProcessInfo messInfo, const sds::IdPtr &arg)
	Invoked if an action waiting on a message receives a kick message during the wait. More...

virtual void	MessageComplete (thread::ProcessInfo messInfo, StatusType status, const sds::IdPtr &arg)
	Invoked if a message complete message is received. More...

virtual void	MessageRejected (thread::ProcessInfo messInfo, StatusType status)
	Invoked if the message sent was rejected by the target task. More...

virtual void	NewTransaction (DitsMsgType msgType, DitsTransIdType tid) override
	This method is invoked each time a messages is initiated. More...

virtual bool	Process (thread::ProcessInfo messInfo, const TransEvtInfo &eventInfo, const sds::IdPtr &arg) override final
	Method invoked to process messages. More...

virtual void	SignalReceived (thread::ProcessInfo messInfo, const sds::IdPtr &arg)
	Invoked if a signal for the action is received. More...

virtual void	TaskDied (thread::ProcessInfo messInfo, StatusType status)
	Invoked if the subsidiary task died whilst we were waiting for a reply from it. More...

virtual void	ThreadWaitAbort (thread::ProcessInfo messInfo, StatusType status)
	Invoked if the thread wait is aborted. More...

virtual void	TriggerReceived (thread::ProcessInfo messInfo, StatusType status, const sds::IdPtr &arg)
	Invoked if a trigger message is received. More...

virtual void	UserMessage (thread::ProcessInfo messInfo, const std::string &task, const std::string &message)
	Invoked if a message for the user is received. More...

Member Function Documentation

virtual void drama::MessageEventHandler::BulkDone ( thread::ProcessInfo messInfo )

virtual

Invoked if a bulk data done message is received.

This is invoked if the event handler is being used for a message involving sending bulk data. When this message arrives, the bulk data transfer is complete and this task is free to reuse the bulk data area.

The default behavior is a null operation. User tasks should sub-class and override this method if they want to do something else.

virtual void drama::MessageEventHandler::BulkTransferred	(	thread::ProcessInfo	messInfo,
		DitsBulkInfoType	bulkInfo
	)

virtual

Invoked if a bulk data transferred message is received.

This is invoked if the event handler is being used for a message involving sending bulk data. It is invoked each time there is an update on the transfer.

This event is only normally triggered if the receiving task is calling DitsBulkArgReport().

The default behavior is a null operation. User tasks should sub-class and override this method if they want to do something else (e.g. update parts of the bulk data area after the receiving task has read it).

Parameters

messInfo	Details on the message sent
bulkInfo	Details on the bulk data transfer. Elements TransferredBytes and TotalBytes will be set.

virtual void drama::MessageEventHandler::ErrorReport	(	thread::ProcessInfo	messInfo,
		const std::string &	task,
		const ErsMessageVector &	messages
	)

virtual

Invoked if an error report for the user is received.

This would normally only happen for UFACE transactions.

The default behavior is to report the message to the user.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
task	The name of the task which originated the message.
messages	The messages, a std::vector of ErsMessageType structures.

virtual bool drama::MessageEventHandler::KickReceived	(	thread::ProcessInfo	messInfo,
		const sds::IdPtr &	arg
	)

virtual

Invoked if an action waiting on a message receives a kick message during the wait.

The default behavior is to throw an exception. Subclasses should override as required.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
arg	The argument to the kick

Returns: true if we should continue waiting for messages. If false is returned, then the transaction is orphaned.

Reimplemented in drama::thread::MonitorMessageHandler.

virtual void drama::MessageEventHandler::MessageComplete	(	thread::ProcessInfo	messInfo,
		StatusType	status,
		const sds::IdPtr &	arg
	)

virtual

Invoked if a message complete message is received.

The default behavior is to throw an exception if the status in the completion message is bad, otherwise just to allow the wait to complete.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
status	The DRAMA status associated with the abort.
arg	The argument to the trigger.

virtual void drama::MessageEventHandler::MessageRejected	(	thread::ProcessInfo	messInfo,
		StatusType	status
	)

virtual

Invoked if the message sent was rejected by the target task.

The default behavior is to throw an appropriate exception.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
status	The DRAMA status associated with the abort.

virtual void drama::MessageEventHandler::NewTransaction	(	DitsMsgType	msgType,
		DitsTransIdType	tid
	)

overridevirtual

This method is invoked each time a messages is initiated.

This method can be used to access the DITS transaction id of the messages which are sent. This is useful in some cases, such as when transaction might be orphaned but will need to be handled, or, for example, if you might want to kick a spawnable action.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

msgType	The DITS Type of the message that was sent.
tid	The DITS transaction id.

virtual bool drama::MessageEventHandler::Process	(	thread::ProcessInfo	messInfo,
		const TransEvtInfo &	eventInfo,
		const sds::IdPtr &	arg
	)

finaloverridevirtual

Method invoked to process messages.

This implements functionality required by the parent class TransEvtProcessor and cannot be overridden by subclasses of this class.

virtual void drama::MessageEventHandler::SignalReceived	(	thread::ProcessInfo	messInfo,
		const sds::IdPtr &	arg
	)

virtual

Invoked if a signal for the action is received.

The default reports to the user via Ers that a signal message has been received and to gives some hints about how to handle it

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
arg	The argument to the signal

virtual void drama::MessageEventHandler::TaskDied	(	thread::ProcessInfo	messInfo,
		StatusType	status
	)

virtual

Invoked if the subsidiary task died whilst we were waiting for a reply from it.

The default behavior is to throw an appropriate exception.

Parameters

messInfo	Details on the message sent
status	The DRAMA status associated with the task death.

virtual void drama::MessageEventHandler::ThreadWaitAbort	(	thread::ProcessInfo	messInfo,
		StatusType	status
	)

virtual

Invoked if the thread wait is aborted.

This will be invoked if, whilst waiting for a message, the main DRAMA loop exits (task exiting), or the action thread completed (we must be running in a subsidiary thread) or of the user has invoked drama::Thread::TAction::AbortMessageWaits.

The default behavior is to throw an appropriate exception.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
status	The DRAMA status associated with the abort.

virtual void drama::MessageEventHandler::TriggerReceived	(	thread::ProcessInfo	messInfo,
		StatusType	status,
		const sds::IdPtr &	arg
	)

virtual

Invoked if a trigger message is received.

The default reports to the user via Ers that a trigger has been received and to gives some hints about how to handle it

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
status	The DRAMA status associated with the trigger.
arg	The argument to the trigger.

Reimplemented in drama::thread::MonitorMessageHandler.

virtual void drama::MessageEventHandler::UserMessage	(	thread::ProcessInfo	messInfo,
		const std::string &	task,
		const std::string &	message
	)

virtual

Invoked if a message for the user is received.

This would normally only happen for UFACE transactions.

The default behavior is to report the message to the user.

Note: When invoked, the DRAMA Lock is taken and the DRAMA context is that of the action (or UFACE context) the thread was running in. Since the lock is taken, don't do anything which waits.

Parameters

messInfo	Details on the message sent
task	The name of the task which originated the message.
message	The message itself.

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

path.hh

Detailed Description

Public Member Functions

Member Function Documentation