RTI Connext Modern C++ API Version 7.2.0
dds::core::policy::Durability Class Reference

Specifies whether a dds::pub::DataWriter will store and deliver previously published data samples to late-joining dds::sub::DataReader entities. More...

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

Public Member Functions

 Durability ()
 Creates the default Durability. More...
 
 Durability (dds::core::policy::DurabilityKind the_kind)
 Creates an instance with a specific durability kind. More...
 
Durabilitykind (dds::core::policy::DurabilityKind the_kind)
 Sets the Durability kind. More...
 
dds::core::policy::DurabilityKind kind () const
 Getter (see setter with the same name) More...
 
dds::core::policy::Durabilitydirect_communication (bool the_direct_communication)
 <<extension>> Indicates whether or not a transient or persistent dds::sub::DataReader should receive samples directly from a transient or persistent dds::pub::DataWriter More...
 
bool direct_communication () const
 <<extension>> Getter (see setter with the same name) More...
 
dds::core::policy::Durabilitywriter_depth (int32_t the_writer_depth)
 <<extension>> Indicates the number of samples a durable DataWriter will send to a late joining DataReader. More...
 
int32_t writer_depth () const
 <<extension>> Getter (see setter with the same name) More...
 
dds::core::policy::Durabilitystorage_settings (const rti::core::PersistentStorageSettings &the_storage_settings)
 <<extension>> Used to configure durable writer history and durable reader state. More...
 
const rti::core::PersistentStorageSettingsstorage_settings () const
 Gets the persistent storage settings by const-reference (see setter) More...
 
rti::core::PersistentStorageSettingsstorage_settings ()
 Gets the persistent storage settings by reference (see setter) More...
 

Static Public Member Functions

static Durability Volatile ()
 Creates a Durability instance with volatile kind. More...
 
static Durability TransientLocal ()
 Creates a Durability instance with trasient-local kind. More...
 
static Durability Transient ()
 Creates a Durability instance with trasient kind. More...
 
static Durability Persistent ()
 Creates a Durability instance with persistent kind. More...
 

Detailed Description

Specifies whether a dds::pub::DataWriter will store and deliver previously published data samples to late-joining dds::sub::DataReader entities.

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
See also
DURABILITY_SERVICE

Usage

It is possible for a dds::pub::DataWriter to start publishing data before all (or any) dds::sub::DataReader entities have joined the network.

Moreover, a dds::sub::DataReader that joins the network after some data has been written could potentially be interested in accessing the most current values of the data, as well as potentially some history.

This policy makes it possible for a late-joining dds::sub::DataReader to obtain previously published samples.

By helping to ensure that DataReaders get all data that was sent by DataWriters, regardless of when it was sent, using this QoS policy can increase system tolerance to failure conditions.

Note that although related, this does not strictly control what data RTI Connext will maintain internally. That is, RTI Connext may choose to maintain some data for its own purposes (e.g., flow control) and yet not make it available to late-joining readers if the DURABILITY policy is set to dds::core::policy::DurabilityKind::VOLATILE.

Transient and Persistent Durability

For the purpose of implementing the DURABILITY QoS kind TRANSIENT or PERSISTENT, RTI Connext behaves as if for each Topic that has dds::core::policy::Durability::kind of dds::core::policy::DurabilityKind::TRANSIENT or dds::core::policy::DurabilityKind::PERSISTENT there is a corresponding "built-in" dds::sub::DataReader and dds::pub::DataWriter configured with the same DURABILITY kind. In other words, it is as if somewhere in the system, independent of the original dds::pub::DataWriter, there is a built-in durable dds::sub::DataReader subscribing to that Topic and a built-in durable DataWriter re-publishing it as needed for the new subscribers that join the system. This functionality is provided by the RTI Persistence Service.

The Persistence Service can configure itself based on the QoS of your application's dds::pub::DataWriter and dds::sub::DataReader entities. For each transient or persistent dds::topic::Topic, the built-in fictitious Persistence Service dds::sub::DataReader and dds::pub::DataWriter have their QoS configured from the QoS of your application's dds::pub::DataWriter and dds::sub::DataReader entities that communicate on that dds::topic::Topic.

For a given dds::topic::Topic, the usual request/offered semantics apply to the matching between any dds::pub::DataWriter in the domain that writes the dds::topic::Topic and the built-in transient/persistent dds::sub::DataReader for that dds::topic::Topic; similarly for the built-in transient/persistent dds::pub::DataWriter for a dds::topic::Topic and any dds::sub::DataReader for the dds::topic::Topic. As a consequence, a dds::pub::DataWriter that has an incompatible QoS will not send its data to the RTI Persistence Service, and a dds::sub::DataReader that has an incompatible QoS will not get data from it.

Incompatibilities between local dds::sub::DataReader and dds::pub::DataWriter entities and the corresponding fictitious built-in transient/persistent entities cause the dds::core::status::StatusMask::requested_incompatible_qos() and dds::core::status::StatusMask::offered_incompatible_qos() to change and the corresponding Listener invocations and/or signaling of dds::core::cond::Condition objects as they would with your application's own entities.

The value of dds::core::policy::DurabilityService::service_cleanup_delay controls when RTI Persistence Service is able to remove all information regarding a data instances.

Information on a data instance is maintained until the following conditions are met:

  1. The instance has been explicitly disposed (instance_state = NOT_ALIVE_DISPOSED),

and

  1. All samples for the disposed instance have been acknowledged, including the dispose sample itself,

and

  1. A time interval longer that dds::core::policy::DurabilityService::service_cleanup_delay has elapsed since the moment RTI Connext detected that the previous two conditions were met. (Note: Only values of zero or dds::core::Duration::infinite() are currently supported for the service_cleanup_delay)

The utility of dds::core::policy::DurabilityService::service_cleanup_delay is apparent in the situation where an application disposes an instance and it crashes before it has a chance to complete additional tasks related to the disposition. Upon restart, the application may ask for initial data to regain its state and the delay introduced by the service_cleanup_delay will allow the restarted application to receive the information on the disposed instance and complete the interrupted tasks.

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 DURABILITY kind are considered ordered such that dds::core::policy::DurabilityKind::VOLATILE < dds::core::policy::DurabilityKind::TRANSIENT_LOCAL < dds::core::policy::DurabilityKind::TRANSIENT < dds::core::policy::DurabilityKind::PERSISTENT.

Constructor & Destructor Documentation

◆ Durability() [1/2]

dds::core::policy::Durability::Durability ( )
inline

Creates the default Durability.

◆ Durability() [2/2]

dds::core::policy::Durability::Durability ( dds::core::policy::DurabilityKind  the_kind)
inlineexplicit

Creates an instance with a specific durability kind.

The kind of durability.

[default] dds::core::policy::DurabilityKind::VOLATILE

Member Function Documentation

◆ kind() [1/2]

Durability & dds::core::policy::Durability::kind ( dds::core::policy::DurabilityKind  the_kind)
inline

Sets the Durability kind.

The kind of durability.

[default] dds::core::policy::DurabilityKind::VOLATILE

◆ kind() [2/2]

dds::core::policy::DurabilityKind dds::core::policy::Durability::kind ( ) const
inline

Getter (see setter with the same name)

◆ Volatile()

static Durability dds::core::policy::Durability::Volatile ( )
inlinestatic

Creates a Durability instance with volatile kind.

◆ TransientLocal()

static Durability dds::core::policy::Durability::TransientLocal ( )
inlinestatic

Creates a Durability instance with trasient-local kind.

◆ Transient()

static Durability dds::core::policy::Durability::Transient ( )
inlinestatic

Creates a Durability instance with trasient kind.

◆ Persistent()

static Durability dds::core::policy::Durability::Persistent ( )
inlinestatic

Creates a Durability instance with persistent kind.

◆ direct_communication() [1/2]

dds::core::policy::Durability & direct_communication ( bool  the_direct_communication)

<<extension>> Indicates whether or not a transient or persistent dds::sub::DataReader should receive samples directly from a transient or persistent dds::pub::DataWriter

Note
This function is an extension, it must be called via the extensions() member function

When direct_communication is set to true, a TRANSIENT or PERSISTENT dds::sub::DataReader will receive samples from both the original dds::pub::DataWriter configured with TRANSIENT or PERSISTENT durability and the dds::pub::DataWriter created by the persistence service. This peer-to-peer communication pattern provides low latency between end-points.

If the same sample is received from the original dds::pub::DataWriter and the persistence service, the middleware will discard the duplicate.

When direct_communication is set to false, a TRANSIENT or PERSISTENT dds::sub::DataReader will only receive samples from the dds::pub::DataWriter created by the persistence service. This brokered communication pattern provides a way to guarantee eventual consistency.

[default] true

◆ direct_communication() [2/2]

bool direct_communication ( ) const

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

◆ writer_depth() [1/2]

dds::core::policy::Durability & writer_depth ( int32_t  the_writer_depth)

<<extension>> Indicates the number of samples a durable DataWriter will send to a late joining DataReader.

Note
This function is an extension, it must be called via the extensions() member function

The default value, rti::core::policy::auto_writer_depth(), makes this parameter equal to the following:

The writer_depth must be <= dds::core::policy::History::depth.

writer_depth applies only to non-volatile DataWriters (those for which the kind is TRANSIENT_LOCAL, TRANSIENT, or PERSISTENT).

When rti::core::policy::Batch::enable is set to true, writer_depth acts as a minimum number of samples per instance that will be sent to late joiners, as opposed to the maximum. As long as a batch contains a single sample that falls within the writer_depth for the instance to which it belongs, then the entire batch will be sent. This means that batches sent to late-joining DataReaders may contain more samples per instance than is specified by the writer_depth QoS setting.

When a DataWriter responds to a TopicQuery, the samples that are evaluated against the TopicQuery filter are only those samples that fall within the writer_depth, not the dds::core::policy::History::depth.

Setting writer_depth on the DataReader side will be ignored.

[default] rti::core::policy::auto_writer_depth()

◆ writer_depth() [2/2]

int32_t writer_depth ( ) const

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

◆ storage_settings() [1/3]

dds::core::policy::Durability & storage_settings ( const rti::core::PersistentStorageSettings the_storage_settings)

<<extension>> Used to configure durable writer history and durable reader state.

By default, durable writer history and durable reader state are disabled. This means that a DataWriter will not persist its historical cache and a DataReader will not persist its state.

To enable durable writer history and durable reader state set rti::core::PersistentStorageSettings::enable to true.

◆ storage_settings() [2/3]

const rti::core::PersistentStorageSettings & storage_settings ( ) const

Gets the persistent storage settings by const-reference (see setter)

◆ storage_settings() [3/3]

rti::core::PersistentStorageSettings & storage_settings ( )

Gets the persistent storage settings by reference (see setter)