RTI Connext Modern C++ API  Version 6.1.2
dds::core::policy::ReaderDataLifecycle Class Reference

Controls how a DataReader manages the lifecycle of the data that it has received. More...

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

Public Member Functions

 ReaderDataLifecycle ()
 Creates the default policy. More...
 
 ReaderDataLifecycle (const dds::core::Duration &the_nowriter_delay, const dds::core::Duration &the_disposed_samples_delay)
 Creates an instance with the specified nowriter and disposed-samples purge delays. More...
 
ReaderDataLifecycleautopurge_nowriter_samples_delay (const dds::core::Duration &duration)
 Minimum duration for which the DataReader will maintain information regarding an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_NO_WRITERS. More...
 
dds::core::Duration autopurge_nowriter_samples_delay () const
 Getter (see setter with the same name) More...
 
ReaderDataLifecycleautopurge_disposed_samples_delay (const dds::core::Duration &duration)
 Minimum duration for which the DataReader will maintain information regarding an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_DISPOSED. More...
 
dds::core::Duration autopurge_disposed_samples_delay () const
 Getter (see setter with the same name) More...
 
dds::core::policy::ReaderDataLifecycleautopurge_disposed_instances_delay (const dds::core::Duration &duration)
 <<extension>> Minimum duration for which the DataReader will maintain an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_DISPOSED. More...
 
dds::core::Duration autopurge_disposed_instances_delay () const
 <<extension>> Getter (see setter with the same name) More...
 
dds::core::policy::ReaderDataLifecycleautopurge_nowriter_instances_delay (const dds::core::Duration &duration)
 <<extension>> Minimum duration for which the DataReader will maintain an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_NO_WRITERS. More...
 
dds::core::Duration autopurge_nowriter_instances_delay () const
 <<extension>> Getter (see setter with the same name) More...
 

Static Public Member Functions

static ReaderDataLifecycle NoAutoPurge ()
 Returns a policy where all purge delays are disabled (the default) More...
 
static ReaderDataLifecycle AutoPurgeDisposedSamples (const dds::core::Duration &duration)
 Returns a policy where only the disposed-samples purge delay is enabled with a specified duration. More...
 
static ReaderDataLifecycle AutoPurgeNoWriterSamples (const dds::core::Duration &d)
 Returns a policy where only the no-writer purge delay is enabled with a specified duration. More...
 

Detailed Description

Controls how a DataReader manages the lifecycle of the data that it has received.

When a DataReader receives data, it is stored in a receive queue for the DataReader. The user application may either take the data from the queue or leave it there.

This QoS policy controls whether or not RTI Connext will automatically remove data from the receive queue (so that user applications cannot access it afterwards) when it detects that there are no more DataWriters alive for that data. It specifies how long a dds::sub::DataReader must retain information regarding instances that have the instance_state dds::sub::status::InstanceState::not_alive_no_writers().

Note: This policy is not concerned with keeping reliable reader state or discovery information.

The dds::sub::DataReader internally maintains the samples that have not been "taken" by the application, subject to the constraints imposed by other QoS policies such as dds::core::policy::History and dds::core::policy::ResourceLimits.

The dds::sub::DataReader also maintains information regarding the identity, view_state and instance_state of data instances even after all samples have been taken. This is needed to properly compute the states when future samples arrive.

Under normal circumstances the dds::sub::DataReader can only reclaim all resources for instances for which there are no writers and for which all samples have been 'taken'. The last sample the dds::sub::DataReader will have taken for that instance will have an instance_state of either dds::sub::status::InstanceState::not_alive_no_writers() or dds::sub::status::InstanceState::not_alive_disposed() depending on whether or not the last writer that had ownership of the instance disposed it.

In the absence of READER_DATA_LIFECYCLE, this behavior could cause problems if the application forgets to take those samples. "Untaken" samples will prevent the dds::sub::DataReader from reclaiming the resources and they would remain in the dds::sub::DataReader indefinitely.

A DataReader can also reclaim all resources for instances that have an instance state of dds::sub::status::InstanceState::not_alive_disposed() and for which all DDS samples have been 'taken'. DataReaders will only reclaim resources in this situation when the autopurge_disposed_instances_delay has been set to zero.

For keyed Topics, the consideration of removing data samples from the receive queue is done on a per instance (key) basis. Thus when RTI Connext detects that there are no longer DataWriters alive for a certain key value of a Topic (an instance of the Topic), it can be configured to remove all data samples for that instance (key).

Entity:
dds::sub::DataReader
Properties:
RxO = N/A
Changeable = YES

Constructor & Destructor Documentation

◆ ReaderDataLifecycle() [1/2]

dds::core::policy::ReaderDataLifecycle::ReaderDataLifecycle ( )
inline

Creates the default policy.

◆ ReaderDataLifecycle() [2/2]

dds::core::policy::ReaderDataLifecycle::ReaderDataLifecycle ( const dds::core::Duration the_nowriter_delay,
const dds::core::Duration the_disposed_samples_delay 
)
inline

Creates an instance with the specified nowriter and disposed-samples purge delays.

Member Function Documentation

◆ autopurge_nowriter_samples_delay() [1/2]

ReaderDataLifecycle& dds::core::policy::ReaderDataLifecycle::autopurge_nowriter_samples_delay ( const dds::core::Duration duration)
inline

Minimum duration for which the DataReader will maintain information regarding an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_NO_WRITERS.

At some point after this time elapses, the dds::sub::DataReader will purge all internal information regarding the instance, any "untaken" samples will also be dropped.

[default] dds::core::Duration::infinite()

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

◆ autopurge_nowriter_samples_delay() [2/2]

dds::core::Duration dds::core::policy::ReaderDataLifecycle::autopurge_nowriter_samples_delay ( ) const
inline

Getter (see setter with the same name)

◆ autopurge_disposed_samples_delay() [1/2]

ReaderDataLifecycle& dds::core::policy::ReaderDataLifecycle::autopurge_disposed_samples_delay ( const dds::core::Duration duration)
inline

Minimum duration for which the DataReader will maintain information regarding an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_DISPOSED.

After this time elapses, the dds::sub::DataReader will purge all samples for the instance even if they have not been read by the application. This purge is done lazily when space is needed for other samples or instances.

[default] dds::core::Duration::infinite()

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

◆ autopurge_disposed_samples_delay() [2/2]

dds::core::Duration dds::core::policy::ReaderDataLifecycle::autopurge_disposed_samples_delay ( ) const
inline

Getter (see setter with the same name)

◆ NoAutoPurge()

static ReaderDataLifecycle dds::core::policy::ReaderDataLifecycle::NoAutoPurge ( )
inlinestatic

Returns a policy where all purge delays are disabled (the default)

[DEPRECATED] Use the default constructor instead

◆ AutoPurgeDisposedSamples()

static ReaderDataLifecycle dds::core::policy::ReaderDataLifecycle::AutoPurgeDisposedSamples ( const dds::core::Duration duration)
inlinestatic

Returns a policy where only the disposed-samples purge delay is enabled with a specified duration.

◆ AutoPurgeNoWriterSamples()

static ReaderDataLifecycle dds::core::policy::ReaderDataLifecycle::AutoPurgeNoWriterSamples ( const dds::core::Duration d)
inlinestatic

Returns a policy where only the no-writer purge delay is enabled with a specified duration.

◆ autopurge_disposed_instances_delay() [1/2]

dds::core::policy::ReaderDataLifecycle & autopurge_disposed_instances_delay ( const dds::core::Duration duration)

<<extension>> Minimum duration for which the DataReader will maintain an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_DISPOSED.

Note
This function is an extension, it must be called via this->extensions()

After this time elapses, when the last sample for the disposed instance is taken, the dds::sub::DataReader will keep only the minimum state about the instance.

If you do not want to keep this minimum state after the delay period, also set keep_minimum_state_for_instances to FALSE in rti::core::policy::DataReaderResourceLimits.

The only currently supported values are dds::core::Duration::zero() and dds::core::Duration::infinite(). A value of dds::core::Duration::zero() will purge an instance's state immediately after the instance state transitions to dds::sub::status::InstanceState::not_alive_disposed(), as long as all samples, including the dispose sample, associated with that instance have been 'taken'.

[default] dds::core::Duration::infinite()

◆ autopurge_disposed_instances_delay() [2/2]

dds::core::Duration autopurge_disposed_instances_delay ( ) const

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

◆ autopurge_nowriter_instances_delay() [1/2]

dds::core::policy::ReaderDataLifecycle & autopurge_nowriter_instances_delay ( const dds::core::Duration duration)

<<extension>> Minimum duration for which the DataReader will maintain an instance once its instance_state becomes InstanceStateKind::NOT_ALIVE_NO_WRITERS.

Note
This function is an extension, it must be called via this->extensions()

An instance will transition to the dds::sub::status::InstanceState::not_alive_no_writers() instance_state when all known writers for the instance have either lost liveliness or have unregistered themselves from the instance. After this time elapses, when the last sample for the instance without writers is taken, the dds::sub::DataReader will keep only the minimum state about the instance.

If you do not want to keep this minimum state after the delay period, also set keep_minimum_state_for_instances to FALSE in rti::core::policy::DataReaderResourceLimits.

The only currently supported values are dds::core::Duration::zero() and dds::core::Duration::infinite(). A value of dds::core::Duration::zero() will purge an instance's state immediately after the instance state transitions to dds::sub::status::InstanceState::not_alive_no_writers(), as long as all samples, including the no_writers sample, associated with that instance have been 'taken'.

[default] dds::core::Duration::zero()

◆ autopurge_nowriter_instances_delay() [2/2]

dds::core::Duration autopurge_nowriter_instances_delay ( ) const

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