59.20 PUBLISH_MODE QosPolicy (DDS Extension)

This QosPolicy determines whether a DataWriter sends data synchronously—in the context of the user thread when calling write(), or asynchronously—in the context of a separate thread internal to Connext.

The fastest way for 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.

Although asynchronous publishing may increase latency, it 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 may be coalesced into a single network packet which reduces bandwidth consumption.

Note that the following items are closely related:

  • PUBLISH_MODE QoS policy: Determines whether a specific DataWriter should use synchronous or asynchronous write(). If you choose asynchronous write(), the PUBLISH_MODE QoS policy is also used to determine the FlowController the DataWriter should use.
  • ASYNCHRONOUS_PUBLISHER QoS policy: When a DataWriter is configured to write asynchronously, its Publisher spawns a new thread to handle this. The Publisher's asynchronous publishing thread serves all of the Publisher's asynchronous DataWriters. This thread is configured by the 58.1 ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension).
  • FlowControllers: When data is written asynchronously, a FlowController (37.3 FlowControllers (DDS Extension)), identified by flow_controller_name in the PUBLISH_MODE QoS policy, can be used 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 written by a DataWriter.

Note: For information on asynchronous DataWriters and sender-side filtering, see 45.1 Where Filtering is Applied—Publishing vs. Subscribing Side.

This QosPolicy includes the members in Table 59.36 DDS_PublishModeQosPolicy.

See the API Reference HTML documentation for complete QoS details, including functional categories, defaults, and other QoS attributes. (API References are here: <NDDSHOME>/doc/api/connext_dds/api_<language>) For example, click here for QoS in the Modern C++ API.

Table 59.36 DDS_PublishModeQosPolicy

Type

Field Name

Description

DDS_PublishMode

QosPolicyKind

kind

Either:

  • DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS
  • DDS_SYNCHRONOUS_PUBLISH_MODE_QOS

NOTE: To use these values in XML, omit the "DDS_" prefix. See 62.4.4 Enumeration Values.

char*

flow_controller_name

Name of the associated flow controller.

There are three built-in FlowControllers:

  • DDS_DEFAULT_FLOW_CONTROLLER_NAME
  • DDS_FIXED_RATE_FLOW_CONTROLLER_NAME
  • DDS_ON_DEMAND_FLOW_CONTROLLER_NAME

You may also create your own FlowControllers.

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.

NOTE: To use these values in XML, omit the "DDS_" prefix. See 62.4.4 Enumeration Values.

See 37.3 FlowControllers (DDS Extension).

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.

See 37.3.4 Prioritized DDS Samples.

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 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 59.12 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.

59.20.1 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.

59.20.2 Related QosPolicies

59.20.3 Applicable Entities

59.20.4 System Resource Considerations

See 59.22.1 Configuring Resource Limits for Asynchronous DataWriters.

System resource usage depends on the settings in the corresponding FlowController (see 37.3 FlowControllers (DDS Extension)).