RTI Connext Modern C++ API  Version 6.0.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
rti::queuing::QueueProducer< T > Class Template Reference

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

#include <rti/queuing/QueueProducer.hpp>

Inheritance diagram for rti::queuing::QueueProducer< T >:
dds::core::Reference< detail::QueueProducerImpl< T > >

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

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:

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
TThe 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
paramsAll the parameters that configure this QueueProducer. See QueueProducerParams for the list of required parameters.
is_enabledSpecifies 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_listenerA 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_guidA 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
Oneof 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_listenerThe QueueProducerListener to set
event_maskThe 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
sampleThe sample to be sent
Exceptions
Oneof 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
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&)
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
Oneof 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
Oneof 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
Oneof the Standard Exceptions ;
Returns
True if this QueueProducer matches with at least one SharedReaderQueue.
MT Safety:
SAFE

RTI Connext Modern C++ API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc