mtsEventReceiverBase Class Reference

#include <mtsEventReceiver.h>

Inheritance diagram for mtsEventReceiverBase:

Public Member Functions
	mtsEventReceiverBase ()
virtual	~mtsEventReceiverBase ()
void	SetName (const std::string &name)
virtual std::string	GetName () const
virtual void	SetRequired (const std::string &name, mtsInterfaceRequired *req)
virtual void	SetThreadSignal (osaThreadSignal *signal)
virtual bool	Wait ()
virtual bool	WaitWithTimeout (double timeoutInSec)
virtual void	Detach ()
virtual void	ToStream (std::ostream &outputStream) const =0

Protected Member Functions
bool	CheckRequired () const
bool	WaitCommon ()

Protected Attributes
std::string	Name
mtsInterfaceRequired *	Required
osaThreadSignal *	EventSignal
bool	Waiting
bool	OwnEventSignal

Detailed Description

This class implements event receivers for void and write events. The idea is similar to the mtsFunction classes (e.g., mtsFunctionVoid, mtsFunctionRead) – these event receivers should be added to a required interface and will be bound to the corresponding event generators in the connected provided interface. Then, it is possible for the component to specify an event handler at any time (see SetHandler method), or to wait for the event to occur (see Wait method).

Previously, it was only possible to add event handlers to a required interface (see mtsInterfaceRequired::AddEventHandlerVoid, mtsInterfaceRequired::AddEventHandlerWrite). For backward compatibility, this design continues to support direct addition of an event handler to a required interface. Thus, the following three blocks of code can all be used to set an event handler:

mtsInterfaceRequired required;

// Method 1: Add event handler directly to required interface (no event receiver)
required->AddEventHandlerVoid(&MyClass::Handler, this, "EventName");

// Method 2: Add event handler via event receiver
mtsEventReceiverVoid MyReceiver;
required->AddEventReceiver(MyReceiver, "EventName");
MyReceiver.SetHandler(&MyClass::Handler, this);

// Method 3: Add event handler and event receiver to required interface
//           (although this works, Method 2 is the preferred implementation)
mtsEventReceiverVoid MyReceiver;
required->AddEventReceiver(MyReceiver, "EventName");
required->AddEventHandlerVoid(&MyClass::Handler, this, "EventName");

One thing to note about an event receiver is that, by default, it is considered required (i.e., MTS_REQUIRED) when added to a required interface, whereas event handlers are not.

There are two main reasons for the introduction of event handlers:

1. They allow the component to wait for an event.
2. They allow event handlers to be added at any time. Previously, if an event handler was added to a required interface AFTER that interface was connected, it was ignored (i.e., it was not added as an observer to the event generator in the provided interface).

The implementation of the event receiver class requires an osaThreadSignal to block the component when the Wait method is called. This design uses the ThreadSignal member of the required interface mailbox, which is present for any component derived from mtsTask. If the required interface does not have a mailbox, the event receiver will create its own instance of osaThreadSignal. This is done to support use of event receivers by low-level components that do not have their own thread of execution (e.g., mtsComponent), as long as the Wait method is only called from a single thread. Note that the Wait method returns a bool; a false return indicates that the Wait failed for some reason (such as being called from more than one thread). An alternate implementation would be to introduce an osaThreadSignal member to mtsComponent and use that instead of the one in the required interface mailbox.

Constructor & Destructor Documentation

mtsEventReceiverBase::mtsEventReceiverBase

(

)

virtual mtsEventReceiverBase::~mtsEventReceiverBase ( )

virtual

Member Function Documentation

bool mtsEventReceiverBase::CheckRequired ( ) const

protected

virtual void mtsEventReceiverBase::Detach ( )

virtual

virtual std::string mtsEventReceiverBase::GetName ( void  ) const

inlinevirtual

void mtsEventReceiverBase::SetName ( const std::string &  name )

inline

virtual void mtsEventReceiverBase::SetRequired ( const std::string &  name, mtsInterfaceRequired *  req  )

virtual

Called from mtsInterfaceRequired::AddEventReceiver

virtual void mtsEventReceiverBase::SetThreadSignal ( osaThreadSignal *  signal )

virtual

virtual void mtsEventReceiverBase::ToStream ( std::ostream &  outputStream ) const

pure virtual

Human readable output to stream.

Implemented in mtsEventReceiverWrite, and mtsEventReceiverVoid.

virtual bool mtsEventReceiverBase::Wait ( )

virtual

Wait for event to be issued.

Returns

true if successful, false if failed.

bool mtsEventReceiverBase::WaitCommon ( )

protected

virtual bool mtsEventReceiverBase::WaitWithTimeout ( double  timeoutInSec )

virtual

Wait for event to be issued, up to specified timeout.

Returns

true if successful, false if failed or timeout occurred.

Member Data Documentation

osaThreadSignal* mtsEventReceiverBase::EventSignal

protected

std::string mtsEventReceiverBase::Name

protected

bool mtsEventReceiverBase::OwnEventSignal

protected

mtsInterfaceRequired* mtsEventReceiverBase::Required

protected

bool mtsEventReceiverBase::Waiting

protected

---

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

• /home/adeguet1/catkin_ws/src/cisst-saw/cisst/cisstMultiTask/mtsEventReceiver.h