RTI Connext Modern C++ API  Version 6.0.1
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::queuing::QueueRequester< TReq, TRep > Class Template Reference

Allows sending requests and receiving replies. More...

#include <rti/queuing/QueueRequester.hpp>

Inheritance diagram for rti::queuing::QueueRequester< TReq, TRep >:
dds::core::Reference< detail::QueueRequesterImpl< TReq, TRep > >

Public Member Functions

 QueueRequester (const QueueRequesterParams &params, bool is_enabled=true, Listener *requester_listener=NULL, const rti::core::Guid &requester_guid=rti::core::Guid::unknown())
 Creates a QueueRequester with parameters.
 
void listener (Listener *the_listener, const dds::core::status::StatusMask &event_mask=dds::core::status::StatusMask::none())
 Sets the listener associated with this queue requester.
 
Listenerlistener () const
 Returns the listener currently associated with this requester.
 
void enable ()
 Enables the QueueRequester to send data, receive data and receive listener notifications.
 
dds::sub::LoanedSamples< TRep > receive_replies (const dds::core::Duration &max_wait)
 Waits for multiple replies and provides a loaned container to access them.
 
dds::sub::LoanedSamples< TRep > receive_replies (int min_count, int max_count, const dds::core::Duration &max_wait)
 Waits for multiple replies and provides a loaned container to access them.
 
dds::sub::LoanedSamples< TRep > take_replies ()
 Provides a loaned container from which you can access the existing replies.
 
dds::sub::LoanedSamples< TRep > take_replies (int max_count)
 Provides a loaned container from which you can access the existing replies.
 
dds::sub::LoanedSamples< TRep > read_replies ()
 Provides a loaned container from which you can access the existing replies.
 
dds::sub::LoanedSamples< TRep > read_replies (int max_count)
 Provides a loaned container from which you can access the existing replies for a specific request.
 
dds::sub::LoanedSamples< TRep > take_replies (int max_count, const rti::core::SampleIdentity &related_request_id)
 Provides a loaned container to access the existing replies for a specific request.
 
dds::sub::LoanedSamples< TRep > take_replies (const rti::core::SampleIdentity &related_request_id)
 Provides a loaned container from which you can access the existing replies for a specific request.
 
dds::sub::LoanedSamples< TRep > read_replies (const rti::core::SampleIdentity &related_request_id)
 Provides a loaned container from which you can access the existing replies for a specific request.
 
void send_request (const TReq &request)
 Sends a request.
 
void send_request (const TReq &request, rti::pub::WriteParams &write_params)
 Sends a request with the specified parameters and gets back metadata information related to the request sent.
 
void acknowledge_reply (const dds::sub::SampleInfo &sample_info, bool is_positive_acknowledgment=true)
 Explicitly acknowledges a single reply.
 
void acknowledge_all (bool is_positive_acknowledgment=true)
 Acknowledges all previously accessed replies.
 
bool wait_for_acknowledgments (const dds::core::Duration &max_wait)
 Blocks the calling thread until all requests written by this QueueRequester are acknowledged Queuing Service, or until a timeout occurs.
 
bool wait_for_acknowledgments (const rti::core::SampleIdentity &identity, const dds::core::Duration &max_wait)
 Blocks the calling thread until the request identified by identity is acknowledged by Queuing Service, or until a timeout occurs.
 
rti::queuing::QueueConsumer< TRep > consumer () const
 Retrieves the underlying QueueConsumer.
 
rti::queuing::QueueProducer< TReq > producer () const
 Retrieves the underlying QueueProducer.
 
bool wait_for_replies (const dds::core::Duration &max_wait)
 Waits for replies to any request.
 
bool wait_for_replies (int min_count, const dds::core::Duration &max_wait)
 Waits for replies to any request.
 
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.
 
void send_availability (ConsumerAvailabilityParams parameters)
 Sends the availability status of the QueueConsumer receiving samples from the reply SharedReaderQueue to Queuing Service.
 
