Allows you to send samples to a specific SharedReaderQueue hosted by Queuing Service. More...

#include <rti/queuing/QueueProducer.hpp>

Inherits dds::core::Reference< DELEGATE >.

Public Member Functions
	QueueProducer (const QueueProducerParams &params, bool is_enabled=true, Listener *producer_listener=NULL, const rti::core::Guid &producer_guid=rti::core::Guid::unknown())
	Creates a QueueProducer 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 producer.

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

void	enable ()
	Enables the QueueProducer to send data and receive listener notifications.

void	send_sample (const T &sample)
	Sends a sample.

void	send_sample (const T &sample, rti::pub::WriteParams &write_params)
	Sends a sample with the specified parameters and gets back metadata information related to the sample sent.

bool	wait_for_acknowledgments (const dds::core::Duration &max_wait)
	Blocks the calling thread until all samples written by this QueueProducer since the last call to this method are acknowledged by Queuing Service.

bool	wait_for_acknowledgments (const rti::core::SampleIdentity &identity, const dds::core::Duration &max_wait)
	Blocks the calling thread until the sample identified by identity is acknowledged by Queuing Service.

dds::pub::DataWriter< T >	writer () const
	Retrieves the underlying dds::pub::DataWriter.

rti::core::Guid	guid () const
	Returns the GUID of this QueueProducer.

bool	has_matching_reader_queue ()
	Checks whether this QueueProducer has matched with at least one SharedReaderQueue.

Public Member Functions inherited from dds::core::Reference< DELEGATE >
	Reference (dds::core::null_type &)

	Reference (const Reference &ref)

template<typename D >
	Reference (const Reference< D > &ref)

	~Reference ()

template<typename R >
bool	operator== (const R &ref) const

template<typename R >
bool	operator!= (const R &ref) const

Reference &	operator= (const null_type)

bool	is_nil () const

bool	operator== (const null_type) const

bool	operator!= (const null_type) const

const DELEGATE_REF_T &	delegate () const OMG_NOEXCEPT

DELEGATE_REF_T &	delegate () OMG_NOEXCEPT

DELEGATE *	operator-> () OMG_NOEXCEPT

const DELEGATE *	operator-> () const OMG_NOEXCEPT

Detailed Description

template<typename T>
class rti::queuing::QueueProducer< T >

Allows you to send samples to a specific SharedReaderQueue hosted by Queuing Service.

A QueueProducer is an entity that allows you to send samples to a SharedReaderQueue hosted by Queuing Service. A QueueProducer has one underlying dds::pub::DataWriter to communicate with a SharedReaderQueue.

Valid types for the topic of the DataWriter (T) are those generated by the rtiddsgen code generator , the DDS built-in types , and dds::core::xtypes::DynamicData.

To send samples to a SharedReaderQueue, a QueueProducer must set its topic name (see QueueProducerParams::queue_topic_name) equal to the SharedReaderQueue topic name.

The QueueProducer and the SharedReadeeQueue must also be in the same DDS domain (that is, they must have the same domain ID).

A QueueProducer has an associated dds::domain::DomainParticipant, which can be shared with other QueueProducers or RTI Connext routines. All the other RTI Connext entities required for queuing interaction, including a dds::pub::DataWriter for writing samples, are automatically created when the QueueProducer is constructed.

Quality of Service (QoS) for the underlying DataWriter is configurable (see QueueProducerParams::qos_profile and QueueProducerParams::datawriter_qos).

If no QoS is specified in the QueueProducerParams, the default DataWriterQos will be used.

A QueueProducer must always be reliable in order to match and communicate with the SharedReaderQueue. Hence, whichever DataWriterQos is selected, the following QoS setting is always overriden:

dds::core::policy::Reliability::kind is set to dds::core::policy::ReliabilityKind::RELIABLE.

The underlying DataWriter is created with an internal dds::pub::DataWriterListener, which is required to provide the behavior of a QueueProducer, including the notification of events via QueueProducerListener. For this reason, when accessing the underlying DataWriter, the listener should not be set, removed or modified; otherwise the behavior of the QueueProducer will be incorrect and unpredictable.

Template Parameters

