Client part of query pattern to perform two-way communication. More...

#include <smartQuery.hh>

Inheritance diagram for SmartACE::QueryClient< R, A >:

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

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

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

virtual	~QueryClient ()
	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	query (const R &request, A &answer)
	Blocking Query. More...

Smart::StatusCode	queryRequest (const R &request, Smart::QueryIdPtr &id)
	Asynchronous Query. More...

Smart::StatusCode	queryReceive (const Smart::QueryIdPtr id, A &answer)
	Check if answer is available. More...

Smart::StatusCode	queryReceiveWait (const Smart::QueryIdPtr id, A &answer, const Smart::Duration &timeout=Smart::Duration::max())
	Wait for reply. More...

Smart::StatusCode	queryDiscard (const Smart::QueryIdPtr id)
	Discard the pending answer with the identifier id More...

Detailed Description

template<class R, class A>
class SmartACE::QueryClient< R, A >

Client part of query pattern to perform two-way communication.

Template parameters

R: request class (Communication Object)
A: answer (reply) class (Communication Object)

Demonstrated in first example and third example

Constructor & Destructor Documentation

◆ QueryClient() [1/3]

template<class R, class A>

SmartACE::QueryClient< R, A >::QueryClient	(	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 wireable port
slave	wiring slave of this component

◆ QueryClient() [2/3]

template<class R, class A>

SmartACE::QueryClient< R, A >::QueryClient ( 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

◆ QueryClient() [3/3]

template<class R, class A>

SmartACE::QueryClient< R, A >::QueryClient	(	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

◆ ~QueryClient()

template<class R, class A>

virtual SmartACE::QueryClient< R, A >::~QueryClient ( )

virtual

Destructor.

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

Member Function Documentation

◆ add()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::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 R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::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 R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::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 running or pending queries 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 query() / queryRequest() / queryReceive() or queryReceiveWait().

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 R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::disconnect ( )

Disconnect the service requestor from the service provider.

All blocking queries are aborted with the SMART_DISCONNECTED status code. Already received but not yet picked up answers keep valid and can still be picked up with queryReceive()/queryReceiveWait(). Not yet received answers at the time of disconnection are lost and calls to queryReceive()/queryReceiveWait() return with SMART_DISCONNECTED.

It is no problem to change the connection to a service provider at any point of time irrespective of any calls to query() / queryRequest() / queryReceive() or queryReceiveWait().

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.

◆ query()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::query	(	const R &	request,
		A &	answer
	)

Blocking Query.

Perform a blocking query and return only when the query answer is available. Member function is thread safe and thread reentrant.

Parameters

request	send this request to the server (Communication Object)
answer	returned answer from the server (Communication Object)

Returns

status code:

SMART_OK : everything is ok and answer contains answer
SMART_CANCELLED : blocking is not allowed or is not allowed anymore and therefore pending query is aborted, answer is lost and answer contains no valid answer.
SMART_DISCONNECTED : the client is either disconnected and no query can be made or it got disconnected and a pending query is aborted without answer. In both cases, answer is not valid.
SMART_ERROR_COMMUNICATION : communication problems, answer is not valid.
SMART_ERROR : something went wrong, answer is not valid.

◆ queryDiscard()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::queryDiscard ( const Smart::QueryIdPtr id )

Discard the pending answer with the identifier id

Call this member function if you do not want to get the answer of a request anymore which was invoked by queryRequest(). This member function invalidates the identifier id.

Warning: This member function does NOT abort blocking calls ! This is done by the blocking() member function. It has to be called if you have not yet received an answer and the identifier is still valid, for example due to a CANCELLED return value, and you don't want to get the answer anymore.; It is not allowed to call queryReceive(), queryReceiveWait() or queryDiscard() concurrently with the same query id (which is not a restriction since it makes no sense !)

Parameters

id	provides the identifier of the query

Returns

status code:

SMART_OK : everything is ok and query with the identifier id discarded.
SMART_WRONGID : no pending query with this identifier.
SMART_ERROR : something went wrong, id not valid any longer.

◆ queryReceive()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::queryReceive	(	const Smart::QueryIdPtr	id,
		A &	answer
	)

Check if answer is available.

Non-blocking call to fetch the answer belonging to the given identifier. Returns immediately. Member function is thread safe and reentrant.

Warning: It is not allowed to call queryReceive(), queryReceiveWait() or queryDiscard() concurrently with the same query id (which is not a restriction since it makes no sense !)

Parameters

id	provides the identifier of the query
answer	is set to the answer returned from the server if it was available

Returns

status code:

SMART_OK : everything is ok and answer contains the answer
SMART_WRONGID : no pending query with this identifier available, therefore no valid answer returned.
SMART_NODATA : answer not yet available, therefore try again later. The identifier id keeps valid, but answer contains no valid answer.
SMART_DISCONNECTED : the answer belonging to the id can not be received anymore since the client got disconnected. id is not valid any longer and answer contains no valid answer.
SMART_ERROR : something went wrong, answer contains no answer and id is not valid any longer.

◆ queryReceiveWait()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::queryReceiveWait	(	const Smart::QueryIdPtr	id,
		A &	answer,
		const Smart::Duration &	timeout = `Smart::Duration::max()`
	)

Wait for reply.

Blocking call to fetch the answer belonging to the given identifier. Waits until the answer is received.

Warning: It is not allowed to call queryReceive(), queryReceiveWait() or queryDiscard() concurrently with the same query id (which is not a restriction since it makes no sense !)

Parameters

id	provides the identifier of the query
answer	is set to the answer returned from the server if it was available
timeout	the optional maximum waiting time for a query answer (default value max: method blocks indefinitely)

Returns

status code:

SMART_OK : everything is ok and answer contains the answer
SMART_WRONGID : no pending query with this identifier available, therefore no valid answer returned.
SMART_CANCELLED : blocking call is not allowed or is not allowed anymore and therefore blocking call is aborted and no valid answer is returned. The query identifier id keeps valid and one can either again call queryReceive(), queryReceiveWait() or discard the answer by calling queryDiscard().
SMART_DISCONNECTED : blocking call is aborted and the answer belonging to id can not be received anymore since client got disconnected. id is not valid any longer and answer contains no valid answer.
SMART_ERROR : something went wrong, answer contains no answer and id is not valid any longer.

◆ queryRequest()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::queryRequest	(	const R &	request,
		Smart::QueryIdPtr &	id
	)

Asynchronous Query.

Perform a query and receive the answer later, returns immediately. Member function is thread safe and reentrant.

Parameters

request	send this request to the server (Communication Object)
id	is set to the identifier which is later used to receive the reply to this request

Returns

status code:

SMART_OK : everything is ok and id contains query identifier used to either fetch or discard the answer.
SMART_DISCONNECTED : request is rejected since client is not connected to a server and therefore id is not a valid identifier.
SMART_ERROR_COMMUNICATION : communication problems, id is not valid.
SMART_ERROR : something went wrong, id is not valid.

◆ remove()

template<class R, class A>

Smart::StatusCode SmartACE::QueryClient< R, A >::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.

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

smartQuery.hh

Public Member Functions

Detailed Description

template<class R, class A> class SmartACE::QueryClient< R, A >

Constructor & Destructor Documentation

◆ QueryClient() [1/3]

◆ QueryClient() [2/3]

◆ QueryClient() [3/3]

◆ ~QueryClient()

Member Function Documentation

◆ add()

◆ blocking()

◆ connect()

◆ disconnect()

◆ query()

◆ queryDiscard()

◆ queryReceive()

◆ queryReceiveWait()

◆ queryRequest()

◆ remove()

template<class R, class A>
class SmartACE::QueryClient< R, A >