bool has_matching_request_reader_queue ()
 Checks whether this QueueRequester has matched with at least one request SharedReaderQueue.
 
bool has_matching_reply_reader_queue ()
 Checks whether this QueueRequester has matched with at least one reply SharedReaderQueue.
 
dds::pub::DataWriter< TReq > writer () const
 Retrieves the underlying dds::pub::DataWriter used to send requests.
 
dds::sub::DataReader< TRep > reader () const
 Retrieves the underlying dds::sub::DataReader used to receive replies.
 
rti::core::Guid guid ()
 Returns the GUID of this QueueRequester.
 

Detailed Description

template<typename TReq, typename TRep>
class rti::queuing::QueueRequester< TReq, TRep >

Allows sending requests and receiving replies.

A QueueRequester is a component suited for the queuing request-reply use case. A QueueRequester plays the role of a request QueueProducer and reply QueueConsumer.

A QueueRequester is the entity that allows sending requests to a a request SharedReaderQueue and receiving replies from a reply SharedReaderQueue.

To communicate with the SharedReaderQueues the QueueRequester creates two topics. The first topic corresponds to the request SharedReaderQueue topic and the second topic to the reply SharedReaderQueue topic.

Valid types for these topics (TReq and TRep) are: those generated by the rtiddsgen code generator, the DDS built-in types, and dds::core::xtypes::DynamicData.

See Also
QueueProducer
QueueConsumer
Template Parameters
TReqThe data type for the request SharedReaderQueue topic
TRepThe data type for the reply SharedReaderQueue topic

Constructor & Destructor Documentation

template<typename TReq , typename TRep >
rti::queuing::QueueRequester< TReq, TRep >::QueueRequester ( const QueueRequesterParams params,
bool  is_enabled = true,
Listener requester_listener = NULL,
const rti::core::Guid requester_guid = rti::core::Guid::unknown() 
)
inlineexplicit

Creates a QueueRequester with parameters.

Parameters
paramsAll the parameters that configure this QueueRequester. See QueueRequesterParams for the list of mandatory parameters.
is_enabledSpecifies if the QueueRequester is created ready to receive notifications in its listener and send or receive data. If you choose to bind the QueueRequester to a QueueRequesterListener using an rti::core::ListenerBinder you should create the QueueRequester disabled to avoid missing listener notifications. You can later enable the disabled QueueRequester using QueueRequester::enable.
requester_listenerA pointer to a QueueRequesterListener object to receive event notifications. If you provide the listener at construction time you should also detach the listener before the QueueRequester is deleted. The QueueRequester is not automatically deleted until the listener is set to NULL. If you want the detachment of the listener to be automatically managed set requester_listener = NULL and use an rti::core::ListenerBinder instead.
requester_guidA GUID identifier for the requester. When requester_guid is set to rti::core::Guid::unknown() the Guid identifier is generated automatically. You can retrieve the generated QueueRequester Guid using the QueueRequester::guid() method. To restart a QueueRequester just create a new one with its same GUID.
Exceptions
Oneof the Standard Exceptions
See Also
QueueRequesterParams

Member Function Documentation

template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::listener ( Listener the_listener,
const dds::core::status::StatusMask event_mask = dds::core::status::StatusMask::none() 
)
inline

Sets the listener associated with this queue requester.

Parameters
the_listenerThe QueueRequesterListener to set
event_maskThe dds::core::status::StatusMask associated with the listener
template<typename TReq , typename TRep >
Listener* rti::queuing::QueueRequester< TReq, TRep >::listener ( ) const
inline

Returns the listener currently associated with this requester.

If there is no listener it returns NULL.

template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::enable ( )
inline

Enables the QueueRequester to send data, receive data and receive listener notifications.

If you create the QueueRequester disabled you can enable it using this mehtod. To avoid missing listener notifciation when you use an rti::core::ListenerBinder to bind the QueueRequester to a QueueRequesterListener use QueueRequester::enable to enable the QueueRequester after it is bound to the listener.

template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::receive_replies ( const dds::core::Duration max_wait)
inline
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::receive_replies ( int  min_count,
int  max_count,
const dds::core::Duration max_wait 
)
inline
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::take_replies ( )
inline

Provides a loaned container from which you can access the existing replies.

See Also
QueueConsumer::take_samples()
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::take_replies ( int  max_count)
inline

Provides a loaned container from which you can access the existing replies.

See Also
QueueConsumer::take_samples(int)
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::read_replies ( )
inline

Provides a loaned container from which you can access the existing replies.

This operation is equivalent to QueueRequester::take_replies(), except the sample remains in the QueueRequester and can be read or taken again.

template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::read_replies ( int  max_count)
inline

Provides a loaned container from which you can access the existing replies for a specific request.

This operation is equivalent to QueueRequester::take_replies(int, const rti::core::SampleIdentity&), except the sample remains in the QueueRequester and can be read or taken again.

template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::take_replies ( int  max_count,
const rti::core::SampleIdentity related_request_id 
)
inline

Provides a loaned container to access the existing replies for a specific request.

This operation is analogous to QueueRequester::take_replies(int), except the replies this operation provides correspond to a specific request.

Parameters
max_countThe maximum number of samples that are taken at a time. The special value dds::core::LENGTH_UNLIMITED may be used.
related_request_idThe identity of a request previously sent by this QueueRequester
MT Safety:
SAFE
See Also
QueueRequester::take_replies(int)
dds::sub::LoanedSamples
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::take_replies ( const rti::core::SampleIdentity related_request_id)
inline

Provides a loaned container from which you can access the existing replies for a specific request.

This operation is equivalent to using QueueRequester::take_replies(int, const rti::core::SampleIdentity&) with max_count=dds::core::LENGTH_UNLIMITED

MT Safety:
SAFE
See Also
dds::sub::LoanedSamples
QueueRequester::take_replies(int, const rti::core::SampleIdentity&)
template<typename TReq , typename TRep >
dds::sub::LoanedSamples<TRep> rti::queuing::QueueRequester< TReq, TRep >::read_replies ( const rti::core::SampleIdentity related_request_id)
inline

Provides a loaned container from which you can access the existing replies for a specific request.

This operation is equivalent to QueueRequester::take_replies(int, const rti::core::SampleIdentity&), except the sample remains in the QueueRequester and can be read or taken again.

template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::send_request ( const TReq &  request)
inline

Sends a request.

. If a future reply needs to be correlated to exactly this request, use QueueRequester::send_request_w_writesample.

Parameters
requestThe request to be sent
Exceptions
Oneof the Standard Exceptions
MT Safety:
SAFE
See Also
QueueProducer::send_sample(const T&, rti::pub::WriteParams&)
template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::send_request ( const TReq &  request,
rti::pub::WriteParams write_params 
)
inline

Sends a request with the specified parameters and gets back metadata information related to the request sent.

After calling this operation, write_params contains valid metadata information associated with the request sent.

The metadata field rti::pub::WriteParams::source_guid of the write_params in the request is always set to this QueueProducer's GUID.

Parameters
request<<in>> the request sample to send.
write_params<<inout>> Parameters used to send the request. When this call ends successfully, write_params contains valid metadata information associated with the request sent.
Exceptions
Oneof the Standard Exceptions or NoMatchingQueueException if by the time this operation is called there is not a single matching SharedReaderQueue.
MT Safety:
SAFE
See Also
QueueProducer::send_sample(const T&)
QueueProducer::send_sample(const T&, rti::pub::WriteParams&)
QueueRequester::wait_for_replies(int, const dds::core::Duration&, const rti::core::SampleIdentity&)
QueueRequester::take_replies(int, const rti::core::SampleIdentity&)
QueueRequester::take_replies(const rti::core::SampleIdentity&)
template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::acknowledge_reply ( const dds::sub::SampleInfo sample_info,
bool  is_positive_acknowledgment = true 
)
inline
template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::acknowledge_all ( bool  is_positive_acknowledgment = true)
inline
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::wait_for_acknowledgments ( const dds::core::Duration max_wait)
inline

