Detailed Description

A class which implements a DRAMA Message Handler.

Interface only. Users must sub-class and implement Request MessageReceived(). They may also want to implement ActionEnd().

A MessageHandler is used to handle Obey or Kick messages in particular. They might be used to implement an action or an action reschedule handler, or an action kick handler.

These objects can then be supplied to the drama::Task::Add() methods or the MessageHandler::PutObeyHandler() or MessageHandler::PutKickHandler() methods. One of these is also returned by drama::Spawnable::Spawn().

Note: The drama::MessageReceiveFunction function type provides alternative to creating one of these objects. It allows a function to be specified to drama::Task::Add() method or the MessageHandler::PutObeyHandler() or MessageHandler::PutKickHandler() methods.

Author: Tony Farrell, AAO

Revision: 1.45

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

Examples:: dramahello.cpp.

#include "messagehandler.hh"

Inheritance diagram for drama::MessageHandler:

Public Member Functions
	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 EntryInfo &	GetEntry ()
	Return the action entry details. More...

virtual std::shared_ptr< Task >	GetTask () const
	Returns a pointer to the task. More...

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

MessageHandler &	operator= (const MessageHandler &rhs)=delete
	Copy operator deleted. More...

MessageHandler &	operator= (MessageHandler &&rhs)=default
	Move operator. More...

virtual void	PutKickHandler (MessageHandlerPtr obj)
	Put a message handler object for the next Kick event. More...

virtual void	PutKickHandler (MessageReceiveFunction func)
	Put a message handler function for the next Kick event. More...

virtual void	PutObeyHandler (MessageHandlerPtr obj)
	Put a message handler object for the next Obey reschedule event. More...

virtual void	PutObeyHandler (MessageReceiveFunction func)
	Put a message handler function for the next Obey reschedule event. 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...

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...

Protected Member Functions
virtual void	ActionEnd (bool taskExiting, StatusType actionEndStatus)
	Method Invoked when the action completes. More...

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

virtual Request	MessageReceived ()=0
	Method invoked by DRAMA to handle the message. More...

Constructor & Destructor Documentation

drama::MessageHandler::MessageHandler ( )

inline

Create a DRAMA action/message handler object.

virtual drama::MessageHandler::~MessageHandler ( )

virtual

MessageHandler destructor.

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

drama::MessageHandler::MessageHandler ( const MessageHandler & source )

delete

Assignment operator deleted.

No copying or assignment of these

drama::MessageHandler::MessageHandler ( MessageHandler && source )

default

Move assignment operator.

Member Function Documentation

virtual void drama::MessageHandler::ActionEnd	(	bool	taskExiting,
		StatusType	actionEndStatus
	)

protectedvirtual

Method Invoked when the action completes.

A default implementation of an action end method, invoked when the action ends, whatever the reason. The user should override this if they want to be notified about the action completing.

This method is only invoked for objects specified to a Task::Add method, or returned by drama::Spawnable::Spawn.

This method is called after any bulk data has tidied up but before any remaining ERS messages are flushed (so they can be annulled or added to) and before the action completion message is returned to the parent task.

The MessageHandler::GetTask() method will be valid during this method.

Warning: This is a private member, not a protected member. Doxygen sees this as protected to work around a Doxygen issue.

Parameters

taskExiting	Will be true if being invoked as the task exits.
actionEndStatus	The final DRAMA status code of the action.

virtual const EntryInfo& drama::MessageHandler::GetEntry ( )

inlinevirtual

Return the action entry details.

Returns: current action entry details.

Examples:: dramahello.cpp.

virtual std::shared_ptr<Task> drama::MessageHandler::GetTask ( ) const

inlinevirtual

Returns a pointer to the task.

If we are not in an action or action end handler, then returns nullptr.

Note: Only valid if invoked in the contact of MessageReceived() being invoked.

Returns: pointer to the task object.

Reimplemented in drama::thread::TAction.

void drama::MessageHandler::GrabEntryInfo ( )

inlineprotected

Fetch the DRAMA Entry information.

Normally used internally only, but sometimes needed from sub-classes if they need to update the values (for example, if we call back from another handler to this object).

References drama::EntryInfo::SetFromDits().

virtual Request drama::MessageHandler::MessageReceived ( )

protectedpure virtual

Method invoked by DRAMA to handle the message.

