RTI Connext Modern C++ API  Version 6.1.0
rti::request::Requester< RequestType, ReplyType > Class Template Reference

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

#include <rti/request/Requester.hpp>

Inheritance diagram for rti::request::Requester< RequestType, ReplyType >:
dds::core::Reference< detail::RequesterImpl< RequestType, ReplyType > >

Public Member Functions

 Requester (const RequesterParams &params)
 Creates a Requester with parameters. More...
 
 Requester (dds::domain::DomainParticipant participant, const std::string &service_name)
 Creates a Requester with the minimum set of parameters. More...
 
rti::core::SampleIdentity send_request (const RequestType &request)
 Sends a request. More...
 
void send_request (const RequestType &request, rti::pub::WriteParams &params)
 Sends a request with advanced parameters. More...
 
dds::sub::LoanedSamples< ReplyType > receive_replies (const dds::core::Duration &max_wait)
 Waits for multiple replies and provides a loaned container to access them. More...
 
dds::sub::LoanedSamples< ReplyType > receive_replies (int min_count, const dds::core::Duration &max_wait)
 Waits for multiple replies and provides a loaned container to access them. More...
 
dds::sub::LoanedSamples< ReplyType > take_replies ()
 Takes all the replies. More...
 
dds::sub::LoanedSamples< ReplyType > take_replies (const rti::core::SampleIdentity &related_request_id)
 Takes the replies for a specific requests. More...
 
dds::sub::LoanedSamples< ReplyType > read_replies ()
 Reads all the replies. More...
 
dds::sub::LoanedSamples< ReplyType > read_replies (const rti::core::SampleIdentity &related_request_id)
 Reads the replies for a specific request. More...
 
bool wait_for_replies (const dds::core::Duration &max_wait)
 Waits for replies to any request. More...
 
bool wait_for_replies (int min_count, const dds::core::Duration &max_wait)
 Waits for replies to any request. More...
 
bool wait_for_replies (int min_count, const dds::core::Duration &max_wait, const rti::core::SampleIdentity &related_request_id)
 Waits for replies to a specific request. More...
 
dds::pub::DataWriter< RequestType > request_datawriter () const
 Retrieves the underlying dds::pub::DataWriter. More...
 
dds::sub::DataReader< ReplyType > reply_datareader () const
 Retrieves the underlying dds::sub::DataReader. More...
 

Detailed Description

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

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

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

A requester is an entity with two associated topics: a request topic and a reply topic. It can send requests by publishing samples of the request topic and receive replies to those requests by subscribing to 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.

A Replier and a Requester communicate when they use the same topics for requests and replies (see RequesterParams::service_name) on the same domain ID.

A Requester can send requests and receive one or multiple replies. It does that using the following operations:

  • Sending requests (i.e. publishing request samples on the request topic)
  • Waiting for replies to be received by the middleware (for any request or for a specific request)
  • Getting those replies from the middleware. There are two ways to do this: take (the data samples are removed from the middleware), read (the data samples remain in the middleware and can be read or taken again).
  • A convenience operation, receive (which is a combination of wait and take).

In all cases, the middleware guarantees that a requester only receives reply samples that are associated with those requests that it sends.

For multi-reply scenarios, in which a Requester receives multiple replies from a Replier for a given request, the Requester can check if a reply is the last reply of a sequence of replies. To do so, see if the bit rti::core::SampleFlag::intermediate_reply_sequence is set in dds::sub::SampleInfo::flag after receiving each reply. This indicates it is NOT the last reply.

A requester has an associated dds::domain::DomainParticipant, which can be shared with other requesters or RTI Connext routines. All the other RTI Connext entities required for the request-reply interaction, including a dds::pub::DataWriter for writing requests and a dds::sub::DataReader for reading replies, are automatically created when the requester 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

Template Parameters
RequestTypeThe data type for the request topic
ReplyTypeThe data type for the reply topic
See also
rti::request::Replier
Request-Reply Examples
Basic Requester example

Constructor & Destructor Documentation

