|
RTI Connext Modern C++ API
Version 6.1.0
|
<<extension>> Specifies whether a dds::pub::DataWriter sends data synchronously or asynchronously. More...
#include <rti/core/policy/CorePolicy.hpp>
Public Member Functions | |
| PublishMode () | |
| Creates a PublishMode qos policy of synchronous kind. More... | |
| PublishMode & | kind (const rti::core::policy::PublishModeKind the_kind) |
| Sets the publish mode (synchronous or asynchronous) for a DataWriter. More... | |
| rti::core::policy::PublishModeKind | kind () const |
| Gets the publish mode. More... | |
| std::string | flow_controller_name () const |
| Gets the flow controller name. More... | |
| PublishMode & | flow_controller_name (const std::string &name) |
| Sets the flow controller name associated with a DataWriter. More... | |
| int32_t | priority () const |
| Sets the priority of all samples written by a DataWriter. More... | |
| PublishMode & | priority (int32_t value) |
| Gets the priority. More... | |
Static Public Member Functions | |
| static PublishMode | Synchronous () |
| Creates a PublishMode qos policy of synchronous kind. More... | |
| static PublishMode | Asynchronous () |
| Creates a PublishMode qos policy of asynchronous kind with default flow controller and undefined priority. More... | |
| static PublishMode | Asynchronous (const std::string &flow_controller_name) |
| Creates a PublishMode qos policy of asynchronous kind with a specific flow controller and undefined priority. More... | |
| static PublishMode | Asynchronous (const std::string &flow_controller_name, int32_t priority) |
| Creates a PublishMode qos policy of asynchronous kind with specific flow controller and priority. More... | |
<<extension>> Specifies whether a dds::pub::DataWriter sends data synchronously or asynchronously.
The publishing mode of a dds::pub::DataWriter determines whether data is written synchronously in the context of the user thread when calling dds::pub::DataWriter::write() or asynchronously in the context of a separate thread internal to the middleware.
Each dds::pub::Publisher spawns a single asynchronous publishing thread (rti::core::policy::AsynchronousPublisher::thread) to serve all its asynchronous dds::pub::DataWriter instances.
The fastest way for RTI Connext to send data is for the user thread to execute the middleware code that actually sends the data itself. However, there are times when user applications may need or want an internal middleware thread to send the data instead. For instance, to send large data reliably, you must use an asynchronous thread.
When data is written asynchronously, a rti::pub::FlowController, identified by flow_controller_name, can be used to shape the network traffic. Shaping a data flow usually means limiting the maximum data rates at which the middleware will send data for a dds::pub::DataWriter. The flow controller will buffer any excess data and only send it when the send rate drops below the maximum rate. The flow controller's properties determine when the asynchronous publishing thread is allowed to send data and how much.
Asynchronous publishing may increase latency, but offers the following advantages:
- The dds::pub::DataWriter::write() call does not make any network calls and is therefore faster and more deterministic. This becomes important when the user thread is executing time-critical code.
- When data is written in bursts or when sending large data types as multiple fragments, a flow controller can throttle the send rate of the asynchronous publishing thread to avoid flooding the network.
- Asynchronously written samples for the same destination will be coalesced into a single network packet which reduces bandwidth consumption.
The maximum number of samples that will be coalesced depends on NDDS_Transport_Property_t::gather_send_buffer_count_max (each sample requires at least 2-4 gather-send buffers). Performance can be improved by increasing NDDS_Transport_Property_t::gather_send_buffer_count_max. Note that the maximum value is operating system dependent.
The middleware must queue samples until they can be sent by the asynchronous publishing thread (as determined by the corresponding rti::pub::FlowController). The number of samples that will be queued is determined by the dds::core::policy::History. When using dds::core::policy::HistoryKind::KEEP_LAST, only the most recent dds::core::policy::History::depth samples are kept in the queue. Once unsent samples are removed from the queue, they are no longer available to the asynchronous publishing thread and will therefore never be sent.
| rti::core::policy::PublishMode::PublishMode | ( | ) |
Creates a PublishMode qos policy of synchronous kind.
|
static |
Creates a PublishMode qos policy of synchronous kind.
|
static |
Creates a PublishMode qos policy of asynchronous kind with default flow controller and undefined priority.
|
static |
Creates a PublishMode qos policy of asynchronous kind with a specific flow controller and undefined priority.
|
static |
Creates a PublishMode qos policy of asynchronous kind with specific flow controller and priority.
| PublishMode& rti::core::policy::PublishMode::kind | ( | const rti::core::policy::PublishModeKind | the_kind | ) |
Sets the publish mode (synchronous or asynchronous) for a DataWriter.
[default] rti::core::policy::PublishModeKind_def::SYNCHRONOUS
| rti::core::policy::PublishModeKind rti::core::policy::PublishMode::kind | ( | ) | const |
Gets the publish mode.
| std::string rti::core::policy::PublishMode::flow_controller_name | ( | ) | const |
Gets the flow controller name.
| PublishMode& rti::core::policy::PublishMode::flow_controller_name | ( | const std::string & | name | ) |
Sets the flow controller name associated with a DataWriter.
The following builitin values are supported:
[default] rti::pub::FlowController::DEFAULT_NAME
| int32_t rti::core::policy::PublishMode::priority | ( | ) | const |
Sets the priority of all samples written by a DataWriter.
A positive integer value designating the relative priority of the dds::pub::DataWriter, used to determine the transmission order of pending writes.
Use of publication priorities requires the asynchronous publisher (rti::core::policy::PublishModeKind_def::ASYNCHRONOUS) with rti::pub::FlowControllerProperty::scheduling_policy set to FlowControllerSchedulingPolicy_def::HIGHEST_PRIORITY_FIRST.
Larger numbers have higher priority.
For multi-channel DataWriters, if the publication priority of any channel is set to any value other than PUBLICATION_PRIORITY_UNDEFINED, then the channel's priority will take precedence over that of the DataWriter.
For multi-channel DataWriters, if the publication priority of any channel is PUBLICATION_PRIORITY_UNDEFINED, then the channel will inherit the publication priority of the DataWriter.
If the publicaton priority of the DataWriter, and of any channel of a multi-channel DataWriter, are PUBLICATION_PRIORITY_UNDEFINED, then the priority of the DataWriter or DataWriter channel will be assigned the lowest priority value.
If the publication priority of the DataWriter is PUBLICATION_PRIORITY_AUTOMATIC, then the DataWriter will be assigned the priority of the largest publication priority of all samples in the DataWriter.
The publication priority of each sample can be set in the rti::pub::WriteParams of the dds::pub::DataWriter::write(const T&,rti::pub::WriteParams&) function.
For dispose and unregister samples, use the rti::pub::WriteParams of dds::pub::DataWriter::dispose_instance(rti::pub::WriteParams&) and dds::pub::DataWriter::unregister_instance(rti::pub::WriteParams&).
[default] PUBLICATION_PRIORITY_UNDEFINED
| PublishMode& rti::core::policy::PublishMode::priority | ( | int32_t | value | ) |
Gets the priority.