<<reference-type>> Allows receiving requests and sending replies More...

#include <rti/request/Replier.hpp>

Inheritance diagram for rti::request::Replier< RequestType, ReplyType >:

Public Member Functions
	Replier (dds::domain::DomainParticipant participant, const std::string &service_name)
	Creates a Replier with the minimum set of parameters. More...

	Replier (const ReplierParams &params)
	Creates a Replier with parameters. More...

	Replier (const ReplierParams &params, Listener *the_listener)
	Creates a replier with additional parameters and a listener. More...

	Replier (const ReplierParams &params, std::shared_ptr< Listener > the_listener)
	Creates a replier with additional parameters and a listener. More...

void	send_reply (const ReplyType &reply, const rti::core::SampleIdentity &related_request_id)
	Sends a reply for a previous request. More...

void	send_reply (const ReplyType &reply, const dds::sub::SampleInfo &related_request_info)
	Sends a reply. More...

void	send_reply (const ReplyType &reply, rti::pub::WriteParams &params)
	Sends a reply with advanced parameters. More...

bool	wait_for_requests (const dds::core::Duration &max_wait)
	Waits for requests. More...

bool	wait_for_requests (int min_count, const dds::core::Duration &max_wait)
	Waits for requests. More...

dds::sub::LoanedSamples< RequestType >	receive_requests (const dds::core::Duration &max_wait)
	Waits for multiple requests and provides a loaned container to access them. More...

dds::sub::LoanedSamples< RequestType >	receive_requests (int min_count, const dds::core::Duration &max_wait)
	Waits for multiple requests and provides a loaned container to access them. More...

dds::sub::LoanedSamples< RequestType >	take_requests ()
	Takes all the requests. More...

dds::sub::LoanedSamples< RequestType >	read_requests ()
	Reads all the requests. More...

Listener *	listener () const
	Gets the replier listener. More...

void	listener (Listener *the_listener, const dds::core::status::StatusMask &=dds::core::status::StatusMask::none())
	Sets a listener to be notified when requests are available. More...

std::shared_ptr< Listener >	get_listener () const
	Gets the replier listener. More...

void	set_listener (std::shared_ptr< Listener > the_listener)
	Sets a listener to be notified when requests are available. More...

dds::sub::DataReader< RequestType >	request_datareader () const
	Retrieves the underlying dds::sub::DataReader. More...

dds::pub::DataWriter< ReplyType >	reply_datawriter () const
	Retrieves the underlying dds::pub::DataWriter. More...

Detailed Description

template<typename RequestType, typename ReplyType>
class rti::request::Replier< RequestType, ReplyType >

<<reference-type>> Allows receiving requests and sending replies

Note: A Replier provides all the functions of a <<reference-type>> except close() and retain().

A Replier is an entity with two associated topics: a request topic and a reply topic. It can receive requests by subscribing to the request topic and can send replies to those requests by publishing the reply topic.

Valid types for these topics are: those generated by the rtiddsgen code generator, the DDS built-in types, and dds::core::xtypes::DynamicData. See Creating a Replier.

A Replier has four main types of operations:

Waiting for requests to be received from the middleware
Getting those requests
Receiving requests (a convenience operation that is a combination of waiting and getting in a single operation)
Sending a reply for a previously received request (i.e., publishing a reply sample on the reply topic with special meta-data so that the orignal Requester can identify it)

For multi-reply scenarios in which a rti::request::Replier generates more than one reply for a request, the rti::request::Replier should mark all the intermediate replies (all but the last) using the rti::core::SampleFlag::intermediate_reply_sequence flag in rti::pub::WriteParams::flag.

Much like a Requester, a Replier has an associated dds::domain::DomainParticipant, which can be shared with other Repliers or RTI Connext routines. All the other entities required for the request-reply interaction, including a dds::pub::DataWriter for writing replies and a dds::sub::DataReader for reading requests, are automatically created when the Replier is constructed.

Quality of Service for the underlying DataWriter and DataReader can be configured (see RequesterParams::qos_profile). By default, they are created with dds::core::policy::ReliabilityKind_def::RELIABLE. The exact default configuration is described here: Configuring Request-Reply QoS profiles

There are several ways to use a Replier:

A thread receives requests and then dispatches them. If the computation of a reply is a simple operation, consider using a SimpleReplier instead of a Replier.
Polling without waiting, using rti::request::Replier::take_requests directly.
Using a ReplierListener to get notified and get the requests within the callback.

Template Parameters

RequestType	The data type for the request topic
ReplyType	The data type for the reply topic

See also: rti::request::Requester; Request-Reply Examples; Basic Replier example

Constructor & Destructor Documentation

◆ Replier() [1/4]

template<typename RequestType, typename ReplyType>

rti::request::Replier< RequestType, ReplyType >::Replier	(	dds::domain::DomainParticipant	participant,
		const std::string &	service_name
	)

inline

