34.4.4 Prioritized DDS Samples

Note: This feature is not supported when using the Ada API.

The Prioritized DDS Samples feature allows you to prioritize traffic that is in competition for transmission resources. The granularity of this prioritization may be by DataWriter, by instance, or by individual DDS sample.

Prioritized DDS Samples can improve latency in the following cases:

• Low-Availability Links

With low-availability communication, unsent DDS samples may accumulate while the link is unavailable. When the link is restored, a large number of DDS samples may be waiting for transmission. High priority DDS samples will be sent first.

• Low-Bandwidth Links

With low-bandwidth communication, a temporary backlog may occur or the link may become congested with large DDS samples. High-priority DDS samples will be sent at the first available gap, between the fragments of a large low-priority DDS sample.

• Prioritized Topics

With limited bandwidth communication, some topics may be deemed to be of higher priority than others on an ongoing basis, and DDS samples written to some topics should be given precedence over others on transmission.

• High Priority Events

Due to external rules or content analysis (e.g., perimeter violation or identification as a threat), the priority of DDS samples is dynamically determined, and the priority assigned a given DDS sample will reflect the urgency of its delivery.

To configure a DataWriter to use prioritized DDS samples:

• Create a FlowController with the scheduling_policy property set to DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY.
• Create a DataWriter with the 47.20 PUBLISH_MODE QosPolicy (DDS Extension) kind set to ASYNCHRONOUS and flow_controller_name set to the name of the FlowController.

A single FlowController may perform traffic shaping for multiple DataWriters and multiple DataWriter channels. The FlowController’s configuration determines how often publication resources are scheduled, how much data may be sent per period, and other transmission characteristics that determine the ultimate performance of prioritized DDS samples.

When working with prioritized DDS samples, you should use these operations, which allow you to specify priority:

• write_w_params() (see 31.8 Writing Data)
• unregister_instance_w_params() (see 31.14.4 Unregistering Instances)
• dispose_w_params() (see 31.14.3 Disposing Instances)

If you use write(), unregister(), or dispose() instead of the _w_params() versions, the affected DDS sample is assigned priority 0 (undefined priority). If you are using a multi-channel DataWriter with a priority filter, and you have no channel for priority 0, the DDS sample will be discarded.

34.4.4.1 Designating Priorities

For DataWriters and DataWriter channels, valid publication priority values are:

• DDS_PUBLICATION_PRIORITY_UNDEFINED
• DDS_PUBLICATION_PRIORITY_AUTOMATIC
• Positive integers excluding zero

For individual DDS samples, valid publication priority values are 0 and positive integers.

There are three ways to set the publication priority of a DataWriter or DataWriter channel:

1. For a DataWriter, publication priority is set in the priority field of its 47.20 PUBLISH_MODE QosPolicy (DDS Extension). For a multi-channel DataWriter (see 47.16 MULTI_CHANNEL QosPolicy (DDS Extension)), this value will be the default publication priority for any member channel that has not been assigned a specific value.
2. For a channel of a Multi-channel DataWriter, publication priority can be set in the DataWriter’s 47.16 MULTI_CHANNEL QosPolicy (DDS Extension) in channels[].priority.
3. If a DataWriter or a channel of a Multi-channel DataWriter is configured for publication priority inheritance (DDS_PUBLICATION_PRIORITY_AUTOMATIC), its publication priority is the highest priority among all the DDS samples currently in the publication queue. When using publication priority inheritance, the publication priorities of individual DDS samples are set by calling the write_w_params() operation, which takes a priority parameter.

The effective publication priority is determined from the interaction of the DataWriter, channel, and DDS sample publication priorities, as shown in Table 34.5 Effective Publication Priority of Samples.

Table 34.5 Effective Publication Priority of Samples

	Priority Setting Combinations
Writer Priority	Undefined	Don’t care	AUTOMATIC	Don’t care	Designated positive integer > 0
Channel Priority	Undefined	AUTOMATIC	Undefined	Designated positive integer > 0	Undefined
DDS Sample Priority	Don’t care	Designated positive integer > 0	Designated positive integer > 0	Don’t care	Don’t care
Effective Priority	Lowest Priority	DDS Sample Priority1 Highest sample priority among all DDS samples currently in the publication queue.	DDS Sample Priority2 Highest sample priority among all DDS samples currently in the publication queue.	Channel Priority	Writer Priority

34.4.4.2 Priority-Based Filtering

The configuration methods explained above are sufficient to create multiple DataWriters, each with its own assigned priority, all using the same FlowController configured for publication priority-based scheduling. Such a configuration is sufficient to assign different priorities to individual topics, but it does not allow different publication priorities to be assigned to published data within a Topic.

To assign different priorities to data within a DataWriter, you will need to use a Multi-channel DataWriter and configure the channels with different priorities. Configuring the publication priorities of DataWriter channels is explained above. To associate different priorities of data with different publication channels, configure the channel[].filter_expression in the DataWriter’s 47.16 MULTI_CHANNEL QosPolicy (DDS Extension). The filtering criteria that is available for evaluation by each channel is determined by the filter type, which is configured with the DataWriter’s filter_name (also in the 47.16 MULTI_CHANNEL QosPolicy (DDS Extension)).

For example, using the built-in SQL-based content filter allows channel membership to be determined based on the content of each DDS sample.

If you do not want to embed priority criteria within each DDS sample, you can use a built-in filter named DDS_PRIFILTER_NAME that uses the publication priority that is provided when you call write_w_params() (see 31.8 Writing Data). The filter’s expression syntax is:

@priority OP VAL

where OP can be < , <= , > , >= , = , or <> (standard relational operators), and VAL is a positive integer.

The filter supports multiple expressions, combined with the conjunctions AND and OR. You can use parentheses to disambiguate combinations of AND and OR in the same expression. For example:

@priority = 2 OR (@priority > 6 AND @priority < 10)