47.21 RELIABILITY QosPolicy
This RELIABILITY QosPolicy determines whether or not data published by a DataWriter will be reliably delivered by Connext to matching DataReaders. The reliability protocol used by Connext is discussed in Chapter 32 Reliability Models for Sending Data.
The reliability of a connection between a DataWriter and DataReader is entirely user configurable. It can be done on a per DataWriter/DataReader connection. A connection may be configured to be "best effort" which means that Connext will not use any resources to monitor or guarantee that the data sent by a DataWriter is received by a DataReader.
For some use cases, such as the periodic update of sensor values to a GUI displaying the value to a person, "best effort" delivery is often good enough. It is certainly the fastest, most efficient, and least resource-intensive (CPU and network bandwidth) method of getting the newest/latest value for a topic from DataWriters to DataReaders. But there is no guarantee that the data sent will be received. It may be lost due to a variety of factors, including data loss by the physical transport such as wireless RF or even Ethernet. Packets received out of order are dropped and reported as lost with the reason LOST_BY_WRITER (see 40.7.7 SAMPLE_LOST Status).
However, there are data streams (topics) in which you want an absolute guarantee that all data sent by a DataWriter is received reliably by DataReaders. This means that Connext must check whether or not data was received, and repair any data that was lost by resending a copy of the data as many times as it takes for the DataReader to receive the data.
Connext uses a reliability protocol configured and tuned by these QoS policies:
- 47.12 HISTORY QosPolicy
- 47.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension)
- 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension)
- 47.22 RESOURCE_LIMITS QosPolicy
The Reliability QoS policy kind is simply a switch to turn on the reliability protocol for a DataWriter/DataReader connection. The level of reliability provided by Connext is determined by the configuration of the aforementioned QoS policies.
You can configure Connext to deliver ALL data in the order they were sent (also known as absolute or strict reliability). Or, as a trade-off for less memory, CPU, and network usage, you can choose a reduced level of reliability where only the last N values are guaranteed to be delivered reliably to DataReaders (where N is user-configurable). With the reduced level of reliability, there are no guarantees that the data sent before the last N are received. Only the last N data packets are monitored and repaired if necessary.
It includes the members in Table 47.37 DDS_ReliabilityQosPolicy. For defaults and valid ranges, please refer to the API Reference HTML documentation.
|
Type |
Field Name |
Description |
|
DDS_ReliabilityQosPolicyKind |
kind |
Can be either:
|
|
DDS_Duration_t |
How long a DataWriter can block on a write() when the send queue is full due to unacknowledged messages. (Has no meaning for DataReaders.) |
|
|
DDS_ReliabilityQosPolicy- |
Kind of reliable acknowledgment. Only applies when kind is RELIABLE. Sets the kind of acknowledgments supported by a DataWriter and sent by DataReader. Possible values:
|
|
|
DDS_InstanceStateConsistencyKind |
instance_state_consistency_kind |
How to implement instance state consistency when a DataReader reconnects with a DataWriter that has lost liveliness (applies only to keyed data):
Note: Since instance state consistency uses the ServiceRequest channel, the RECOVER_INSTANCE_STATE_CONSISTENCY setting requires the enabled_builtin_channels field in the 44.3 DISCOVERY_CONFIG QosPolicy (DDS Extension) to be set to DDS_DISCOVERYCONFIG_SERVICE_REQUEST_CHANNEL (by default, it is). This setting also requires that kind be set to RELIABLE. See 19.1.5 Transition after NOT_ALIVE_NO_WRITERS for details. |
47.21.1 Reliability Kind
The kind of RELIABILITY can be either:
-
BEST_EFFORT
Connext will send DDS data samples only once to DataReaders. No effort or resources are spent to track whether or not sent DDS samples are received. Minimal resources are used. This is the most deterministic method of sending data since there is no indeterministic delay that can be introduced by buffering or resending data. DDS data samples may be lost. This setting is good for periodic data.
-
RELIABLE
Connext will send DDS samples reliably to DataReaders–buffering sent data until they have been acknowledged as being received by DataReaders and resending any DDS samples that may have been lost during transport. Additional resources configured by the HISTORY and RESOURCE_LIMITS QosPolicies may be used. Extra packets will be sent on the network to query (heartbeat) and acknowledge the receipt of DDS samples by the DataReader. This setting is a good choice when guaranteed data delivery is required; for example, sending events or commands.
To send large data reliably, you will also need to set the 47.20 PUBLISH_MODE QosPolicy (DDS Extension) kind to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS. Large in this context means that the data size is larger than the transport message_size_max property value. See 34.3 Large Data Fragmentation.
While a DataWriter sends data reliably, the 47.12 HISTORY QosPolicy and 47.22 RESOURCE_LIMITS QosPolicy determine how many DDS samples can be stored while waiting for acknowledgements from DataReaders. A DDS sample that is sent reliably is entered in the DataWriter’s send queue awaiting acknowledgement from DataReaders. How many DDS samples that the DataWriter is allowed to store in the send queue for a data-instance depends on the kind of the HISTORY QoS as well as the max_samples_per_instance and max_samples parameter of the RESOURCE_LIMITS QoS.
If the HISTORY kind is KEEP_LAST, then the DataWriter is allowed to have the HISTORY depth number of DDS samples per instance of the Topic in the send queue. Should the number of unacknowledged DDS samples in the send queue for a data-instance reach the HISTORY depth, then the next DDS sample written by the DataWriter for the instance will overwrite the oldest DDS sample for the instance in the queue. This implies that an unacknowledged DDS sample may be overwritten and thus lost. So even if the RELIABILITY kind is RELIABLE, if the HISTORY kind is KEEP_LAST, it is possible that some data sent by the DataWriter will not be delivered to the DataReader. What is guaranteed is that if the DataWriter stops writing, the last N DDS samples that the DataWriter wrote will be delivered reliably; where n is the value of the HISTORY depth.
However, if the HISTORY kind is KEEP_ALL, then when the send queue is filled with unacknowledged DDS samples (either due to the number of unacknowledged DDS samples for an instance reaching the RESOURCE_LIMITS max_samples_per_instance value or the total number of unacknowledged DDS samples have reached the size of the send queue as specified by RESOURCE_LIMITS max_samples), the next write() operation on the DataWriter will block until either a DDS sample in the queue has been fully acknowledged by DataReaders and thus can be overwritten or a timeout of RELIABILITY max_blocking_period has been reached.
If there is still no space in the queue when max_blocking_time is reached, the write() call will return a failure with the error code DDS_RETCODE_TIMEOUT.
Thus for strict reliability—a guarantee that all DDS data samples sent by a DataWriter are received by DataReaders—you must use a RELIABILITY kind of RELIABLE and a HISTORY kind of KEEP_ALL for both the DataWriter and the DataReader.
Although you can set the RELIABILITY QosPolicy on Topics, its value can only be used to initialize the RELIABILITY QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see 18.1.3 Setting Topic QosPolicies.
47.21.2 Example
This QosPolicy is used to achieve reliable communications, which is discussed in Chapter 32 Reliability Models for Sending Data and 32.4.1 Enabling Reliability.
47.21.3 Properties
This QosPolicy cannot be modified after the Entity has been enabled.
The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, the DataWriter and DataReader must use one of the valid combinations for the Reliability kind (see Table 47.38 Valid Combinations of Reliability ‘kind’), one of the valid combinations for the acknowledgment_kind (see Table 47.40 Valid Combinations of Reliability ‘acknowledgment_kind’), and one of the valid combinations for the instance_state_consistency_kind (see ):
|
|
|
DataReader requests: |
|
|
|
|
BEST_EFFORT |
RELIABLE |
|
DataWriter offers: |
BEST_EFFORT |
compatible |
incompatible |
|
RELIABLE |
compatible |
compatible |
|
If this QosPolicy is found to be incompatible, statuses ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS will be modified and the corresponding Listeners called for the DataWriter and DataReader, respectively.
There are no compatibility issues regarding the value of max_blocking_wait, since it does not apply to DataReaders.
47.21.4 Related QosPolicies
- 47.12 HISTORY QosPolicy
- 47.20 PUBLISH_MODE QosPolicy (DDS Extension)
- 47.22 RESOURCE_LIMITS QosPolicy
47.21.5 Applicable Entities
47.21.6 System Resource Considerations
Setting the kind to RELIABLE will cause Connext to use up more resources to monitor and maintain a reliable connection between a DataWriter and all of its reliable DataReaders. This includes the use of extra CPU and network bandwidth to send and process heartbeat, ACK/NACK, and repair packets (see Chapter 32 Reliability Models for Sending Data).
When instance_state_consistency_kind is set to RECOVER_INSTANCE_STATE_CONSISTENCY, Connext will consume more resources. These include extra CPU and bandwidth to send and process instance state consistency requests and responses when formerly matched DataReaders and DataWriters regain liveliness. (Connext automatically creates a DataWriter for each Publisher; that DataWriter is used to send responses containing instance state to DataReaders' instance state consistency requests. Connext automatically creates a DataReader for each Subscriber; that DataReader is used to receive the responses containing instance state.)
Setting max_blocking_time to a non-zero number may block the sending thread when the RELIABILITY kind is RELIABLE.