Creates a Replier with the minimum set of parameters.

Parameters

participant	The DomainParticipant that this Replier uses to join a domain.
service_name	The service name. See ReplierParams::service_name

Exceptions

One	of the Standard Exceptions

Referenced by rti::request::Replier< RequestType, ReplyType >::Replier().

◆ Replier() [2/4]

template<typename RequestType, typename ReplyType>

rti::request::Replier< RequestType, ReplyType >::Replier ( const ReplierParams & params )

inlineexplicit

Creates a Replier with parameters.

Parameters

params All the parameters that configure this Replier

Exceptions

One	of the Standard Exceptions

See also: ReplierParams; Creating a Replier

◆ Replier() [3/4]

template<typename RequestType, typename ReplyType>

rti::request::Replier< RequestType, ReplyType >::Replier	(	const ReplierParams &	params,
		Listener *	the_listener
	)

inline

Creates a replier with additional parameters and a listener.

[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener> instead of a regular Listener* pointer.

Parameters

params	All the parameters that configure this Replier
the_listener	A ReplierListener that notifies when new requests are available. Cannot be NULL.

Note: The listener must be reset with this->listener(NULL) before this object can be destroyed. Alternatively, create the Replier and then use rti::core::bind_listener() to have it automatically reset.

◆ Replier() [4/4]

template<typename RequestType, typename ReplyType>

rti::request::Replier< RequestType, ReplyType >::Replier	(	const ReplierParams &	params,
		std::shared_ptr< Listener >	the_listener
	)

inline

Creates a replier with additional parameters and a listener.

Parameters

params	All the parameters that configure this Replier
the_listener	A ReplierListener that notifies when new requests are available. Cannot be nullptr, but the parameter can be omitted.

References rti::request::Replier< RequestType, ReplyType >::Replier().

Member Function Documentation

◆ send_reply() [1/3]

template<typename RequestType, typename ReplyType>

void rti::request::Replier< RequestType, ReplyType >::send_reply	(	const ReplyType &	reply,
		const rti::core::SampleIdentity &	related_request_id
	)

inline

Sends a reply for a previous request.

The related request identity can be retrieved from an existing request sample (Sample).

Parameters

reply	The reply to be sent.
related_request_id	The identity of a previously received request

Exceptions

One	of the Standard Exceptions

See also: Sample::identity; rti::request::Replier::receive_requests; rti::request::Replier::take_requests; Basic Replier example

◆ send_reply() [2/3]

template<typename RequestType, typename ReplyType>

void rti::request::Replier< RequestType, ReplyType >::send_reply	(	const ReplyType &	reply,
		const dds::sub::SampleInfo &	related_request_info
	)

inline

Sends a reply.

This operation obtains the related_request_id from a request SampleInfo, that is, it's equivalent to send_reply(reply, related_request_info->original_publication_virtual_sample_identity())

References dds::sub::SampleInfo::original_publication_virtual_sample_identity().

◆ send_reply() [3/3]

template<typename RequestType, typename ReplyType>

void rti::request::Replier< RequestType, ReplyType >::send_reply	(	const ReplyType &	reply,
		rti::pub::WriteParams &	params
	)

inline

Sends a reply with advanced parameters.

Parameters

reply	The reply to be sent
params	(in-out) The parameters to write the reply (see ).

Precondition: params.related_sample_identity() must be set with the related request SampleIdentity.

Other parameters to customize are discussed in dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&). In particular, rti::pub::WriteParams::flag can be set to rti::core::SampleFlag::intermediate_reply_sequence to inform the Requester application that this reply will be followed by additional replies to the same request. The Requester can access the flag in dds::sub::SampleInfo::flag() when it receives the reply.

◆ wait_for_requests() [1/2]

template<typename RequestType, typename ReplyType>

bool rti::request::Replier< RequestType, ReplyType >::wait_for_requests ( const dds::core::Duration & max_wait )

inline

Waits for requests.

Equivalent to rti::request::Replier::wait_for_requests with min_count=1

See also: rti::request::Replier::wait_for_requests

◆ wait_for_requests() [2/2]

template<typename RequestType, typename ReplyType>

bool rti::request::Replier< RequestType, ReplyType >::wait_for_requests	(	int	min_count,
		const dds::core::Duration &	max_wait
	)

inline

Waits for requests.

This operation waits for min_count requests to be available. It will wait up to max_wait .

This operation is similar to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&).

Parameters

min_count	Minimum number of requests that need to be available for this operation to unblock.
max_wait	Maximum waiting time after which this operation unblocks regardless of how many requests are available.

Returns: true if at least min_count requests were available before max_wait elapsed, or false otherwise.

See also: rti::request::Replier::take_requests; rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

◆ receive_requests() [1/2]

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::receive_requests ( const dds::core::Duration & max_wait )

inline

Waits for multiple requests and provides a loaned container to access them.

