RTI Connext Modern C++ API  Version 6.0.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
dds::core::policy::History Class Reference

Specifies how much historical data a dds::pub::DataWriter and a dds::sub::DataReader can store. More...

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

Public Member Functions

 History ()
 Creates a policy that keeps the last sample only.
 
 History (dds::core::policy::HistoryKind the_kind, int32_t the_depth=1)
 Creates a policy with a specific history kind and optionally a history depth.
 
Historykind (dds::core::policy::HistoryKind the_kind)
 Sets the history kind.
 
dds::core::policy::HistoryKind kind () const
 Gets the history kind.
 
int32_t depth () const
 Gets the history depth.
 
Historydepth (int32_t the_depth)
 Sets the history depth.
 
dds::core::policy::Historyrefilter (rti::core::policy::RefilterKind refilter_kind)
 <<extension>> Specifies how a writer should handle previously written samples to a new reader.
 
rti::core::policy::RefilterKind refilter () const
 <<extension>> Getter (see setter with the same name)
 

Static Public Member Functions

static History KeepAll ()
 Creates a History with HistoryKind::KEEP_ALL.
 
static History KeepLast (uint32_t depth)
 Creates a History with HistoryKind::KEEP_LAST and the specified depth.
 

Detailed Description

Specifies how much historical data a dds::pub::DataWriter and a dds::sub::DataReader can store.

This QoS policy specifies how much data must to stored by RTI Connext for a dds::pub::DataWriter or dds::sub::DataReader. It controls whether RTI Connext should deliver only the most recent value, attempt to deliver all intermediate values, or do something in between.

On the publishing side, this QoS policy controls the samples that should be maintained by the dds::pub::DataWriter on behalf of existing dds::sub::DataReader entities. The behavior with regards to a dds::sub::DataReader entities discovered after a sample is written is controlled by the DURABILITY policy.

On the subscribing side, this QoS policy controls the samples that should be maintained until the application "takes" them from RTI Connext.

Entity:
dds::topic::Topic, dds::sub::DataReader, dds::pub::DataWriter
Properties:
RxO = NO
Changeable = UNTIL ENABLE
See Also
dds::core::policy::Reliability
dds::core::policy::History

Usage

This policy controls the behavior of RTI Connext when the value of an instance changes before it is finally communicated to dds::sub::DataReader entities.

When a dds::pub::DataWriter sends data, or a dds::sub::DataReader receives data, the data sent or received is stored in a cache whose contents are controlled by this QoS policy. This QoS policy interacts with dds::core::policy::Reliability by controlling whether RTI Connext guarantees that all of the sent data is received (dds::core::policy::HistoryKind::KEEP_ALL) or if only the last N data values sent are guaranteed to be received (dds::core::policy::HistoryKind::KEEP_ALL)–this is a reduced level of reliability.

The amount of data that is sent to new DataReaders who have configured their dds::core::policy::Durability to receive previously published data is also controlled by the History QoS policy.

Note that the History QoS policy does not control the physical sizes of the send and receive queues. The memory allocation for the queues is controlled by the dds::core::policy::ResourceLimits.

If kind is dds::core::policy::HistoryKind::KEEP_LAST (the default), then RTI Connext will only attempt to keep the latest values of the instance and discard the older ones. In this case, the value of depth regulates the maximum number of values (up to and including the most current one) RTI Connext will maintain and deliver. After N values have been sent or received, any new data will overwrite the oldest data in the queue. Thus the queue acts like a circular buffer of length N.

For keyed-data, there is different behavior on the publishing and subscribing sides associated with how invalid samples representing the disposal or unregistration of an instance affect history.

On the publishing side, unregistering or disposing an instance creates an invalid sample that is accounted for in the history depth. This means that an invalid sample may replace a value that is currently being stored in the writer queue.

On the subscribing side, however, invalid samples do not count towards history depth and will not replace a value that is being stored in the reader queue.

On both the publishing and subscribing sides, there can only ever be one invalid sample per-instance and that one sample can be in different states depending on whether the instance has been disposed, unregistered, or both.

The default (and most common setting) for depth is 1, indicating that only the most recent value should be delivered.

If kind is dds::core::policy::HistoryKind::KEEP_ALL, then RTI Connext will attempt to maintain and deliver all the values of the instance to existing subscribers. The resources that RTI Connext can use to keep this history are limited by the settings of the RESOURCE_LIMITS. If the limit is reached, then the behavior of RTI Connext will depend on the RELIABILITY. If the Reliability kind is dds::core::policy::ReliabilityKind::BEST_EFFORT, then the old values will be discarded. If Reliability kind is RELIABLE, then RTI Connext will block the dds::pub::DataWriter until it can deliver the necessary old values to all subscribers.

If refilter is RefilterKind::NOTHING, then samples written before a DataReader is matched to a DataWriter are not refiltered by the DataWriter.

If refilter is RefilterKind::EVERYTHING, then all samples written before a DataReader is matched to a DataWriter are refiltered by the DataWriter when the DataReader is matched.

If refilter is RefilterKind::ON_DEMAND, then a DataWriter will only refilter samples that a DataReader requests.

Consistency

This QoS policy's depth must be consistent with the RESOURCE_LIMITS max_samples_per_instance. For these two QoS to be consistent, they must verify that depth <= max_samples_per_instance.

See Also
dds::core::policy::ResourceLimits

Constructor & Destructor Documentation

dds::core::policy::History::History ( )
inline

Creates a policy that keeps the last sample only.

dds::core::policy::History::History ( dds::core::policy::HistoryKind  the_kind,
int32_t  the_depth = 1 
)
inline

Creates a policy with a specific history kind and optionally a history depth.

The history depth doesn't apply to HistoryKind::KEEP_ALL

Member Function Documentation

History& dds::core::policy::History::kind ( dds::core::policy::HistoryKind  the_kind)
inline

Sets the history kind.

Specifies the kind of history to be kept.

[default] dds::core::policy::HistoryKind::KEEP_LAST

dds::core::policy::HistoryKind dds::core::policy::History::kind ( ) const
inline

Gets the history kind.

int32_t dds::core::policy::History::depth ( ) const
inline

Gets the history depth.

History& dds::core::policy::History::depth ( int32_t  the_depth)
inline

Sets the history depth.

Specifies the number of samples to be kept, when the kind is dds::core::policy::HistoryKind::KEEP_LAST

If a value other than 1 (the default) is specified, it should be consistent with the settings of the RESOURCE_LIMITS policy. That is:

depth <= dds::core::policy::ResourceLimits::max_samples_per_instance

When the kind is dds::core::policy::HistoryKind::KEEP_ALL, the depth has no effect. Its implied value is infinity (in practice limited by the settings of the RESOURCE_LIMITS policy).

[default] 1

[range] [1,100 million], <= dds::core::policy::ResourceLimits::max_samples_per_instance

static History dds::core::policy::History::KeepAll ( )
inlinestatic

Creates a History with HistoryKind::KEEP_ALL.

static History dds::core::policy::History::KeepLast ( uint32_t  depth)
inlinestatic

Creates a History with HistoryKind::KEEP_LAST and the specified depth.

<<extension>> Specifies how a writer should handle previously written samples to a new reader.

[default] RefilterKind::NOTHING

rti::core::policy::RefilterKind refilter ( ) const

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


RTI Connext Modern C++ API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc