SmartACE::EventClient< P, E > Class Template Reference

Handles the event service on client side. More...

#include <smartEvent.hh>

Inheritance diagram for SmartACE::EventClient< P, E >:

Public Member Functions
	EventClient (SmartComponent *component, const std::string &port, WiringSlave *slave)
	Constructor (exposed as port wireable from outside by other components and without handler). More...
	EventClient (SmartComponent *component)
	Constructor (not wired with service provider, not exposed as port and without handler). More...
	EventClient (SmartComponent *component, const std::string &server, const std::string &service)
	Constructor (wired with specified service provider and without handler) More...
virtual	~EventClient ()
	Destructor. More...
Smart::StatusCode	add (WiringSlave *slave, const std::string &port)
	Add this instance to the set of ports wireable via the wiring pattern from outside the component. More...
Smart::StatusCode	remove ()
	Remove this service requestor from the set of ports wireable via the wiring pattern from outside the component. More...
Smart::StatusCode	connect (const std::string &server, const std::string &service)
	Connect this service requestor to the denoted service provider. More...
Smart::StatusCode	disconnect ()
	Disconnect the service requestor from the service provider. More...
Smart::StatusCode	blocking (const bool b)
	Allow or abort and reject blocking calls. More...
Smart::StatusCode	activate (const Smart::EventMode &mode, const P &parameter, Smart::EventIdPtr &id)
	Activate an event with the provided parameters in either "single" or "continuous" mode. More...
Smart::StatusCode	deactivate (const Smart::EventIdPtr id)
	Deactivate the event with the specified identifier. More...
Smart::StatusCode	tryEvent (const Smart::EventIdPtr id)
	Check whether event has already fired and return immediately with status information. More...
Smart::StatusCode	getEvent (const Smart::EventIdPtr id, E &event, const Smart::Duration &timeout=Smart::Duration::max())
	Blocking call which waits for the event to fire and then consumes the event. More...
Smart::StatusCode	getNextEvent (const Smart::EventIdPtr id, E &event, const Smart::Duration &timeout=Smart::Duration::max())
	Blocking call which waits for the next event. More...

Detailed Description

template<class P, class E>
class SmartACE::EventClient< P, E >

Handles the event service on client side.

Template parameters:

• P: Activation parameter class (Communication Object) contains individual parameters of the event activation.
• E: Event answer class (Communication Object) is returned when an event fires and can contain further details why and under which circumstances an event fired.

Demonstrated in fifth example

Constructor & Destructor Documentation

EventClient() [1/3]

template<class P , class E >

SmartACE::EventClient< P, E >::EventClient	(	SmartComponent *	component,
		const std::string &	port,
		WiringSlave *	slave
	)

Constructor (exposed as port wireable from outside by other components and without handler).

Constructs an EventClient for method oriented event processing. Use tryEvent()/getEvent()/getNextEvent() to process incoming events.

add()/remove() and connect()/disconnect() can always be used to change the status of the instance. Instance is not connected to a service provider.

Throws exception if port name is already in use.

• SMART_PORTALREADYUSED : port name already in use, instance not created
• SMART_ERROR : something went wrong, instance not created

Parameters

component	management class of the component
port	name of the wireable port
slave	wiring slave of this component

EventClient() [2/3]

template<class P , class E >

SmartACE::EventClient< P, E >::EventClient

(

SmartComponent *

component

)

Constructor (not wired with service provider, not exposed as port and without handler).

Constructs an EventClient for method oriented event processing. Use tryEvent()/getEvent()/getNextEvent() to process incoming events.

add()/remove() and connect()/disconnect() can always be used to change the status of the instance. Instance is not connected to a service provider and is not exposed as port wireable from outside the component.

(Currently exception not thrown)

Parameters

component

management class of the component

EventClient() [3/3]

template<class P , class E >

SmartACE::EventClient< P, E >::EventClient	(	SmartComponent *	component,
		const std::string &	server,
		const std::string &	service
	)

Constructor (wired with specified service provider and without handler)

Constructs an EventClient for method oriented event processing. Use tryEvent()/getEvent()/getNextEvent() to process incoming events. Connects to the denoted service and blocks until the connection has been established. Blocks infinitely if denoted service becomes not available since constructor performs retries. Blocking is useful to simplify startup of components which have mutual dependencies.

add()/remove() and connect()/disconnect() can always be used to change the status of the instance.

Throws exception if denoted service is incompatible (wrong communication pattern or wrong communication objects).

• SMART_INCOMPATIBLESERVICE : the denoted service is incompatible (wrong communication pattern or wrong communication objects) and can therefore not be connected. Instance is not created.
• SMART_ERROR : something went wrong, instance not created

Parameters

component	management class of the component
server	name of the server
service	name of the service

~EventClient()

template<class P , class E >

virtual SmartACE::EventClient< P, E >::~EventClient ( )

virtual

Destructor.

The destructor calls remove() and disconnect() and therefore properly deactivates every still active event and removes the instance from the set of wireable ports.

Member Function Documentation

activate()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::activate	(	const Smart::EventMode &	mode,
		const P &	parameter,
		Smart::EventIdPtr &	id
	)

Activate an event with the provided parameters in either "single" or "continuous" mode.

Parameters

mode	"single" or "continuous" mode
parameter	activation parameter class (Communication Object)
id	is set to the unique id of the event activation

Returns

status code

• SMART_OK : everything is ok, event is activated and id contains a valid activation identifier.
• SMART_DISCONNECTED : activation not possible since not connected to a server. No valid activation identifier id returned.
• SMART_ERROR_COMMUNICATION : communication problems, event not activated, id is not a valid activation identifier.
• SMART_ERROR : something went wrong, event not activated, id is not a valid activation identifier.

add()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::add	(	WiringSlave *	slave,
		const std::string &	port
	)

Add this instance to the set of ports wireable via the wiring pattern from outside the component.

Already established connections keep valid. If this service requestor is already exposed as port, it is first removed and then added with the new port name. add()/remove() and connect()/disconnect() can always be used to change the status of this instance.

Parameters

slave	wiring slave of this component
port	name of port used for wiring

Returns

status code

• SMART_OK : everything is OK and this instance added to the set of ports wireable from outside the component
• SMART_PORTALREADYUSED : port name already in use and this instance now not available as port
• SMART_ERROR : something went wrong

blocking()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::blocking

(

const bool

b

)

Allow or abort and reject blocking calls.

If blocking is set to false all blocking calls return with SMART_CANCELLED. This can be used to abort blocking calls.

Parameters

b	(blocking) true/false

Returns

status code

• SMART_OK : new mode set
• SMART_ERROR : something went wrong

connect()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::connect	(	const std::string &	server,
		const std::string &	service
	)

Connect this service requestor to the denoted service provider.

An already established connection is first disconnected. See disconnect() for implications on active events in that case.

It is no problem to change the connection to a service provider at any point of time irrespective of any calls to tryEvent()/getEvent() or getNextEvent().

Parameters

server	name of the server
service	name of the service

Returns

status code

• SMART_OK : everything is OK and connected to the specified service.
• SMART_SERVICEUNAVAILABLE : the specified service is currently not available and the requested connection can not be established. Service requestor is now not connected to any service provider.
• SMART_INCOMPATIBLESERVICE : the specified service provider is not compatible (wrong communication pattern or wrong communication objects) to this service requestor and can therefore not be connected. Service requestor is now not connected to any service provider.
• SMART_ERROR_COMMUNICATION : communication problems, service requestor is now not connected to any service provider.
• SMART_ERROR : something went wrong, service requestor is now not connected to any service provider.

deactivate()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::deactivate

(

const Smart::EventIdPtr

id

)

Deactivate the event with the specified identifier.

An event must always be deactivated, even if it has already fired in single mode. This is just necessary for cleanup procedures and provides a uniform user API independently of the event mode. Calling deactivate() while there are blocking calls aborts them with the appropriate status code.

Parameters

id	of event to be disabled

Returns

status code

• SMART_OK : everything is ok and event is deactivated
• SMART_WRONGID : there is no active event available with this id
• SMART_ERROR_COMMUNICATION : communication problems, event not deactivated
• SMART_ERROR : something went wrong, event not deactivated

(Hint: can not return SMART_DISCONNECTED since then each event is for sure also deactivated resulting in SMART_WRONGID)

disconnect()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::disconnect

(

)

Disconnect the service requestor from the service provider.

All blocking calls are aborted with the SMART_DISCONNECTED status code. All events are deactivated.

It is no problem to change the connection to a service provider at any point of time irrespective of any calls to tryEvent() / getEvent() or getNextEvent().

Returns

status code

• SMART_OK : everything is OK and service requestor is disconnected from the service provider.
• SMART_ERROR_COMMUNICATION : something went wrong at the level of the intercomponent communication. At least the service requestor is in the disconnected state irrespective of the service provider side clean up procedures.
• SMART_ERROR : something went wrong. Again at least the service requestor is in the disconnected state.

getEvent()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::getEvent	(	const Smart::EventIdPtr	id,
		E &	event,
		const Smart::Duration &	timeout = Smart::Duration::max()
	)

Blocking call which waits for the event to fire and then consumes the event.

This method consumes an event. Returns immediately if an unconsumed event is available. Blocks otherwise till event becomes available. If method is called concurrently from several threads with the same id and method is blocking, then every call returns with the same event once the event fired. If there is however already an unconsumed event available, then only one out of the concurrent calls consumes the event and the other calls return with appropriate status codes.

Parameters