Equivalent to using rti::request::Replier::receive_requests with min_count=1 and max_count=dds::core::LENGTH_UNLIMITED

See also: dds::sub::LoanedSamples; rti::request::Replier::receive_requests

◆ receive_requests() [2/2]

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::receive_requests	(	int	min_count,
		const dds::core::Duration &	max_wait
	)

inline

Waits for multiple requests and provides a loaned container to access them.

Equivalent to using rti::request::Replier::wait_for_requests and rti::request::Replier::take_requests

See also: dds::sub::LoanedSamples; rti::request::Replier::wait_for_requests; rti::request::Replier::take_requests

◆ take_requests()

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::take_requests ( )

inline

Takes all the requests.

See also: rti::request::Requester::take_replies

◆ read_requests()

template<typename RequestType, typename ReplyType>

dds::sub::LoanedSamples<RequestType> rti::request::Replier< RequestType, ReplyType >::read_requests ( )

inline

Reads all the requests.

This operation is equivalent to rti::request::Replier::take_requests except the requests remain in the Replier and can be read or taken again.

◆ listener() [1/2]

template<typename RequestType, typename ReplyType>

Listener* rti::request::Replier< RequestType, ReplyType >::listener ( ) const

inline

Gets the replier listener.

[DEPRECATED] Prefer get_listener() instead of this function.

Referenced by rti::request::Replier< RequestType, ReplyType >::reply_datawriter().

◆ listener() [2/2]

template<typename RequestType, typename ReplyType>

void rti::request::Replier< RequestType, ReplyType >::listener	(	Listener *	the_listener,
		const dds::core::status::StatusMask &	= `dds::core::status::StatusMask::none()`
	)

inline

Sets a listener to be notified when requests are available.

[DEPRECATED] The use of set_listener() is recommended. Unlike this function, set_listener receives a shared_ptr which simplifies the management of listener's lifecycle.

The listener will be called when new requests are available.

Note: rti::core::bind_listener() is recommended instead of this listener setter. bind_listener() and bind_and_manage_listener() automatically remove the listener, which allows the Replier to be automatically destroyed.

(The second parameter is ignored)

◆ get_listener()

template<typename RequestType, typename ReplyType>

std::shared_ptr<Listener> rti::request::Replier< RequestType, ReplyType >::get_listener ( ) const

inline

Gets the replier listener.

The listener will be called when new requests are available

◆ set_listener()

template<typename RequestType, typename ReplyType>

void rti::request::Replier< RequestType, ReplyType >::set_listener ( std::shared_ptr< Listener > the_listener )

inline

Sets a listener to be notified when requests are available.

Warning: It's recommended that the listener implementation doesn't hold a permanent reference to the replier. If it does, the application needs to manually reset the listener (set_listener(nullptr)) to ensure that there is no cycle that prevents the destruction of these two objects.

Parameters

the_listener A shared pointer to the listener to receive updates or nullptr to reset the current listener and stop receiving updates.

◆ request_datareader()

template<typename RequestType, typename ReplyType>

dds::sub::DataReader<RequestType> rti::request::Replier< RequestType, ReplyType >::request_datareader ( ) const

inline

Retrieves the underlying dds::sub::DataReader.

See also: rti::request::Requester::get_reply_datareader

Referenced by rti::request::Replier< RequestType, ReplyType >::reply_datawriter().

◆ reply_datawriter()

template<typename RequestType, typename ReplyType>

dds::pub::DataWriter<ReplyType> rti::request::Replier< RequestType, ReplyType >::reply_datawriter ( ) const

inline

Retrieves the underlying dds::pub::DataWriter.

See also: rti::request::Requester::get_request_datawriter

References rti::request::Replier< RequestType, ReplyType >::listener(), rti::request::ReplierListener< RequestType, ReplyType >::on_request_available(), rti::request::Replier< RequestType, ReplyType >::reply_datawriter(), and rti::request::Replier< RequestType, ReplyType >::request_datareader().

Referenced by rti::request::Replier< RequestType, ReplyType >::reply_datawriter().

Public Member Functions

Detailed Description

template<typename RequestType, typename ReplyType> class rti::request::Replier< RequestType, ReplyType >

Constructor & Destructor Documentation

◆ Replier() [1/4]

◆ Replier() [2/4]

◆ Replier() [3/4]

◆ Replier() [4/4]

Member Function Documentation

◆ send_reply() [1/3]

◆ send_reply() [2/3]

◆ send_reply() [3/3]

◆ wait_for_requests() [1/2]

◆ wait_for_requests() [2/2]

◆ receive_requests() [1/2]

◆ receive_requests() [2/2]

◆ take_requests()

◆ read_requests()

◆ listener() [1/2]

◆ listener() [2/2]

◆ get_listener()

◆ set_listener()

◆ request_datareader()

◆ reply_datawriter()

template<typename RequestType, typename ReplyType>
class rti::request::Replier< RequestType, ReplyType >