dds::core::policy::DestinationOrder Class Reference

Controls the logical order of updates to the same instance by a dds::pub::Publisher. More...

#include <dds/core/policy/CorePolicy.hpp>

Public Member Functions
	DestinationOrder ()
	Creates the default policy.
	DestinationOrder (dds::core::policy::DestinationOrderKind the_kind)
	Creates a policy with the specified destination order kind.
DestinationOrder &	kind (dds::core::policy::DestinationOrderKind the_kind)
	Sets the destination order kind.
dds::core::policy::DestinationOrderKind	kind () const
	Getter (see the setter with the same name)
DestinationOrderImpl &	scope (rti::core::policy::DestinationOrderScopeKind the_scope)
	<<extension>> Sets the destination order scope
rti::core::policy::DestinationOrderScopeKind	scope () const
	<<extension>> Getter (see the setter with the same name)
dds::core::policy::DestinationOrder &	source_timestamp_tolerance (const dds::core::Duration &ms)
	<<extension>> Sets the allowed tolerance between source timestamps of consecutive samples.
dds::core::Duration	source_timestamp_tolerance () const
	<<extension>> Getter (see the setter with the same name)

Static Public Member Functions
static DestinationOrder	SourceTimestamp ()
	Creates a DestinationOrder with DestinationOrderKind::BY_SOURCE_TIMESTAMP.
static DestinationOrder	ReceptionTimestamp ()
	Creates a DestinationOrder with DestinationOrderKind::BY_RECEPTION_TIMESTAMP.

Detailed Description

Controls the logical order of updates to the same instance by a dds::pub::Publisher.

Entity:

dds::topic::Topic, dds::sub::DataReader, dds::pub::DataWriter

Status:

dds::core::status::StatusMask::offered_incompatible_qos(), dds::core::status::StatusMask::requested_incompatible_qos()

Properties:

RxO = YES
Changeable = UNTIL ENABLE

Usage

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. So different DataReaders may not receive the same "last" value when DataWriters stop sending data.

This QoS policy controls how each subscriber resolves the final value of a data instance that is written by multiple dds::pub::DataWriter entities (which may be associated with different dds::pub::Publisher entities) running on different nodes.

The default setting, dds::core::policy::DestinationOrderKind::BY_RECEPTION_TIMESTAMP, indicates that (assuming the OWNERSHIP_STRENGTH policy allows it) the latest received value for the instance should be the one whose value is kept. That is, data will be delivered by a dds::sub::DataReader in the order in which it was received (which may lead to inconsistent final values).

The setting dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP indicates that (assuming the OWNERSHIP_STRENGTH allows it, within each instance) the source_timestamp of the change shall be used to determine the most recent information. That is, data will be delivered by a dds::sub::DataReader in the order in which it was sent. If data arrives on the network with a source timestamp that is later than the source timestamp of the last data delivered, the new data will be dropped. This 'by source timestamp' ordering therefore works best when system clocks are relatively synchronized among writing machines.

When using dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP, not all data sent by multiple dds::pub::DataWriter entities may be delivered to a dds::sub::DataReader and not all DataReaders will see the same data sent by DataWriters. However, all DataReaders will see the same "final" data when DataWriters "stop" sending data. This is the only setting that, in the case of concurrently publishing dds::pub::DataWriter entities updating the same instance of a shared-ownership topic, ensures all subscribers will end up with the same final value for the instance.

This QoS 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.

Compatibility

The value offered is considered compatible with the value requested if and only if the inequality offered kind >= requested kind evaluates to 'TRUE'. For the purposes of this inequality, the values of dds::core::policy::DestinationOrder::kind are considered ordered such that dds::core::policy::DestinationOrderKind::BY_RECEPTION_TIMESTAMP < dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP

Constructor & Destructor Documentation

dds::core::policy::DestinationOrder::DestinationOrder ( )

inline

Creates the default policy.

dds::core::policy::DestinationOrder::DestinationOrder ( dds::core::policy::DestinationOrderKind  the_kind )

inlineexplicit

Creates a policy with the specified destination order kind.

Member Function Documentation

DestinationOrder& dds::core::policy::DestinationOrder::kind ( dds::core::policy::DestinationOrderKind  the_kind )

inline

Sets the destination order kind.

[default] dds::core::policy::DestinationOrderKind::BY_RECEPTION_TIMESTAMP,

dds::core::policy::DestinationOrderKind dds::core::policy::DestinationOrder::kind ( ) const

inline

Getter (see the setter with the same name)

static DestinationOrder dds::core::policy::DestinationOrder::SourceTimestamp ( )

inlinestatic

Creates a DestinationOrder with DestinationOrderKind::BY_SOURCE_TIMESTAMP.

static DestinationOrder dds::core::policy::DestinationOrder::ReceptionTimestamp ( )

inlinestatic

Creates a DestinationOrder with DestinationOrderKind::BY_RECEPTION_TIMESTAMP.

DestinationOrderImpl & scope

(

rti::core::policy::DestinationOrderScopeKind

the_scope

)

<<extension>> Sets the destination order scope

Indicates if tolerance check and the current sample's timestamp is computed based on instance or topic basis.
[default] dds::core::policy::DestinationOrderScopeKind::INSTANCE

rti::core::policy::DestinationOrderScopeKind scope

(

)

const

<<extension>> Getter (see the setter with the same name)

dds::core::policy::DestinationOrder & source_timestamp_tolerance

(

const dds::core::Duration &

ms

)

<<extension>> Sets the allowed tolerance between source timestamps of consecutive samples.

When a dds::pub::DataWriter sets dds::core::policy::DestinationOrderKind to dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP, when writing a sample, its timestamp must not be less than the timestamp of the previously written sample. However, if it is less than the timestamp of the previously written sample but the difference is less than this tolerance, the sample will use the previously written sample's timestamp as its timestamp. Otherwise, if the difference is greater than this tolerance, the write will fail.

When a dds::sub::DataReader sets dds::core::policy::DestinationOrderKind to dds::core::policy::DestinationOrderKind::BY_SOURCE_TIMESTAMP, the dds::sub::DataReader will accept a sample only if the source timestamp is no farther in the future from the reception timestamp than this tolerance. Otherwise, the sample is rejected.

[default] 100 milliseconds for dds::pub::DataWriter, 30 seconds for dds::sub::DataReader and when default-constructed

dds::core::Duration source_timestamp_tolerance

(

)

const

<<extension>> Getter (see the setter with the same name)