PUBLISH_MODE QosPolicy (DDS Extension)
This QosPolicy determines the DataWriter’s publishing mode, either asynchronous or synchronous.
The publishing mode controls whether data is written synchronously—in the context of the user thread when calling write(), or asynchronously—in the context of a separate thread internal to Connext DDS.
Note: Asynchronous DataWriters do not perform sender-side filtering. Any filtering, such as time-based or content-based filtering, takes place on the DataReader side.
Each Publisher spawns a single asynchronous publishing thread (set in its ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)) to serve all its asynchronous DataWriters.
When data is written asynchronously, a FlowController (FlowControllers (DDS Extension)), identified by flow_controller_name, can be used to shape the network traffic. The FlowController's properties determine when the asynchronous publishing thread is allowed to send data and how much.
The fastest way for Connext DDS 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, for sending large data reliably, an asynchronous thread must be used (see ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)).
This QosPolicy can select a FlowController to prioritize or shape the data flow sent by a DataWriter to DataReaders. Shaping a data flow usually means limiting the maximum data rates with which the middleware will send data for a DataWriter. The FlowController will buffer data sent faster than the maximum rate by the DataWriter, and then only send the excess data when the user send rate drops below the maximum rate.
If kind is set to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS, the flow controller referred to by flow_controller_name must exist. Otherwise, the setting will be considered inconsistent.
This QosPolicy includes the members in DDS_PublishModeQosPolicy. For the defaults, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_PublishMode |
kind |
Either:
|
|
char* |
flow_controller_ |
Name of the associated flow controller. There are three built-in FlowControllers:
You may also create your own FlowControllers. |
|
DDS_Long |
priority |
A positive integer designating the relative priority of the DataWriter, used to determine the transmission order of pending writes. To use publication priorities, this QosPolicy’s kind must be DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS and the DataWriter must use a FlowController with a highest-priority first (HPF) scheduling_policy. |
The maximum number of DDS samples that will be coalesced depends on NDDS_Transport_Property_t::gather_send_buffer_count_max (each DDS 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.
Connext DDS queues DDS samples until they can be sent by the asynchronous publishing thread (as determined by the corresponding FlowController).
The number of DDS samples that will be queued is determined by the HISTORY QosPolicy: when using KEEP_LAST, the most recent depth DDS samples are kept in the queue.
Once unsent DDS samples are removed from the queue, they are no longer available to the asynchronous publishing thread and will therefore never be sent.
Unless flow_controller_name points to one of the built-in FlowControllers, finalizing the DataWriterQos will also free the string pointed to by flow_controller_name. Therefore, you should use DDS_String_dup() before passing the string to flow_controller_name, or reset flow_controller_name to NULL before the destructing /finalizing the QoS.
Advantages of Asynchronous Publishing:
Asynchronous publishing may increase latency, but offers the following advantages:
- The 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 DDS samples for the same destination will be coalesced into a single network packet which reduces bandwidth consumption.
Properties
This QosPolicy cannot be modified after the DataWriter is created.
Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.
Related QosPolicies
Applicable Entities
System Resource Considerations
See Configuring Resource Limits for Asynchronous DataWriters.
System resource usage depends on the settings in the corresponding FlowController (see FlowControllers (DDS Extension)).
© 2018 RTI