A subclass must implement this method, which is invoked by DRAMA when an Obey or Kick message occurs. depending on where this object has been specified.

The following methods will be valid during this call: MessageHandler::MessageUser(), MessageHandler::GetTask(), MessageHandler::GetEntry(), MessageHandler::PutKickHandler, MessageHandler::PutObeyHandler, MessageHandler::SdsListToUser(), MessageHandler::SendTrigger(), MessageHandler::SendBulkTrigger(), MessageHandler::SetReturnArg().

Warning: This is a private member, not a protected member. Doxygen sees this as protected to work around a Doxygen issue.

Returns: The reschedule request for the action - is the action to complete or be rescheduled later.

Implemented in drama::MessageHandlerViaFunctor.

Examples:: dramahello.cpp.

virtual void drama::MessageHandler::MessageUser ( const std::string & text ) const

virtual

Use DRAMA to send a message to the user.

The supplied text is send to the user using, see MsgOut(). Normally this appears the user interface.

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

Note: Only valid if invoked in the contact of MessageReceived() being invoked.

Parameters

text	The string to output to the user.

Reimplemented in drama::thread::TAction.

Examples:: dramahello.cpp.

MessageHandler& drama::MessageHandler::operator= ( const MessageHandler & rhs )

delete

Copy operator deleted.

No copying or assignment of these

MessageHandler& drama::MessageHandler::operator= ( MessageHandler && rhs )

default

Move operator.

virtual void drama::MessageHandler::PutKickHandler ( MessageHandlerPtr obj )

inlinevirtual

Put a message handler object for the next Kick event.

Will be reset to a null handler when the action completes.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

obj	The object which will handle the kick event. The MessageReceived method of this object will be invoked. Passed by std::shrared_ptr. The object must be a sub-class of drama::MessageHandler.

Reimplemented in drama::thread::TAction.

References DramaTHROW.

virtual void drama::MessageHandler::PutKickHandler ( MessageReceiveFunction func )

virtual

Put a message handler function for the next Kick event.

Will be reset to a null handler when the action completes.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

func	A function to be invoked to handle the kick event. The only argument to this function is a drama::MessageHandler object, but not the one on which this was invoked. Instead, a separately allocated object. It returns the reschedule request.

virtual void drama::MessageHandler::PutObeyHandler ( MessageHandlerPtr obj )

inlinevirtual

Put a message handler object for the next Obey reschedule event.

Will be reset to the default handler when the action completes.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

obj	The object which will handle the reschedule event. The MessageReceived method of this object will be invoked. Passed by std::shrared_ptr. The object must be a sub-class of drama::MessageHandler.

Reimplemented in drama::thread::TAction.

References DramaTHROW.

virtual void drama::MessageHandler::PutObeyHandler ( MessageReceiveFunction func )

virtual

Put a message handler function for the next Obey reschedule event.

Will be reset to the default handler when the action completes.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

func	A function to be invoked to handle the reschedule event. The only argument to this function is a drama::MessageHandler object, but not the one on which this was invoked. Instead, a separately allocated object. It returns the reschedule request.

virtual const sds::PrintObjectCR& drama::MessageHandler::SdsListToUser ( ) const

virtual

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

Note: Only valid if invoked in the contact of MessageReceived() being invoked.

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

Reimplemented in drama::thread::TAction.

Examples:: dramahello.cpp.

void drama::MessageHandler::SendBulkTrigger	(	BulkData *	arg,
		DitsTransIdType *	transId,
		bool	isSds,
		unsigned	notifyBytes = `1024 *1024`
	)

Send a bulk data trigger message to the parent action.

This method sends a trigger message (see SendTrigger()) with a bulk data argument.

The trigger message has an amount of shared memory associated with it, created as a drama::BulkData object. The bulk data is passed as efficiently as possible to the target task, and may not need to be copied at all (if on the same machine).

If the bulk data contains an exported SDS item, then the target task can receive the bulk data without doing any more work. Alternatively, and required if SDS is not involved, the target task can use various inquiry functions to handle it in a special way.

Sending of bulk data involves creating an DRAMA message transaction and this routine returns the associated transaction id. The sending action should receive additional reschedule events with an entry reason of EntryCode::BulkTransferred indicating the progress of the transfer. It will also receive an entry with a reason of EntryCode::BulkDone when the target task releases the shared memory.