T	The data type for the SharedReaderQueue topic

See Also: QueueProducer; QueueProducerListener

Constructor & Destructor Documentation

template<typename T>

rti::queuing::QueueProducer< T >::QueueProducer	(	const QueueProducerParams &	params,
		bool	is_enabled = `true`,
		Listener *	producer_listener = `NULL`,
		const rti::core::Guid &	producer_guid = `rti::core::Guid::unknown()`
	)

inlineexplicit

Creates a QueueProducer with parameters.

Parameters

params	All the parameters that configure this QueueProducer. See QueueProducerParams for the list of required parameters.
is_enabled	Specifies if the QueueProducer is created ready to receive notifications in its listener and send data. If you choose to bind the QueueProducer to a QueueProducerListener using an rti::core::ListenerBinder you should create the QueueProducer disabled to avoid missing listener notifications. You can later enable the disabled QueueProducer using QueueProducer::enable.
producer_listener	A pointer to a QueueProducerListener object to receive event notifications. If you provide the listener at construction time you should also detach the listener before the QueueProducer is deleted. The QueueProducer is not automatically deleted until the listener is set to NULL. If you want the detachment of the listener to be automatically managed set producer_listener = NULL and use an rti::core::ListenerBinder instead.
producer_guid	A GUID identifier for the producer. When producer_guid is set to rti::core::Guid::unknown() the Guid identifier is generated automatically. You can retrieve the generated QueueProducer Guid using the QueueProducer::guid method. To restart a QueueProducer just create a new one with its same GUID.

Exceptions

One	of the Standard Exceptions

See Also: QueueProducerParams

Member Function Documentation

template<typename T>

void rti::queuing::QueueProducer< T >::listener	(	Listener *	the_listener,
		const dds::core::status::StatusMask &	event_mask = `dds::core::status::StatusMask::none()`
	)

inline

Sets the listener associated with this producer.

Parameters

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

template<typename T>

Listener* rti::queuing::QueueProducer< T >::listener ( ) const

inline

Returns the listener currently associated with this Producer.

If there is no listener it returns NULL.

template<typename T>

void rti::queuing::QueueProducer< T >::enable ( )

inline

Enables the QueueProducer to send data and receive listener notifications.

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

template<typename T>

void rti::queuing::QueueProducer< T >::send_sample ( const T & sample )

inline

Sends a sample.

This operation is equivalent to calling QueueProducer::send_sample(const T&, rti::pub::WriteParams&) using a default rti::pub::WriteParams.

Parameters

sample The sample to be sent

Exceptions

One	of the Standard Exceptions or NoMatchingQueueException

MT Safety:: SAFE

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

template<typename T>

void rti::queuing::QueueProducer< T >::send_sample	(	const T &	sample,
		rti::pub::WriteParams &	write_params
	)

inline

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

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

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

Parameters

sample	<<in>> the sample to send.
write_params	<<inout>> Parameters to send the sample. When this call ends successfully, `write_params` contains valid metadata information associated with the sample 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&)

template<typename T>

bool rti::queuing::QueueProducer< T >::wait_for_acknowledgments ( const dds::core::Duration & max_wait )

inline

Blocks the calling thread until all samples written by this QueueProducer since the last call to this method are acknowledged by Queuing Service.

This operation will keep the calling thread blocked as long as there are samples pending on acknowledgement, unless a timeout occurs.

After unblocking, the return value is true if all samples have been acknowledged positively or false if at least one of them was acknowledged negatively.

If there is a timeout, this operation throws dds::core::TimeoutError.

This operation requires setting QueueProducerParams::enable_wait_for_ack to true. Otherwise, it will throw dds::core::PreconditionNotMetError.

When a SharedReaderQueue is not replicated, a sample is acknowledged positively once the running Queuing Service instance has enqueued the sample.

When a SharedReaderQueue is replicated, a sample is acknowledged positively once it has been enqueued by the Queuing Service instance acting as a master. This means that the sample has been received and enqueued by a configurable quorum of instances (using <replication_settings>/<queue_instances>).

