47.26 TRANSPORT_PRIORITY QosPolicy
The TRANSPORT_PRIORITY QosPolicy is optional and only supported on certain OSs and transports by RTI. Its intention is to allow you to specify on a per-DataWriter or per-DataReader basis that the data sent by a DataWriter or DataReader is of a different priority.
DDS does not specify how a DDS implementation shall treat data of different priorities. It is often difficult or impossible for DDS implementations to treat data of higher priority differently than data of lower priority, especially when data is being sent (delivered to a physical transport) directly by the thread that called the DataWriter’s write() operation. Also, many physical network transports themselves do not have an end-user controllable level of data packet priority.
In Connext, for the IP-based transports (UDPv4, UDPv6, Real-Time WAN Transport, and TCP), the value set in the TRANSPORT_PRIORITY QosPolicy can be used to set the differentiated services field (DS field) bits of the IPv4 and IPv6 headers for datagrams sent by a DataWriter or DataReader. It is platform-dependent on how and whether setting the DS field has an effect. Some platforms may require external permissions in order to set the DS field.
The transport priority value is not provided as is to the transports, but transformed according to the transport_priority_mask, transport_priority_mapping_low, and transport_priority_mapping_high properties (see 51.6 Setting Builtin Transport Properties with the PropertyQosPolicy). If you want the priority value to be exactly equal to the DS value, then the only change you need to make is to set transport_priority_mask to 0xff (and keep the transport_priority_mapping_low and transport_priority_mapping_high defaults).
It is incorrect to assume that using the TRANSPORT_PRIORITY QosPolicy will have any effect at all on the end-to-end delivery of data between a DataWriter and DataReader. All network elements such as switches and routers must have the capability and be enabled to actually use the DS field to treat higher-priority packets differently. Thus the ability to use the TRANSPORT_PRIORITY QosPolicy must be designed and configured at a system level; just turning it on in an application may have no effect at all at a transport level.
For additional details on how to set the DS field in IP-based transports, see 47.26.5 Setting DS Field in IP-Based Transports.
The TRANSPORT_PRIORITY QosPolicy includes the member in Table 47.44 DDS_TransportPriorityQosPolicy. For the default and valid range, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_Long |
value |
Hint as to how to set the priority. |
Connext will propagate the value set on a per-DataWriter or per-DataReader basis to the transport when the DataWriter publishes data. It is up to the implementation of the transport to do something with the value, if anything.
You can set the TRANSPORT_PRIORITY QosPolicy on a Topic and use its value to initialize the TRANSPORT_PRIORITY QosPolicies of DataWriters and DataReaders. The TRANSPORT_PRIORITY QosPolicy of a Topic does not directly affect the operation of Connext, see 18.1.3 Setting Topic QosPolicies.
For discovery DataWriters and DataReaders, the Transport priority can be set using the field metatraffic_transport_priority in the 44.2 DISCOVERY QosPolicy (DDS Extension).
47.26.1 Properties
This QosPolicy cannot be modified after the entity is created.
47.26.2 Related QosPolicies
This QosPolicy does not interact with any other policies.
47.26.3 Applicable Entities
47.26.4 System Resource Considerations
The use of this policy does not significantly impact the use of resources. However, if a transport is implemented to use the value set by this policy, then there may be transport-specific issues regarding the resources that the transport implementation itself uses.
47.26.5 Setting DS Field in IP-Based Transports
Connext allows setting the ToS field of the IPv4 and IPv6 headers. See Figure 47.2: Using DSCP Values to Prioritize IP Traffic.
The modern redefinition of the ToS field is an 8-bit differentiated services field (DS field), which consists of a 6-bit Differentiated Services Code Point (DSCP) field encoded in the most significant bits and a 2-bit Explicit Congestion Notification (ECN) field encoded in the least significant bits (not shown in Figure 47.2: Using DSCP Values to Prioritize IP Traffic).
The DSCP values can be used by the underlying network infrastructure to prioritize IP traffic.
Figure 47.2: Using DSCP Values to Prioritize IP Traffic
In theory, a network could have up to 64 different traffic classes using the 64 available DSCP values (6-bit). The DiffServ RFCs recommend, but do not require, certain encodings. This gives a network operator great flexibility in defining traffic classes. In practice, however, most networks use the following commonly defined per-hop behaviors:
- Default Forwarding (DF or BE) PHB — which is typically best-effort traffic.
- Expedited Forwarding (EF) PHB — dedicated to low-loss, low-latency traffic.
- Assured Forwarding (AF) PHB — gives assurance of delivery under prescribed conditions.
- Class Selector PHBs (CS) — which maintain backward compatibility with the IP precedence field of the old TOS field.
There are four Assured Forwarding classes, denoted by the letters AF followed by two digits. The first digit denotes the AF class and can range from 1 through 4. The second digit refers to the level of drop preference within each AF class and can range from 1 (lowest drop preference) to 3 (highest drop preference).
47.26.5.1 Configuring DS Field with DDS
At the DomainParticipant level, configure the following transport priority mask as shown in the following XML snippets:
Using properties:
<participant_qos>
<property>
<value>
<element>
<name>dds.transport.UDPv4.builtin.transport_priority_mask</name>
<value>0x00000FF</value>
</element>
</value>
</property>
</participant_qos>
Using the <transport_priority_mask> XML tag:
<participant_qos>
<transport_builtin>
<udpv4>
<transport_priority_mask>0xFF</transport_priority_mask>
</udpv4>
</transport_builtin>
</participant_qos>
Then, for each DataWriter and DataReader, configure the transport priority using the TRANSPORT_PRIORITY QoS Policy with a value between 0 and FF. The priorities on DataWriters and DataReaders are independent. The priority set on a DataWriter will set the DS field for RTPS packets sent by the DataWriter. The priority set on a DataReader will set the ToS field for RTPS packets sent by the DataReader.
For example:
- Assume that you want to prioritize the traffic sent by a DataWriter using the Expedited Forwarding (EF) traffic class. In this case, your priority should be set to the following:
<datawriter_qos>
<transport_priority>
<value>0xB8</value>
</transport_priority>
</datawriter_qos>
Where 0xB8 = 101110 00
Where 101110 is the DSCP and 00 is the ECN.
Below find a Wireshark capture snapshot showing how the DS field was set:
- Assume that you want to prioritize the traffic sent by a DataReader using the Assured Forwarding AF11 traffic class. In this case, your priority should be set to the following:
<datareader_qos>
<transport_priority>
<value>0x28</value>
</transport_priority>
</datareader_qos>
Where 0x28 = 001010 00
Where 001010 is the DSCP, and 00 is the ECN.
Below find a Wireshark capture snapshot showing how the DS field was set:
47.26.5.2 Configuring DS Field for Discovery Traffic
You can also set the DS field value for discovery traffic by setting the following QoS value:
<participant_qos>
<discovery>
<metatraffic_transport_priority>0xB8</metatraffic_transport_priority>
</discovery>
</participant_qos>
47.26.5.3 Configuring DS Field Programmatically
Before the DomainParticipant is created, add the dds.transport.UDPv4.builtin.transport_priority_mask to the DomainParticipant QoS that will be used to create the DomainParticipant, as indicated in the following traditional C++ code snippet:
retcode = DDSPropertyQosPolicyHelper::assert_property(
dp_qos.property,
"dds.transport.UDPv4.builtin.transport_priority_mask",
"0xFF",
RTI_FALSE);
if (retcode != DDS_RETCODE_OK) {/* Error */
}
Before creating DataWriters and DataReaders, set the transport priority field in the QoS used to create the Entity. For example:
dw_qos.transport_priority.value = 0xB8;