When processing a EntryCode::BulkTransferred, you can then call GetEntry().GetBulkInfo() to retrieve details of the transfer.

The reception of EntryCode::BulkTransferred messages are dependent on the behavour of the target task. If it is a local task, then these mesages are recevid each time it calls drama::BulkDataArg::Report().

If the target task is remote, these update messages are sent by the local IMP transmitter task at a rate determined by it.

If NotifyBytes is non-zero it indicates a hint to the target about the rate at which these notifications are requested.

You should not delete the shared memory yourself until get the first message using one of these codes. When you get EntryCode::BulkDone you are free to reuse all the shared memory as the target task has finished accessing the shared memory. You can reuse parts of the shared memory early by making use of information in GetEntry().GetBulkInfo() to determine what parts of the bulk data have been used.

If the target task is local, then EntryCode::BulkDone is received when the target task action entry returns or if in the case where the the task invokes DitsBulkArgInfo(3)(), when it has called DitsBulkArgRelease(3)().

If the target task is remote, then EntryCode::BulkDone is received when the local transmitter task has finished forwarding the data to the remote machine.

As a result, in the remote task case, you are not notified when the target task has finished accessing the data, just when it is safe for you to re-use the local shared memory.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

arg	The Bulk Data segment to be the argument to the trigger message.
transId	Transaction id for the transaction started. This will be unique (any one time - they are reused) and allows the application to distinguish multiple different outstanding trigger replies. If specified as a nullptr, then no replies be received and you won't know when the transfer is complete.
isSds	Does arg contain an SDS item? If true, the target task can access the item as an argument using using SDS in the normal way If false, the shared memory contains data in an application private format and DRAMA makes no attempt to interpret it.
notifyBytes	If non-zero, it indicates your action should be notified (using EntryCode::BulkTransferred entries) every time the specified number of bytes are transferred. Note the this effect is somewhat dependent on the target task behavior and you may only receive the final EntryCode::BulkDone message.

Referenced by SendBulkTrigger().

void drama::MessageHandler::SendBulkTrigger	(	BulkDataSds *	arg,
		DitsTransIdType *	transId,
		unsigned	notifyBytes = `1024*1024`
	)

inline

Send a bulk data trigger message to the parent action.

In this version - the bulk data item contains an SDS item.

See SendBulkTrigger() for details about the general case.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

arg	The Bulk Data segment to be the argument to the trigger message, which will contain an SDS item.
transId	Transaction id for the transaction started. This will be unique (any one time - they are reused) and allows the application to distinguish multiple different outstanding trigger replies. If specified as a nullptr, then no replies be received and you won't know when the transfer is complete.
notifyBytes	If non-zero, it indicates your action should be notified (using EntryCode::BulkTransferred entries) every time the specified number of bytes are transferred. Note the this effect is somewhat dependent on the target task behavior and you may only receive the final EntryCode::BulkDone message.

References SendBulkTrigger().

void drama::MessageHandler::SendTrigger ( const sds::Id & arg ) const

Send a trigger message to the parent action.

A trigger message is a way for an action to send messages to its parent action without completing. The parent action is that action (probably in another task) which sent the OBEY message which initiated this action.

It is up to the parent action to interpret these trigger message (so they are a protocol that is up to the two takes involved to define).

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

arg	The SDS Id of the argument to the trigger message.

void drama::MessageHandler::SetReturnArg	(	const sds::Id &	arg,
		bool	copy = `true`
	)

inline

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

This is only sent if the action completes returning a request code of drama::RequestCode::End or drama::RequestCode::Exit.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

arg	The SDS ID of the structure to be sent with the completion message.
copy	If 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 which must ensure the item outlives the completion of the action.

References DramaTHROW.

void drama::MessageHandler::SetReturnArg ( sds::Id * arg )

inline

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

This is only sent if the action completes returning a request code of drama::RequestCode::End or drama::RequestCode::Exit.

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. The drama::sds::Id::COut(true) is invoked on the argument and DRAMA will take control of tidying it up.

Note: Only valid if invoked in the contact of MessageReceived() being invoked for an Obey or Kick message.

Parameters

arg	The SDS ID of the structure to be sent with the completion message.

References drama::sds::Id::COut(), and DramaTHROW.

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

messagehandler.hh

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation