Client part of the Push pattern to provide a flexible push service. More...

#include <smartPush.hh>

Inheritance diagram for SmartACE::PushClient< DataType >:

Public Member Functions
	PushClient (SmartComponent component, const std::string &port, WiringSlave slave)
	Constructor (exposed as port and wireable from outside by other components). More...

	PushClient (SmartComponent *component)
	Constructor (not wired with service provider and not exposed as port). More...

	PushClient (SmartComponent *component, const std::string &server, const std::string &service)
	Constructor (wired with specified service provider). More...

virtual	~PushClient ()
	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	subscribe (const unsigned int &prescale=1)
	Subscribe at the server to periodically get every n-th update. More...

Smart::StatusCode	unsubscribe ()
	Unsubscribe to get no more updates. More...

Smart::StatusCode	blocking (const bool b)
	Allow or abort and reject blocking calls. More...

Smart::StatusCode	getUpdate (DataType &d)
	Non-blocking call to immediately return the latest available data buffered at the client side from the most recent update. More...

Smart::StatusCode	getUpdateWait (DataType &d, const Smart::Duration &timeout=Smart::Duration::max())
	Blocking call which waits until the next update is received. More...

Smart::StatusCode	getServerInfo (SmartTimeValue &t, bool &r)
	Get cycle time and server state. More...

Detailed Description

template<class DataType>
class SmartACE::PushClient< DataType >

Client part of the Push pattern to provide a flexible push service.

Clients can subscribe to regularly get every n-th update. This class implements the Subject part of the Observer design pattern (see also PushClientObserver class).

Template parameters

T: Pushed value class (Communication Object)

Demonstrated in eigth example

Constructor & Destructor Documentation

◆ PushClient() [1/3]

template<class DataType >

SmartACE::PushClient< DataType >::PushClient	(	SmartComponent *	component,
		const std::string &	port,
		WiringSlave *	slave
	)

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

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 client-port (visible in wiring-slave)
slave	reference to wiring-slave

◆ PushClient() [2/3]

template<class DataType >

SmartACE::PushClient< DataType >::PushClient ( SmartComponent * component )

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

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

◆ PushClient() [3/3]

template<class DataType >

SmartACE::PushClient< DataType >::PushClient	(	SmartComponent *	component,
		const std::string &	server,
		const std::string &	service
	)

Constructor (wired with specified service provider).

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

◆ ~PushClient()

template<class DataType >

virtual SmartACE::PushClient< DataType >::~PushClient ( )

virtual

Destructor.

The destructor calls remove() and disconnect() and therefore properly cleans up every pending data reception and removes the instance from the set of wireable ports.

Member Function Documentation

◆ add()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::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 DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::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 DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::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 pending data reception 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 getUpdate() / getUpdateWait().

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.

◆ disconnect()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::disconnect ( )

Disconnect the service requestor from the service provider.

A disconnect always first performs an unsubscribe. See unsubsribe() for implications on getUpdate() and getUpdateWait().

It is no problem to change the connection to a service provider at any point of time irrespective of any calls to getUpdate() / getUpdateWait().

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.

◆ getServerInfo()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::getServerInfo	(	SmartTimeValue &	t,
		bool &	r
	)

Get cycle time and server state.

Returns cycle time of server in [seconds] and server state indicating whether server is activated or not. The client can decide on the cycle time on its individual update rate at subscription.

Parameters

t	is set to the server cycle time [seconds]
r	indicates whether server is started [true, false]

Returns

status code

SMART_OK : everything is ok and returned values are valid.
SMART_DISCONNECTED : client is not connected to a server and therefore not get any valid server info.
SMART_ERROR_COMMUNICATION : communication problems and returned server info is not valid.
SMART_ERROR : something went completely wrong and no valid server info returned.

◆ getUpdate()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::getUpdate ( DataType & d )

Non-blocking call to immediately return the latest available data buffered at the client side from the most recent update.

No data is returned as long as no update is received since subscription. To avoid returning old data, no data is returned after the client is unsubscribed or when the server is not active.

Parameters

d	is set to the newest currently available data

Returns

status code

SMART_OK : everything ok and latest data since client got subscribed is returned.
SMART_NODATA : client has not yet received an update since subscription and therefore no data is available and no data is returned.
SMART_NOTACTIVATED : the server is currently not active and does therefore not provide updates at the expected rate. No valid data returned.
SMART_UNSUBSCRIBED : no data available since client is not subscribed and can therefore not receive updates. Method does not return old data from last subscription since these might be based on too old parameter settings. To get data one has to be subscribed.
SMART_DISCONNECTED : no data returned since client is even not connected to a server.
SMART_ERROR : something went wrong

◆ getUpdateWait()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::getUpdateWait	(	DataType &	d,
		const Smart::Duration &	timeout = `Smart::Duration::max()`
	)

Blocking call which waits until the next update is received.

Blocking is aborted with the appropriate status if either the server gets deactivated, the client gets unsubscribed or disconnected or if blocking is not allowed any more at the client.

Parameters

d	is set to the newest currently available data
timeout	allows to release the blocking wait after a given timeout time (the default max time means infinite blocking)

Returns

status code

SMART_OK : everything is ok and just received data is returned.
SMART_CANCELLED : blocking is not allowed or is not allowed anymore. Waiting for the next update is aborted and no valid data is returned.
SMART_NOTACTIVATED : the server is currently not active and does therefore not provide updates at the expected rate. No valid data returned.
SMART_UNSUBSCRIBED : returns immediately without data if the client is not subscribed.
SMART_DISCONNECTED : returns immediately without data since client is even not connected to a server.
SMART_ERROR : something went completely wrong and no valid data returned.

◆ remove()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::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.

◆ subscribe()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::subscribe ( const unsigned int & prescale = 1 )

Subscribe at the server to periodically get every n-th update.

A newly subscribed client gets the next available new data and is then updated with regard to its individual update cycle.

Parameters

prescale whole-numbered value to set the update rate to every n-th value

Returns

status code

SMART_OK : everything is ok and client is subscribed
SMART_DISCONNECTED : client is not connected to a server and can therefore not subscribe for updates, not subscribed
SMART_ERROR_COMMUNICATION : communication problems, not subscribed
SMART_ERROR : something went wrong, not subscribed

◆ unsubscribe()

template<class DataType >

Smart::StatusCode SmartACE::PushClient< DataType >::unsubscribe ( )

Unsubscribe to get no more updates.

All blocking calls are aborted with the appropriate status and yet received and still buffered data is deleted to avoid returning old data.

Returns

status code

SMART_OK : everything is ok and client is now unsubscribed or has already been unsubscribed
SMART_ERROR_COMMUNICATION : communication problems, not unsubscribed
SMART_ERROR : something went wrong, not unsubscribed

(can not return SMART_DISCONNECTED since then client is for sure also unsubscribed which results in SMART_OK)

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

smartPush.hh

Public Member Functions

Detailed Description

template<class DataType> class SmartACE::PushClient< DataType >

Constructor & Destructor Documentation

◆ PushClient() [1/3]

◆ PushClient() [2/3]

◆ PushClient() [3/3]

◆ ~PushClient()

Member Function Documentation

◆ add()

◆ blocking()

◆ connect()

◆ disconnect()

◆ getServerInfo()

◆ getUpdate()

◆ getUpdateWait()

◆ remove()

◆ subscribe()

◆ unsubscribe()

template<class DataType>
class SmartACE::PushClient< DataType >