Blocks the calling thread until all requests written by this QueueRequester are acknowledged Queuing Service, or until a timeout occurs.

See Also
QueueProducer::wait_for_acknowledgments(const dds::core::Duration&)
QueueRequester::send_request(const TReq&)
QueueRequesterListener::on_request_acknowledged
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::wait_for_acknowledgments ( const rti::core::SampleIdentity identity,
const dds::core::Duration max_wait 
)
inline

Blocks the calling thread until the request identified by identity is acknowledged by Queuing Service, or until a timeout occurs.

See Also
QueueProducer::wait_for_acknowledgments(const rti::core::SampleIdentity&, const dds::core::Duration&)
QueueRequester::send_request(const TReq&)
QueueRequesterListener::on_request_acknowledged
template<typename TReq , typename TRep >
rti::queuing::QueueConsumer<TRep> rti::queuing::QueueRequester< TReq, TRep >::consumer ( ) const
inline

Retrieves the underlying QueueConsumer.

template<typename TReq , typename TRep >
rti::queuing::QueueProducer<TReq> rti::queuing::QueueRequester< TReq, TRep >::producer ( ) const
inline

Retrieves the underlying QueueProducer.

template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::wait_for_replies ( const dds::core::Duration max_wait)
inline

Waits for replies to any request.

See Also
QueueConsumer::wait_for_samples(int, const dds::core::Duration&)
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::wait_for_replies ( int  min_count,
const dds::core::Duration max_wait 
)
inline

Waits for replies to any request.

See Also
QueueConsumer::wait_for_samples(int, const dds::core::Duration&)
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::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 QueueRequester::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 QueueRequester
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
QueueRequester::wait_for_replies(int, const dds::core::Duration&)
template<typename TReq , typename TRep >
void rti::queuing::QueueRequester< TReq, TRep >::send_availability ( ConsumerAvailabilityParams  parameters)
inline

Sends the availability status of the QueueConsumer receiving samples from the reply SharedReaderQueue to Queuing Service.

See Also
QueueConsumer::send_availability(ConsumerAvailabilityParams)
QueueRequesterParams::enable_availability
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::has_matching_request_reader_queue ( )
inline

Checks whether this QueueRequester has matched with at least one request SharedReaderQueue.

See Also
QueueProducer::has_matching_reader_queue()
template<typename TReq , typename TRep >
bool rti::queuing::QueueRequester< TReq, TRep >::has_matching_reply_reader_queue ( )
inline

Checks whether this QueueRequester has matched with at least one reply SharedReaderQueue.

See Also
QueueConsumer::has_matching_reader_queue()
template<typename TReq , typename TRep >
dds::pub::DataWriter<TReq> rti::queuing::QueueRequester< TReq, TRep >::writer ( ) const
inline

Retrieves the underlying dds::pub::DataWriter used to send requests.

See Also
QueueProducer::writer()
template<typename TReq , typename TRep >
dds::sub::DataReader<TRep> rti::queuing::QueueRequester< TReq, TRep >::reader ( ) const
inline

Retrieves the underlying dds::sub::DataReader used to receive replies.

See Also
QueueConsumer::reader
template<typename TReq , typename TRep >
rti::core::Guid rti::queuing::QueueRequester< TReq, TRep >::guid ( )
inline

Returns the GUID of this QueueRequester.

The QueueRequester's GUID is the same GUID of both the underlying QueueProducer and QueueConsumer.

The GUID of the QueueRequester is also used by Queuing Service to correlate the replies the QueueRequester produces. Replies are only delivered to the QueueRequester that generated the related request.

See Also
QueueRequesterParams::entity_name
QueueProducer::guid
QueueConsumer::guid

RTI Connext Modern C++ API Version 6.0.1 Copyright © Sat Nov 23 2019 Real-Time Innovations, Inc