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	PrepareToWait ()
virtual bool	Wait ()
virtual bool	WaitWithTimeout (double timeoutInSec)
virtual void	ClearWait ()
virtual void	Detach ()
virtual void	ToStream (std::ostream &outputStream) const =0

Protected Types
enum	WaitStates { EVENT_RECEIVER_IDLE , EVENT_RECEIVER_PREPARING , EVENT_RECEIVER_WAITING , EVENT_RECEIVER_SIGNALED }

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

Protected Attributes
std::string	Name
mtsInterfaceRequired *	Required
osaThreadSignal *	EventSignal
bool	OwnEventSignal
WaitStates	WaitState
osaMutex	WaitMutex

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, or the ThreadSignalForBlockingCommands member of the required interface for blocking commands. Otherwise, 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.

Member Enumeration Documentation

WaitStates

enum mtsEventReceiverBase::WaitStates

protected

Enumerator
EVENT_RECEIVER_IDLE
EVENT_RECEIVER_PREPARING
EVENT_RECEIVER_WAITING
EVENT_RECEIVER_SIGNALED

Constructor & Destructor Documentation

mtsEventReceiverBase()

mtsEventReceiverBase::mtsEventReceiverBase

(

)

~mtsEventReceiverBase()

virtual mtsEventReceiverBase::~mtsEventReceiverBase ( )

virtual

Member Function Documentation

CheckEventSignal()

void mtsEventReceiverBase::CheckEventSignal ( )

protected

CheckRequired()

bool mtsEventReceiverBase::CheckRequired ( ) const

protected

ClearWait()

virtual void mtsEventReceiverBase::ClearWait ( )

virtual

Clear the WaitState (set to EVENT_RECEIVER_IDLE)

Reimplemented in mtsEventReceiverWrite.

Detach()

virtual void mtsEventReceiverBase::Detach ( )

virtual

GetName()

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

inlinevirtual

PrepareToWait()

virtual bool mtsEventReceiverBase::PrepareToWait ( )

virtual

Indicate that the waiting thread is preparing to wait on an event, but that there may be some time before Wait or WaitWithTimeout will be called. Calling this command ensures that if the event if raised after the call to PrepareToWait, but before the call to Wait or WaitWithTimeout, that the Wait or WaitWithTimeout methods will return rather than wait indefinitely. It is not required to call this method, but it is recommended if there is a possibility of an indefinite (or infinite) wait if only a single event is expected and if it can occur before Wait or WaitWithTimeout is called. See the description of WaitStates above.

Returns

true if successful, false if failed.

Reimplemented in mtsEventReceiverWrite.

SetName()

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

inline

SetRequired()

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

virtual

Called from mtsInterfaceRequired::AddEventReceiver

SetThreadSignal()

virtual void mtsEventReceiverBase::SetThreadSignal ( osaThreadSignal * signal )

virtual

ToStream()

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

pure virtual

Human readable output to stream.

Implemented in mtsEventReceiverVoid, and mtsEventReceiverWrite.

Wait()

virtual bool mtsEventReceiverBase::Wait ( )

virtual

Wait for event to be issued.

Returns

true if successful, false if failed.

Reimplemented in mtsEventReceiverWrite.

WaitCommon()

bool mtsEventReceiverBase::WaitCommon ( )

protected

WaitWithTimeout()

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.

Reimplemented in mtsEventReceiverWrite.

Member Data Documentation

EventSignal

osaThreadSignal* mtsEventReceiverBase::EventSignal

protected

Name

std::string mtsEventReceiverBase::Name

protected

OwnEventSignal

bool mtsEventReceiverBase::OwnEventSignal

protected

Required

mtsInterfaceRequired* mtsEventReceiverBase::Required

protected

WaitMutex

osaMutex mtsEventReceiverBase::WaitMutex

protected

WaitState

WaitStates mtsEventReceiverBase::WaitState

protected

---

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

• tmp/cisst-saw/cisst/cisstMultiTask/mtsEventReceiver.h