RELIABILITY QosPolicy
This RELIABILITY QosPolicy determines whether or not data published by a DataWriter will be reliably delivered by Connext DDS to matching DataReaders. The reliability protocol used by Connext DDS is discussed in Reliable Communications.
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 DDS 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 a SAMPLE_LOST Status is generated.
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 DDS 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 DDS uses a reliability protocol configured and tuned by these QoS policies:
- HISTORY QosPolicy,
- DATA_WRITER_PROTOCOL QosPolicy (DDS Extension),
- DATA_READER_PROTOCOL QosPolicy (DDS Extension),
- RESOURCE_LIMITS QosPolicy
The Reliability QoS policy is simply a switch to turn on the reliability protocol for a DataWriter/DataReader connection. The level of reliability provided by Connext DDS is determined by the configuration of the aforementioned QoS policies.
You can configure Connext DDS 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 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:
|
The kind of RELIABILITY can be either:
-
BEST_EFFORT
Connext DDS 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 DDS 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 PUBLISH_MODE QosPolicy (DDS Extension) kind to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS. Large in this context means that the data cannot be sent as a single packet by a transport (for example, data larger than 63K when using UDP/IP).
While a DataWriter sends data reliably, the HISTORY QosPolicy and 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 unacknowledge 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 acknowledged 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 DDS, see Setting Topic QosPolicies.
Example
This QosPolicy is used to achieve reliable communications, which is discussed in Reliable Communications and Enabling Reliability.
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 Valid Combinations of Reliability ‘kind’), and one of the valid combinations for the acknowledgment_kind (see Valid Combinations of Reliability ‘acknowledgment_kind’):
|
|
|
DataReader requests: |
|
|
|
|
BEST_EFFORT |
RELIABLE |
|
DataWriter offers: |
BEST_EFFORT |
4 |
incompatible |
|
RELIABLE |
4 |
4 |
|
|
|
DataReader requests: |
|||
|
PROTOCOL |
APPLICATION_ |
APPLICATION_ |
||
|
DataWriter offers: |
PROTOCOL |
4 |
incompatible |
incompatible |
|
APPLICATION_AUTO |
4 |
4 |
4 |
|
|
APPLICATION_EXPLICIT |
4 |
4 |
4 |
|
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.
Related QosPolicies
Applicable Entities
System Resource Considerations
Setting the kind to RELIABLE will cause Connext DDS 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 Reliable Communications).
Setting max_blocking_time to a non-zero number may block the sending thread when the RELIABILITY kind is RELIABLE.
© 2018 RTI