Allows sending requests and receiving replies. More...

#include <rti/queuing/QueueRequester.hpp>

Inheritance diagram for rti::queuing::QueueRequester< 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 queue requester. More...

	QueueRequester (const QueueRequesterParams &params, bool is_enabled, std::shared_ptr< Listener > requester_listener, const rti::core::Guid &requester_guid=rti::core::Guid::unknown())
	Creates a QueueRequester with parameters. More...

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. More...

Listener *	listener () const
	Returns the listener currently associated with this requester. More...

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

void	set_listener (std::shared_ptr< Listener > the_listener)
	Sets a listener to be notified of status updates. More...

void	enable ()
	Enables the QueueRequester to send data, receive data and receive listener notifications. More...

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

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. More...

dds::sub::LoanedSamples< TRep >	take_replies ()
	Provides a loaned container from which you can access the existing replies. More...

dds::sub::LoanedSamples< TRep >	take_replies (int max_count)
	Provides a loaned container from which you can access the existing replies. More...

dds::sub::LoanedSamples< TRep >	read_replies ()
	Provides a loaned container from which you can access the existing replies. More...

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. More...

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. More...

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. More...

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. More...

void	send_request (const TReq &request)
	Sends a request. More...

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. More...

void	acknowledge_reply (const dds::sub::SampleInfo &sample_info, bool is_positive_acknowledgment=true)
	Explicitly acknowledges a single reply. More...

void	acknowledge_all (bool is_positive_acknowledgment=true)
	Acknowledges all previously accessed replies. More...

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. More...

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. More...

rti::queuing::QueueConsumer< TRep >	consumer () const
	Retrieves the underlying QueueConsumer. More...

rti::queuing::QueueProducer< TReq >	producer () const
	Retrieves the underlying QueueProducer. 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...

void	send_availability (ConsumerAvailabilityParams parameters)
	Sends the availability status of the QueueConsumer receiving samples from the reply SharedReaderQueue to Queuing Service. More...

bool	has_matching_request_reader_queue ()
	Checks whether this QueueRequester has matched with at least one request SharedReaderQueue. More...

bool	has_matching_reply_reader_queue ()
	Checks whether this QueueRequester has matched with at least one reply SharedReaderQueue. More...

dds::pub::DataWriter< TReq >	writer () const
	Retrieves the underlying dds::pub::DataWriter used to send requests. More...

dds::sub::DataReader< TRep >	reader () const
	Retrieves the underlying dds::sub::DataReader used to receive replies. More...

rti::core::Guid	guid ()
	Returns the GUID of this QueueRequester. More...

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 rtiddsgen, the DDS built-in types, and dds::core::xtypes::DynamicData.

See also: QueueProducer; QueueConsumer

Template Parameters

TReq	The data type for the request SharedReaderQueue topic
TRep	The data type for the reply SharedReaderQueue topic

Constructor & Destructor Documentation

◆ QueueRequester() [1/2]

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 queue requester.

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

◆ QueueRequester() [2/2]

template<typename TReq , typename TRep >

rti::queuing::QueueRequester< TReq, TRep >::QueueRequester	(	const QueueRequesterParams &	params,
		bool	is_enabled,
		std::shared_ptr< Listener >	requester_listener,
		const rti::core::Guid &	requester_guid = `rti::core::Guid::unknown()`
	)

inlineexplicit

Creates a QueueRequester with parameters.

Parameters

params	All the parameters that configure this QueueRequester. See QueueRequesterParams for the list of mandatory parameters.
is_enabled	Specifies 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_listener	A shared_ptr to a QueueRequesterListener object to receive event notifications.
requester_guid	A 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

One	of the Standard Exceptions

See also: QueueRequesterParams

Member Function Documentation

◆ listener() [1/2]

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.

[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.

Parameters

the_listener	The QueueRequesterListener to set
event_mask	The dds::core::status::StatusMask associated with the listener

◆ listener() [2/2]

template<typename TReq , typename TRep >

Listener * rti::queuing::QueueRequester< TReq, TRep >::listener ( ) const

inline

Returns the listener currently associated with this requester.

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

If there is no listener it returns NULL.

◆ get_listener()

template<typename TReq , typename TRep >

std::shared_ptr< Listener > rti::queuing::QueueRequester< TReq, TRep >::get_listener ( ) const

inline

Gets the listener.

◆ set_listener()

template<typename TReq , typename TRep >

void rti::queuing::QueueRequester< TReq, TRep >::set_listener ( std::shared_ptr< Listener > the_listener )

inline

Sets a listener to be notified of status updates.

Warning: It's recommended that the listener implementation doesn't hold a permanent reference to this object. If it does, the application needs to manually reset the listener or manually close this object 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.

◆ enable()

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.

◆ receive_replies() [1/2]

template<typename TReq , typename TRep >

dds::sub::LoanedSamples< TRep > rti::queuing::QueueRequester< TReq, TRep >::receive_replies ( const dds::core::Duration & max_wait )

inline

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

See also: QueueConsumer::receive_samples(const dds::core::Duration&); QueueRequester::wait_for_replies(int, const dds::core::Duration&); QueueRequester::take_replies(int)

◆ receive_replies() [2/2]

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

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

See also: QueueConsumer::receive_samples(int, int, const dds::core::Duration&); QueueRequester::wait_for_replies(int, const dds::core::Duration&); QueueRequester::take_replies(int)

◆ take_replies() [1/4]

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()

◆ take_replies() [2/4]

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)

◆ read_replies() [1/3]

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.

◆ read_replies() [2/3]

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.

◆ take_replies() [3/4]

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_count	The maximum number of samples that are taken at a time. The special value dds::core::LENGTH_UNLIMITED may be used.
related_request_id	The identity of a request previously sent by this QueueRequester

MT Safety:: SAFE

See also: QueueRequester::take_replies(int); dds::sub::LoanedSamples

◆ take_replies() [4/4]

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&)

◆ read_replies() [3/3]

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.

◆ send_request() [1/2]

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

request The request to be sent

Exceptions

One	of the Standard Exceptions

MT Safety:: SAFE

See also: QueueProducer::send_sample(const T&, rti::pub::WriteParams&)

◆ send_request() [2/2]

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

One	of 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&)

◆ acknowledge_reply()

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

Explicitly acknowledges a single reply.

See also: QueueConsumer::acknowledge_sample(const dds::sub::SampleInfo&, bool); QueueRequester::acknowledge_all(bool)

◆ acknowledge_all()

template<typename TReq , typename TRep >

void rti::queuing::QueueRequester< TReq, TRep >::acknowledge_all ( bool is_positive_acknowledgment = true )

inline

Acknowledges all previously accessed replies.

See also: QueueConsumer::acknowledge_all(bool); QueueRequester::acknowledge_reply(const dds::sub::SampleInfo&, bool)

◆ wait_for_acknowledgments() [1/2]

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

◆ wait_for_acknowledgments() [2/2]

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

◆ consumer()

template<typename TReq , typename TRep >

rti::queuing::QueueConsumer< TRep > rti::queuing::QueueRequester< TReq, TRep >::consumer ( ) const

inline

Retrieves the underlying QueueConsumer.

◆ producer()

template<typename TReq , typename TRep >

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

inline

Retrieves the underlying QueueProducer.

◆ wait_for_replies() [1/3]

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&)

◆ wait_for_replies() [2/3]

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&)

◆ wait_for_replies() [3/3]

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_count	Minimum number of replies for the related request that need to be available for this operation to unblock.
max_wait	Maximum wait time after which this operation unblocks, regardless of how many replies are available.
related_request_id	The 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

One	of the Standard Exceptions

MT Safety:: SAFE

See also: QueueRequester::wait_for_replies(int, const dds::core::Duration&)

◆ send_availability()

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

◆ has_matching_request_reader_queue()

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()

◆ has_matching_reply_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()

◆ writer()

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()

◆ reader()

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

◆ guid()

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QueueRequester() [1/2]

◆ QueueRequester() [2/2]

Member Function Documentation

◆ listener() [1/2]

◆ listener() [2/2]

◆ get_listener()

◆ set_listener()

◆ enable()

◆ receive_replies() [1/2]

◆ receive_replies() [2/2]

◆ take_replies() [1/4]

◆ take_replies() [2/4]

◆ read_replies() [1/3]

◆ read_replies() [2/3]

◆ take_replies() [3/4]

◆ take_replies() [4/4]

◆ read_replies() [3/3]

◆ send_request() [1/2]

◆ send_request() [2/2]

◆ acknowledge_reply()

◆ acknowledge_all()

◆ wait_for_acknowledgments() [1/2]

◆ wait_for_acknowledgments() [2/2]

◆ consumer()

◆ producer()

◆ wait_for_replies() [1/3]

◆ wait_for_replies() [2/3]

◆ wait_for_replies() [3/3]

◆ send_availability()

◆ has_matching_request_reader_queue()

◆ has_matching_reply_reader_queue()

◆ writer()

◆ reader()

◆ guid()