◆ Requester() [1/2]

template<typename RequestType, typename ReplyType>
rti::request::Requester< RequestType, ReplyType >::Requester ( const RequesterParams params)
inlineexplicit

Creates a Requester with parameters.

Parameters
paramsAll the parameters that configure this requester. See RequesterParams for the list of mandatory parameters.
Exceptions
Oneof the Standard Exceptions
See also
RequesterParams
Requester Creation

◆ Requester() [2/2]

template<typename RequestType, typename ReplyType>
rti::request::Requester< RequestType, ReplyType >::Requester ( dds::domain::DomainParticipant  participant,
const std::string &  service_name 
)
inline

Creates a Requester with the minimum set of parameters.

Parameters
participantThe DomainParticipant this requester uses to join a DDS domain
service_nameThe service name. See RequesterParams::service_name
Exceptions
Oneof the Standard Exceptions

Member Function Documentation

◆ send_request() [1/2]

template<typename RequestType, typename ReplyType>
rti::core::SampleIdentity rti::request::Requester< RequestType, ReplyType >::send_request ( const RequestType &  request)
inline

Sends a request.

Parameters
requestThe request to be sent
Returns
The identity of the request, which can be used to correlate it with a future reply (see rti::request::Requester::wait_for_replies(int, const dds::core::Duration&, const rti::core::SampleIdentity&))

◆ send_request() [2/2]

template<typename RequestType, typename ReplyType>
void rti::request::Requester< RequestType, ReplyType >::send_request ( const RequestType &  request,
rti::pub::WriteParams params 
)
inline

Sends a request with advanced parameters.

Parameters
requestThe request to be sent
params(in-out) The parameters to write the request (see dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&))

This function allows setting the request identity in params.identity(), among other advanced parameters. If the identity is not set, RTI Connext automatically assigns it, and to obtain it params.replace_automatic_values() needs to be set to true. Then, after this function ends, params.identity() will contain the request identity. If no additional parameters need to be set, use the simpler send_request(const RequestType&), which directly returns the automatically assigned identity.

◆ receive_replies() [1/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::receive_replies ( const dds::core::Duration max_wait)
inline

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

This operation is equivalent to using rti::request::Requester::receive_replies with min_count=1 and max_count=dds::core::LENGTH_UNLIMITED

MT Safety:
See rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)
See also
dds::sub::LoanedSamples
rti::request::Requester::receive_replies

◆ receive_replies() [2/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::receive_replies ( int  min_count,
const dds::core::Duration max_wait 
)
inline

◆ take_replies() [1/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::take_replies ( )
inline

Takes all the replies.

Takes all the existing replies up to max_count and provides a loaned container to access them.

This operation does not make a copy of the data. It is similar to dds::sub::DataReader::take.

The loan is returned with dds::sub::LoanedSamples::return_loan or in the destructor

This operation may be used after a call to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

Returns
A container with up to max_count elements. May be empty if there were no replies to get.
Exceptions
Oneof the Standard Exceptions
MT Safety:
SAFE
See also
dds::sub::LoanedSamples
dds::sub::LoanedSamples::return_loan
rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)
dds::sub::DataReader::take (for a more detailed description on how QoS and other parameters affect the underlying DataReader)

◆ take_replies() [2/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::take_replies ( const rti::core::SampleIdentity related_request_id)
inline

Takes the replies for a specific requests.

This operation is operation is analogous to take_replies() but it only returns those replies associated with a specific request.

Parameters
related_request_idIdentifies a request previously sent by this Requester's send_request().

◆ read_replies() [1/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::read_replies ( )
inline

Reads all the replies.

This operation is equivalent to rti::request::Requester::take_replies except the replies remain in the Requester and can be read or taken again.

◆ read_replies() [2/2]

template<typename RequestType, typename ReplyType>
dds::sub::LoanedSamples<ReplyType> rti::request::Requester< RequestType, ReplyType >::read_replies ( const rti::core::SampleIdentity related_request_id)
inline

Reads the replies for a specific request.

This operation is equivalent to take_replies(const rti::core::SampleIdentity&), except the replies remain in the Requester and can be read or taken again.

◆ wait_for_replies() [1/3]

template<typename RequestType, typename ReplyType>
bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies ( const dds::core::Duration max_wait)
inline

Waits for replies to any request.

This operation is equivalent to using rti::request::Requester::wait_for_replies(int, const dds::core::Duration&) with min_count=1.

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

◆ wait_for_replies() [2/3]

template<typename RequestType, typename ReplyType>
bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies ( int  min_count,
const dds::core::Duration max_wait 
)
inline

Waits for replies to any request.

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

If this operation is called several times but the available replies are not taken (with rti::request::Requester::take_replies), this operation may return immediately and will not wait for new replies. New replies may replace existing ones if they are not taken, depending on the dds::core::policy::History used to configure this Requester.

Parameters
min_countMinimum number of replies that need to be available for this operation to unblock.
max_waitMaximum waiting time after which this operation unblocks, regardless of how many replies are available.
Returns
true if at least minCount replies were available before maxWait elapsed, or false otherwise.
MT Safety:
Concurrent calls to this operation on the same object are not allowed. However, waiting for replies for specific requests in parallel is supported (see rti::request::Requester::wait_for_replies(int, const dds::core::Duration&, const rti::core::SampleIdentity&)).
See also
rti::request::Requester::take_replies

◆ wait_for_replies() [3/3]

template<typename RequestType, typename ReplyType>
bool rti::request::Requester< RequestType, ReplyType >::wait_for_replies ( int  min_count,
const dds::core::Duration max_wait,
const rti::core::SampleIdentity related_request_id 
)
inline

Waits for replies to a specific request.

This operation is analogous to rti::request::Requester::wait_for_replies(int, const dds::core::Duration&) except this operation waits for replies for a specific request.

Parameters
min_countMinimum number of replies for the related request that need to be available for this operation to unblock.
max_waitMaximum wait time after which this operation unblocks, regardless of how many replies are available.
related_request_idThe identity of a request previously sent by this Requester
Returns
true if at least min_count replies for the related request were available before max_wait elapsed, or false otherwise.
Exceptions
Oneof the Standard Exceptions
MT Safety:
SAFE
See also
rti::request::Requester::wait_for_replies(int, const dds::core::Duration&)

◆ request_datawriter()

template<typename RequestType, typename ReplyType>
dds::pub::DataWriter<RequestType> rti::request::Requester< RequestType, ReplyType >::request_datawriter ( ) const
inline

Retrieves the underlying dds::pub::DataWriter.

Accessing the request DataWriter may be useful for a number of advanced use cases, such as:

  • Finding matching subscriptions (e.g., Repliers)
  • Setting a DataWriter listener
  • Getting DataWriter protocol or cache statuses
MT Safety:
SAFE
See also
dds::pub::DataWriter
dds::pub::DataWriter
dds::pub::matched_subscriptions()
dds::pub::matched_subscription_data()
dds::pub::DataWriter::set_listener
dds::pub::DataWriter::datawriter_protocol_status()

Referenced by rti::request::Requester< Request, Reply >::reply_datareader().

◆ reply_datareader()

template<typename RequestType, typename ReplyType>
dds::sub::DataReader<ReplyType> rti::request::Requester< RequestType, ReplyType >::reply_datareader ( ) const
inline

Retrieves the underlying dds::sub::DataReader.

Accessing the reply DataReader may be useful for a number of advanced use cases, such as:

  • Finding matching publications (e.g., Repliers)
  • Setting a DataReader listener
  • Getting DataReader protocol or cache statuses
MT Safety:
SAFE
See also
dds::sub::DataReader
dds::sub::DataReader
dds::sub::matched_publications
dds::sub::DataReader::matched_publication_data
dds::sub::DataReader::set_listener
dds::sub::DataReader::datareader_protocol_status

Referenced by rti::request::Requester< Request, Reply >::reply_datareader().