RTI Connext DDS Micro C API
Version 3.0.3
|
Specifies how RTI Connext DDS Micro sends application data on the network. This QoS policy can be used to tell RTI Connext DDS Micro to use its own thread to send data, instead of the user thread. More...
#include <dds_c_infrastructure.h>
Data Fields | |
DDS_PublishModeQosPolicyKind | kind |
Publishing mode. | |
const char * | flow_controller_name |
Name of the associated flow controller. | |
DDS_Long | priority |
Publication priority. |
Specifies how RTI Connext DDS Micro sends application data on the network. This QoS policy can be used to tell RTI Connext DDS Micro to use its own thread to send data, instead of the user thread.
The publishing mode of a DDS_DataWriter determines whether data is written synchronously in the context of the user thread when calling FooDataWriter_write or asynchronously in the context of a separate thread internal to the middleware.
The fastest way for RTI Connext DDS Micro 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 DDS_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_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 FooDataWriter_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.
The middleware must queue samples until they can be sent by the publishing thread (as determined by the corresponding DDS_FlowController). The number of samples that will be queued is determined by the DDS_HistoryQosPolicy. When using DDS_KEEP_LAST_HISTORY_QOS, only the most recent DDS_HistoryQosPolicy::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.
DDS_PublishModeQosPolicyKind DDS_PublishModeQosPolicy::kind |
Publishing mode.
[default] DDS_SYNCHRONOUS_PUBLISH_MODE_QOS
const char* DDS_PublishModeQosPolicy::flow_controller_name |
Name of the associated flow controller.
NULL value or zero-length string refers to DDS_DEFAULT_FLOW_CONTROLLER_NAME.
Unless flow_controller_name
points to a built-in flow controller, finalizing the DDS_DataWriterQos will also free the string pointed to by flow_controller_name
. Therefore, use DDS_String_dup before passing the string to flow_controller_name
, or reset flow_controller_name
to NULL before finalizing the QoS.
Please refer to Conventions for more information.
[default] DDS_DEFAULT_FLOW_CONTROLLER_NAME
DDS_Long DDS_PublishModeQosPolicy::priority |
Publication priority.
A positive integer value designating the relative priority of the DDS_DataWriter, used to determine the transmission order of pending writes.
Use of publication priorities requires the asynchronous publisher (DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS) with DDS_FlowControllerProperty_t::scheduling_policy set to DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY.
Larger numbers have higher priority.
[default] DDS_PUBLICATION_PRIORITY_UNDEFINED