dds::core::policy::Reliability Class Reference

Indicates the level of reliability in sample delivered that a dds::pub::DataWriter offers or a dds::sub::DataReader requests. More...

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

Public Member Functions
	Reliability ()
	Creates a best-effort policy.
	Reliability (dds::core::policy::ReliabilityKind the_kind, const dds::core::Duration &the_max_blocking_time=dds::core::Duration::from_millisecs(100))
	Creates an instance with the specified reliability kind an optionally a specific maximum blocking time.
Reliability &	kind (dds::core::policy::ReliabilityKind the_kind)
	Sets the reliability kind.
dds::core::policy::ReliabilityKind	kind () const
	Getter (see setter with the same name)
Reliability &	max_blocking_time (const dds::core::Duration &d)
	Sets the maximum time a DataWriter may block on a call to write().
dds::core::Duration	max_blocking_time () const
	Getter (see setter with the same name)
dds::core::policy::Reliability &	acknowledgment_kind (rti::core::policy::AcknowledgmentKind ack_kind)
	<<extension>> Sets the kind of reliable acknowledgment
rti::core::policy::AcknowledgmentKind	acknowledgment_kind () const
	<<extension>> Getter (see setter with the same name)

Static Public Member Functions
static Reliability	Reliable (const dds::core::Duration &max_blocking_time=dds::core::Duration::from_millisecs(100))
	Creates a policy with ReliabilityKind::RELIABLE and optionally a max blocking time.
static Reliability	BestEffort ()
	Creates a policy with ReliabilityKind::BEST_EFFORT.

Detailed Description

Indicates the level of reliability in sample delivered that a dds::pub::DataWriter offers or a dds::sub::DataReader requests.

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

This policy indicates the level of reliability requested by a dds::sub::DataReader or offered by a dds::pub::DataWriter.

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 RTI 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, rti::core::policy::ReliabilityKind::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.

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 RTI 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. RTI Connext uses a reliability protocol configured and tuned by these QoS policies: dds::core::policy::History, rti::core::policy::DataWriterProtocol, rti::core::policy::DataReaderProtocol, and dds::core::policy::ResourceLimits.

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 RTI Connext is determined by the configuration of the aforementioned QoS policies.

You can configure RTI Connext to deliver all data in the order they were sent (also known as absolute or strict reliability). Or, as a tradeoff 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). In 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.

These levels are ordered, rti::core::policy::ReliabilityKind::BEST_EFFORT < rti::core::policy::ReliabilityKind::RELIABLE. A dds::pub::DataWriter offering one level is implicitly offering all levels below.

Note: To send large data reliably, you will also need to set rti::core::policy::PublishModeKind_def::ASYNCHRONOUS. Large in this context means that the data cannot be sent as a single packet by the transport (for example, data larger than 63K when using UDP/IP).

The setting of this policy has a dependency on the setting of the RESOURCE_LIMITS policy. In case the reliability kind is set to rti::core::policy::ReliabilityKind::RELIABLE the write operation on the dds::pub::DataWriter may block if the modification would cause data to be lost or else cause one of the limits in specified in the RESOURCE_LIMITS to be exceeded. Under these circumstances, the RELIABILITY max_blocking_time configures the maximum duration the write operation may block.

If the dds::core::policy::Reliability::kind is set to rti::core::policy::ReliabilityKind::RELIABLE, data samples originating from a single dds::pub::DataWriter cannot be made available to the dds::sub::DataReader if there are previous data samples that have not been received yet due to a communication error. In other words, RTI Connext will repair the error and resend data samples as needed in order to reconstruct a correct snapshot of the dds::pub::DataWriter history before it is accessible by the dds::sub::DataReader.

If the dds::core::policy::Reliability::kind is set to rti::core::policy::ReliabilityKind::BEST_EFFORT, the service will not re-transmit missing data samples. However, for data samples originating from any one DataWriter the service will ensure they are stored in the dds::sub::DataReader history in the same order they originated in the dds::pub::DataWriter. In other words, the dds::sub::DataReader may miss some data samples, but it will never see the value of a data object change from a newer value to an older value.

See Also

dds::core::policy::History

dds::core::policy::ResourceLimits

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::Reliability::kind are considered ordered such that rti::core::policy::ReliabilityKind::BEST_EFFORT < rti::core::policy::ReliabilityKind::RELIABLE.

• The offered acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::PROTOCOL and requested acknowledgment_kind = rti::core::policy::AcknowledgmentKind_def::PROTOCOL OR offered acknowledgment_kind != rti::core::policy::AcknowledgmentKind_def::PROTOCOL.

Constructor & Destructor Documentation

dds::core::policy::Reliability::Reliability ( )

inline

Creates a best-effort policy.

dds::core::policy::Reliability::Reliability ( dds::core::policy::ReliabilityKind  the_kind, const dds::core::Duration &  the_max_blocking_time = dds::core::Duration::from_millisecs(100)  )

inline

Creates an instance with the specified reliability kind an optionally a specific maximum blocking time.

The max blocking time only applies to reliable DataWriters.

Member Function Documentation

Reliability& dds::core::policy::Reliability::kind ( dds::core::policy::ReliabilityKind  the_kind )

inline

Sets the reliability kind.

[default] rti::core::policy::ReliabilityKind::BEST_EFFORT for dds::sub::DataReader and dds::topic::Topic, rti::core::policy::ReliabilityKind::RELIABLE for dds::pub::DataWriter

dds::core::policy::ReliabilityKind dds::core::policy::Reliability::kind ( ) const

inline

Getter (see setter with the same name)

Reliability& dds::core::policy::Reliability::max_blocking_time ( const dds::core::Duration &  d )

inline

Sets the maximum time a DataWriter may block on a call to write().

This setting applies only to the case where dds::core::policy::Reliability::kind = rti::core::policy::ReliabilityKind::RELIABLE. dds::pub::DataWriter::write() is allowed to block if the dds::pub::DataWriter does not have space to store the value written. Only applies to dds::pub::DataWriter.

[default] 100 milliseconds

[range] [0,1 year] or dds::core::Duration::infinite()

See Also

dds::core::policy::ResourceLimits

dds::core::Duration dds::core::policy::Reliability::max_blocking_time ( ) const

inline

Getter (see setter with the same name)

static Reliability dds::core::policy::Reliability::Reliable ( const dds::core::Duration &  max_blocking_time = dds::core::Duration::from_millisecs(100) )

inlinestatic

Creates a policy with ReliabilityKind::RELIABLE and optionally a max blocking time.

static Reliability dds::core::policy::Reliability::BestEffort ( )

inlinestatic

Creates a policy with ReliabilityKind::BEST_EFFORT.

dds::core::policy::Reliability & acknowledgment_kind

(

rti::core::policy::AcknowledgmentKind

ack_kind

)

<<extension>> Sets the kind of reliable acknowledgment

This setting applies only to the case where dds::core::policy::Reliability::kind = rti::core::policy::ReliabilityKind::RELIABLE.

Sets the kind acknowledgments supported by a dds::pub::DataWriter and sent by dds::sub::DataReader.

[default] rti::core::policy::AcknowledgmentKind_def::PROTOCOL

rti::core::policy::AcknowledgmentKind acknowledgment_kind

(

)

const

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