This operation waits until all the previously written samples since the last call to this method are acknowledged. If you want to wait for a specific sample, use the method QueueProducer::wait_for_acknowledgments(const rti::core::SampleIdentity&, const dds::core::Duration&).

This operation cannot be called by two threads concurrently. If this occurs, the second thread will throw dds::core::PreconditionNotMetError.

This operation cannot be called concurrently with QueueProducer::wait_for_acknowledgments(const rti::core::SampleIdentity&, const dds::core::Duration&) either.

Parameters

max_wait <<in>> Maximum waiting time.

Returns: true if all the samples are acknowledged positively or false if there was at least one sample acknowledged negatively.

Exceptions

One	of the Standard Exceptions ; NoMatchingQueueException if during this call, the QueueProducer lost the matching status with Queuing Service. dds::core::TimeoutError if a timeout occurs before receiving all the acknowledgments.

template<typename T>

bool rti::queuing::QueueProducer< T >::wait_for_acknowledgments	(	const rti::core::SampleIdentity &	identity,
		const dds::core::Duration &	max_wait
	)

inline

Blocks the calling thread until the sample identified by identity is acknowledged by Queuing Service.

This operation blocks the calling thread until the sample identified by identity is acknowledged by Queuing Service or there is a timeout.

After unblocking, the return value is true if the sample has been acknowledged positively or false if the sample has been acknowledged negatively.

If there is a timeout, this operation throws dds::core::TimeoutError.

This operation requires setting QueueProducerParams::enable_wait_for_ack to true. Otherwise, it will throw dds::core::PreconditionNotMetError.

When a SharedReaderQueue is not replicated, a sample is acknowledged positively once the running Queuing Service instance has enqueued the sample.

When a SharedReaderQueue is replicated, a sample is acknowledged positively once it has been enqueued by the Queuing Service instance acting as a master. This means that the sample has been received and enqueued by a configurable quorum of instances (using <replication_settings>/<queue_instances>).

This operation cannot be called by two threads concurrently on the same identity. If this occurs, the second thread will throw dds::core::PreconditionNotMetError.

This operation cannot be called concurrently with QueueProducer::wait_for_acknowledgments(const dds::core::Duration&) either.

Parameters

max_wait	<<in>> Maximum waiting time.
identity	<<in>>. Sample identity.

Returns: true if the sample is acknowledged positively or false if the sample is acknowledged negatively.

Exceptions

One	of the Standard Exceptions ; NoMatchingQueueException if during this call, the QueueProducer lost the matching status with Queuing Service. dds::core::TimeoutError if a timeout occurs before receiving all the acknowledgments.

template<typename T>

dds::pub::DataWriter<T> rti::queuing::QueueProducer< T >::writer ( ) const

inline

Retrieves the underlying dds::pub::DataWriter.

Accessing the DataWriter may be useful for a number of advanced use cases, such as getting the DataWriter protocol or cache statuses.

MT Safety:: SAFE

See Also: dds::pub::DataWriter; dds::pub::DataWriter; dds::pub::DataWriter::datawriter_protocol_status()

template<typename T>

rti::core::Guid rti::queuing::QueueProducer< T >::guid ( ) const

inline

Returns the GUID of this QueueProducer.

The GUID of the QueueProducer is determined based on the value of QueueEntityParams::entity_name and QueueProducerParams::queue_topic_name. Note that the QueueProducer GUID may be equal to or different than the GUID of the underlying DataWriter virtual GUID.

The GUID identifies a QueueProducer and the samples it writes. This is the value set in the source GUID of the samples sent by the QueueProducer.

See Also: QueueProducer::send_sample(const T&); QueueEntityParams::entity_name

template<typename T>

bool rti::queuing::QueueProducer< T >::has_matching_reader_queue ( )

inline

Checks whether this QueueProducer has matched with at least one SharedReaderQueue.

Exceptions

One	of the Standard Exceptions ;

Returns: True if this QueueProducer matches with at least one SharedReaderQueue.

MT Safety:: SAFE

Public Member Functions

Detailed Description

template<typename T> class rti::queuing::QueueProducer< T >

Constructor & Destructor Documentation

Member Function Documentation

template<typename T>
class rti::queuing::QueueProducer< T >