id	of the event activation
event	is set to the returned event if fired (Communication Object)
timeout	the optional maximum waiting time for an event (default value max: method blocks indefinitely)

• single mode:

Since an event in single mode fires only once, return immediately if the event is already consumed. Also return immediately with an available and unconsumed event and consume it. Otherwise wait until the event fires.

Returns status code:

• SMART_OK : event fired and event is consumed and returned.
• SMART_PASSIVE : event fired and got consumed already. Returns immediately without valid event since it can not fire again in single mode.
• SMART_CANCELLED : waiting for the event to fire has been aborted or blocking is not not allowed anymore. Therefore no valid event is returned.
• SMART_DISCONNECTED : client is disconnected or got disconnected while waiting and therefore no valid event is returned and the activation identifier id is also not valid any longer due to automatic deactivation.
• SMART_NOTACTIVATED : got deactivated while waiting and therefore event not valid and also id not valid any longer.
• SMART_WRONGID : there is no activation available with this id and therefore event not valid.

• continuous mode:

Returns immediately if an unconsumed event is available. Returns the newest unconsumed event since activation. Otherwise waits until the event fires again.

Returns status code:

• SMART_OK : unconsumed event is available and event is consumed and returned. Due to the overwriting behavior, only the latest event is available.
• SMART_CANCELLED : blocking is not allowed anymore therefore blocking call has been aborted and event is not valid.
• SMART_DISCONNECTED : got disconnected while waiting and therefore event not valid and also id not valid any longer due to automatic deactivation.
• SMART_NOTACTIVATED : got deactivated while waiting and therefore event not valid and also id not valid any longer.
• SMART_WRONGID : there is no activation available with this id and therefore event not valid.

getNextEvent()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::getNextEvent	(	const Smart::EventIdPtr	id,
		E &	event,
		const Smart::Duration &	timeout = Smart::Duration::max()
	)

Blocking call which waits for the next event.

This methods waits for the next arriving event to make sure that only events arriving after entering the method are considered. Method consumes event. An old event that has been fired is ignored (in contrary to getEvent()). If method is called concurrently from several threads with the same id, then every call returns with the same event once the event fired.

Parameters

id	of the event activation
event	is set to the returned event if fired (Communication Object)
timeout	the optional maximum waiting time for an event (default value max: method blocks indefinitely)

• single mode:

In single mode one misses the event if it fired before entering this member function.

Returns status code:

• SMART_OK : event fired while waiting for the event and event is consumed and returned
• SMART_PASSIVE : event already fired between activation and calling this member function and is therefore missed or event has already been consumed and can not fire again in single mode. Does not block indefinitely and returns no valid event.
• SMART_CANCELLED : event not yet fired and waiting for the event has been aborted or blocking is not allowed anymore. No valid event is returned.
• SMART_DISCONNECTED : got disconnected while waiting and therefore event not valid and also id not valid any longer due to automatic deactivation.
• SMART_NOTACTIVATED : got deactivated while waiting and therefore event not valid and also id not valid any longer.
• SMART_WRONGID : there is no activation available with this id and therefore event not valid.

• continuous mode:

Makes sure that only events fired after entering this member function are considered.

Returns status code:

• SMART_OK : event fired while waiting for the event and event is consumed and returned
• SMART_CANCELLED : waiting for the next event has been aborted or blocking is not allowed anymore. No valid event is returned.
• SMART_DISCONNECTED : got disconnected while waiting and therefore event not valid and also id not valid any longer due to automatic deactivation.
• SMART_NOTACTIVATED : got deactivated while waiting and therefore event not valid and also id not valid any longer.
• SMART_WRONGID : there is no activation available with this id and therefore event not valid.

remove()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::remove

(

)

Remove this service requestor from the set of ports wireable via the wiring pattern from outside the component.

Already established connections keep valid but can now be changed only from inside and not from outside this component anymore.

Returns

status code

• SMART_OK : everything is OK and instance not exposed as port anymore (or was not registered as port).
• SMART_ERROR : something went wrong but this instance is removed from the set of ports in any case.

tryEvent()

template<class P , class E >

Smart::StatusCode SmartACE::EventClient< P, E >::tryEvent

(

const Smart::EventIdPtr

id

)

Check whether event has already fired and return immediately with status information.

This method does not consume an available event.

Parameters

id	of the event activation to be checked

Returns

status code

• single mode:
  • SMART_OK : event fired already, is still available and can be consumed by calling getEvent(),
  • SMART_ACTIVE : event has not yet fired
  • SMART_PASSIVE : event fired already and is already consumed.
  • SMART_WRONGID : there is no activation available with this id
• continuous mode:
  • SMART_OK : unconsumed event is available. Since events are overwritten this means that at least one new event has been received since the last event consumption.
  • SMART_ACTIVE : currently there is no unconsumed event available.
  • SMART_WRONGID : there is no activation available with this id

---

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

• smartEvent.hh