Specifies how RTI Connext sends application data on the network. This QoS policy can be used to tell RTI Connext to use its own thread to send data, instead of the user thread. More...

Data Fields
DDS_PublishModeQosPolicyKind	kind
	Publishing mode. More...

char *	flow_controller_name
	Name of the associated flow controller. More...

DDS_Long	priority
	Publication priority. More...

Detailed Description

Specifies how RTI Connext sends application data on the network. This QoS policy can be used to tell RTI Connext 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.

Each DDS_Publisher spawns a single asynchronous publishing thread (DDS_AsynchronousPublisherQosPolicy::thread) to serve all its asynchronous DDS_DataWriter instances.

See also: DDS_AsynchronousPublisherQosPolicy; DDS_HistoryQosPolicy; DDS_FlowController

Entity:: DDS_DataWriter

Properties:: RxO = N/A
Changeable = NO

Usage

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

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

Field Documentation

◆ kind

DDS_PublishModeQosPolicyKind DDS_PublishModeQosPolicy::kind

Publishing mode.

[default] DDS_SYNCHRONOUS_PUBLISH_MODE_QOS

◆ flow_controller_name

char* DDS_PublishModeQosPolicy::flow_controller_name

Name of the associated flow controller.

The following builitin values are supported:

NULL value or zero-length string refers to DDS_DEFAULT_FLOW_CONTROLLER_NAME.

Warning: The value for this field can be one of the constants above or a string allocated with DDS_String_dup() to specify your own custom flow controller name. You should not assign a string literal. When you assign a new value with DDS_String_dup(), first check if the current value is one of the constants above. If it is, simply replace it; if it's not, you have to release the current string and assign the new one. Here is an example of such an approach:

struct DDS_DataWriterQos writer_qos;
char *flow_controller_name = NULL;
DDS_DataWriterQos_initialize(&writer_qos);
...
DDS_Publisher_get_default_datawriter_qos(publisher, &writer_qos);
...
flow_controller_name = writer_qos.publish_mode.flow_controller_name;
if (flow_controller_name == DDS_DEFAULT_FLOW_CONTROLLER_NAME
        || flow_controller_name == DDS_FIXED_RATE_FLOW_CONTROLLER_NAME
        || flow_controller_name == DDS_ON_DEMAND_FLOW_CONTROLLER_NAME) {
    // Since the value was never on the heap, this won't leak memory
    flow_controller_name = NULL;
} else {
    // This means the value is present on the heap
    DDS_String_free(flow_controller_name);
}
// New value using DDS_String_dup() or one of the predefined constants
flow_controller_name = DDS_String_dup("My custom flow controller name");
. . .
DDS_DataWriterQos_finalize(&writer_qos);

The strings allocated with DDS_String_dup() are released when writer_qos is finalized.

More information about string handling can be found under String Conventions.

See also: DDS_DomainParticipant_create_flowcontroller

[default] DDS_DEFAULT_FLOW_CONTROLLER_NAME

◆ priority

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.

For multi-channel DataWriters, if the publication priority of any channel is set to any value other than DDS_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 DDS_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 DDS_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 DDS_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 DDS_WriteParams_t of the FooDataWriter_write_w_params function.

For dispose and unregister samples, use the DDS_WriteParams_t of FooDataWriter_dispose_w_params and FooDataWriter_unregister_instance_w_params.