RTI Connext Modern C++ API
Version 6.1.2
|
Allows you to send samples to a specific SharedReaderQueue hosted by Queuing Service. More...
#include <rti/queuing/QueueProducer.hpp>
Public Member Functions | |
QueueProducer (const QueueProducerParams ¶ms, bool is_enabled=true, Listener *producer_listener=NULL, const rti::core::Guid &producer_guid=rti::core::Guid::unknown()) | |
Creates a queue producer. More... | |
QueueProducer (const QueueProducerParams ¶ms, bool is_enabled, std::shared_ptr< Listener > producer_listener, const rti::core::Guid &producer_guid=rti::core::Guid::unknown()) | |
Creates a QueueProducer 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 producer. More... | |
Listener * | listener () const |
Returns the listener currently associated with this Producer. 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 QueueProducer to send data and receive listener notifications. More... | |
void | send_sample (const T &sample) |
Sends a sample. More... | |
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. More... | |
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. More... | |
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. More... | |
dds::pub::DataWriter< T > | writer () const |
Retrieves the underlying dds::pub::DataWriter. More... | |
rti::core::Guid | guid () const |
Returns the GUID of this QueueProducer. More... | |
bool | has_matching_reader_queue () |
Checks whether this QueueProducer has matched with at least one SharedReaderQueue. More... | |
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.
T | The data type for the SharedReaderQueue topic |
|
inlineexplicit |
Creates a queue producer.
[DEPRECATED] When using a listener, prefer the constructor that receives a shared_ptr<Listener>
instead of a regular Listener*
pointer.
Referenced by rti::queuing::QueueProducer< TRep >::QueueProducer().
|
inlineexplicit |
Creates a QueueProducer with 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 shared_ptr to a QueueProducerListener object to receive event notifications. |
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. |
One | of the Standard Exceptions |
|
inline |
Sets the listener associated with this producer.
[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.
the_listener | The QueueProducerListener to set |
event_mask | The dds::core::status::StatusMask associated with the listener |
|
inline |
Returns the listener currently associated with this Producer.
[DEPRECATED] Prefer get_listener()
instead of this function.
If there is no listener it returns NULL.
Referenced by rti::queuing::QueueProducer< TRep >::has_matching_reader_queue().
|
inline |
Gets the listener.
|
inline |
Sets a listener to be notified of status updates.
the_listener | A shared pointer to the listener to receive updates or nullptr to reset the current listener and stop receiving updates. |
|
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.
|
inline |
Sends a sample.
This operation is equivalent to calling QueueProducer::send_sample(const T&, rti::pub::WriteParams&) using a default rti::pub::WriteParams.
sample | The sample to be sent |
One | of the Standard Exceptions or NoMatchingQueueException |
|
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.
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. |
One | of the Standard Exceptions or NoMatchingQueueException if by the time this operation is called there is not a single matching SharedReaderQueue. |
|
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.
max_wait | <<in>> Maximum waiting time. |
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. |
|
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.
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. |
|
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.
|
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.
|
inline |
Checks whether this QueueProducer has matched with at least one SharedReaderQueue.
One | of the Standard Exceptions ; |