47.8 DESTINATION_ORDER QosPolicy

When multiple DataWriters send data for the same topic, the order in which data from different DataWriters are received by the applications of different DataReaders may be different. Thus different DataReaders may not receive the same "last" value when DataWriters stop sending data.

This policy controls how each subscriber resolves the final value of a data instance that is written by multiple DataWriters (which may be associated with different Publishers) running on different nodes.

This QosPolicy can be used to create systems that have the property of "eventual consistency." Thus intermediate states across multiple applications may be inconsistent, but when DataWriters stop sending changes to the same topic, all applications will end up having the same state.

Each DDS sample includes two timestamps: a source timestamp and a reception timestamp. The source timestamp is recorded by the DataWriter application when the data was written. The reception timestamp is recorded by the DataReader application when the data was received.

This QoS includes the members in Table 47.17 DDS_DestinationOrderQosPolicy.

Table 47.17 DDS_DestinationOrderQosPolicy

Type

Field Name

Description

DDS_DestinationOrderQosPolicyKind

kind

Can be either:

DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS

DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS

DDS_DestinationOrderQosPolicyScopeKind

scope

Can be either:

DDS_INSTANCE_SCOPE_DESTINATIONORDER_QOS - Indicates that data is ordered on a per instance basis if used along with DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS. The source timestamp of the current sample is compared to the source timestamp of the previously received sample for the same instance. The tolerance check is also applied per instance.

DDS_TOPIC_SCOPE_DESTINATIONORDER_QOS - Indicates that data is ordered on a per topic basis if used along with DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS. The source timestamp of the current sample is compared to the source timestamp of the previously received sample for the same topic. The tolerance check is also applied per topic.

DDS_Duration_t

source_timestamp_tolerance

Allowed tolerance between source timestamps of consecutive DDS samples. Only applies when kind (above) is DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS.

  • For a DataWriter: The write operation will fail if the source timestamp of the sample is older than the timestamp of the previously written DDS sample by more than the source_timestamp_tolerance.
  • For a DataReader: A DataReader will accept a sample only if the source timestamp is no farther in the future from the reception timestamp than the source_timestamp_tolerance.

This QoS policy can be set for both DataWriters and DataReaders. See 47.8.1 Properties for compatibility rules.

For a DataReader:

  • DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS
  • Assuming the OWNERSHIP_STRENGTH allows it, the latest received value for the instance should be the one whose value is kept. Data will be delivered by a DataReader in the order in which it was received (which may lead to inconsistent final values).

  • DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS
  • If scope is set to DDS_INSTANCE_SCOPE_DESTINATIONORDER_QOS (default), within each instance, the sample's source timestamp shall be used to determine the most recent information. This is the only setting that, in the case of concurrent same-strength DataWriters updating the same instance, ensures that all DataReaders end up with the same final value for the instance. If a DataReader receives a sample for an instance with a source timestamp that is older than the last source timestamp received for the instance, the sample is dropped. You can keep track of the total number of dropped samples for this reason with the old_source_timestamp_dropped_sample_count field in the 40.7.2 DATA_READER_CACHE_STATUS. The SAMPLE_REJECTED status or the SAMPLE_LOST status will not be updated.

    If scope is set to DDS_TOPIC_SCOPE_DESTINATIONORDER_QOS, the ordering is enforced per topic across all instances.

    In addition, a DataReader will accept a sample only if the source timestamp is no farther in the future from the reception timestamp than the source_timestamp_tolerance. Otherwise, the DDS sample is dropped. You can keep track of the total number of dropped samples for this reason with the tolerance_source_timestamp_dropped_sample_count field in the 40.7.2 DATA_READER_CACHE_STATUS. The SAMPLE_REJECTED status or the SAMPLE_LOST status will not be updated.

For the DataWriter:

  • DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS
  • The DataWriter will not enforce source timestamp ordering when writing samples using the DataWriter::write_w_timestamp or DataWriter::write_w_params API. The source timestamp of a new sample can be older than the source timestamp of the previous samples.

  • DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS
  • If scope is set to DDS_INSTANCE_SCOPE_DESTINATIONORDER_QOS (default), when writing a sample, the sample’s timestamp must not be older than the timestamp of the previously written DDS sample for the same instance. If, however, the timestamp is older than the timestamp of the previously written DDS sample—but the difference is less than the source_timestamp_tolerance—the DDS sample will use the previously written DDS sample's timestamp as its timestamp. Otherwise, if the difference is greater than the tolerance, the write will fail with retcode DDS_RETCODE_BAD_PARAMETER.

    If scope is set to DDS_TOPIC_SCOPE_DESTINATIONORDER_QOS, a new sample timestamp must not be older than the timestamp of the previously written DDS sample, across all instances. (The ordering is enforced across all instances.)

Although you can set the DESTINATION_ORDER QosPolicy on Topics, its value can only be used to initialize the DESTINATION_ORDER QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see 18.1.3 Setting Topic QosPolicies.

47.8.1 Properties

This QosPolicy cannot be modified after the Entity is enabled.

This QoS must be set compatibly between the DataWriter and the DataReader. The compatible combinations are shown in Table 47.18 Valid Reader/Writer Combinations of DestinationOrder.

Table 47.18 Valid Reader/Writer Combinations of DestinationOrder

Destination Order

DataReader requests:

BY_SOURCE

BY_RECEPTION

DataWriter offers:

BY_SOURCE

compatible

compatible

BY_RECEPTION

incompatible

compatible

If this QosPolicy is set incompatibly, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding Listeners called for the DataWriter and DataReader respectively.

47.8.2 Related QosPolicies

47.8.3 Applicable DDS Entities

47.8.4 System Resource Considerations

The use of this policy does not significantly impact the use of resources.