RTI Connext Modern C++ API  Version 6.1.1
dds::core::policy::Presentation Class Reference

Specifies how the samples representing changes to data instances are presented to a subscribing application. More...

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

Public Member Functions

 Presentation ()
 Create an instance with the default value. More...
 
 Presentation (dds::core::policy::PresentationAccessScopeKind the_access_scope, bool the_coherent_access, bool the_ordered_access)
 Creates an instance with the specified access scope and coherent and ordered access. More...
 
Presentationaccess_scope (dds::core::policy::PresentationAccessScopeKind the_access_scope)
 Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved. More...
 
dds::core::policy::PresentationAccessScopeKind access_scope () const
 Getter (see setter with the same name) More...
 
Presentationcoherent_access (bool enable)
 Controls whether coherent access is supported within the access_scope. More...
 
bool coherent_access () const
 Getter (see setter with the same name) More...
 
Presentationordered_access (bool enable)
 Controls whether ordered access is supported within the access_scope. More...
 
bool ordered_access () const
 Getter (see setter with the same name) More...
 
dds::core::policy::Presentationdrop_incomplete_coherent_set (bool enable)
 <<extension>> Indicates whether or not a DataReader should drop samples from an incomplete coherent set for which not all the relevant samples where received. More...
 
bool drop_incomplete_coherent_set () const
 <<extension>> Getter (see setter with the same name) More...
 

Static Public Member Functions

static Presentation GroupAccessScope (bool coherent, bool ordered)
 Creates a Presentation instnace with group access scope. More...
 
static Presentation InstanceAccessScope (bool coherent, bool ordered)
 Creates a Presentation instance with instance access scope. More...
 
static Presentation TopicAccessScope (bool coherent, bool ordered)
 Creates a Presentation instance with topic access scope. More...
 

Detailed Description

Specifies how the samples representing changes to data instances are presented to a subscribing application.

This QoS policy controls the extent to which changes to data instances can be made dependent on each other and also the kind of dependencies that can be propagated and maintained by RTI Connext. Specifically, this policy affects the application's ability to:

  • specify and receive coherent changes to instances
  • specify the relative order in which changes are presented
Entity:
dds::pub::Publisher, dds::sub::Subscriber
Status:
dds::core::status::StatusMask::offered_incompatible_qos(), dds::core::status::StatusMask::requested_incompatible_qos()
Properties:
RxO = YES
Changeable = UNTIL ENABLE

Usage

A dds::sub::DataReader will usually receive data in the order that it was sent by a dds::pub::DataWriter, and the data is presented to the dds::sub::DataReader as soon as the application receives the next expected value. However, sometimes you may want a set of data for the same DataWriter or different DataWriters to be presented to the DataReader(s) only after all of the elements of the set have been received, but not before. Or you may want the data to be presented in a different order than that in which it was sent. Specifically for keyed data, you may want the middleware to present the data in keyed – or instance – order, such that samples pertaining to the same instance are presented together.

The Presentation QoS policy is a request-offered QoS policy that allows you to specify different scopes of presentation. It also controls whether or not a set of changes within the scope is delivered at the same time or can be delivered as soon as each element is received.

  • ordered_access controls whether RTI Connext will preserve the order of changes.
  • access_scope controls the granularity of the other settings. See below:

If coherent_access is set, then the access_scope set on the dds::sub::Subscriber controls the maximum extent of coherent changes. The behavior is as follows:

If ordered_access is set, then the access_scope set on the dds::sub::Subscriber controls the maximum extent to which order will be preserved by RTI Connext.

  • If access_scope is set to dds::core::policy::PresentationAccessScopeKind_def::INSTANCE (the lowest level), then the relative order of DDS samples sent by a dds::pub::DataWriter is only preserved on a per-instance basis. If two DDS samples refer to the same instance (identified by Topic and a particular value for the key), then the order in which they are stored in the dds::sub::DataReader queue is consistent with the order in which the changes occurred. However, if the two DDS samples belong to different instances, the order in which they are presented may or may not match the order in which the changes occurred. This is the case even if it is the same application thread making the changes using the same dds::pub::DataWriter.

If access_scope is set to dds::core::policy::PresentationAccessScopeKind_def::HIGHEST_OFFERED on the dds::sub::Subscriber, then the dds::sub::Subscriber will use the access_scope offered by the remote dds::pub::Publisher.

Note that this QoS policy controls the scope at which related changes are made available to the subscriber. This means the subscriber can access the changes in a coherent manner and in the proper order; however, it does not necessarily imply that the dds::sub::Subscriber will indeed access the changes in the correct order. For that to occur, the application at the subscriber end must use the proper logic in reading the dds::sub::DataReader objects.

For dds::core::policy::PresentationAccessScopeKind_def::GROUP the subscribing application must use the APIs dds::sub::CoherentAccess::CoherentAccess(), dds::sub::CoherentAccess::end() and dds::sub::find to access the changes in the proper order. If you do not use these operations, the data may not be ordered across DataWriters that belong to the same dds::pub::Publisher.

The field dds::sub::SampleInfo::coherent_set_info is set when a sample is part of a coherent set. This field provides information to identify the coherent set that a sample is part of. In addition, rti::core::CoherentSetInfo::incomplete_coherent_set indicates if a sample is part of an incomplete coherent set (one for which not all samples have been received). Coherent sets for which some of the samples are filtered out by content or time on the dds::pub::DataWriter are considered incomplete.

By default, the samples that are received from an incomplete coherent set are dropped by the DataReader(s) and they are not provided to the application. Such samples are reported as lost in the SAMPLE_LOST Status. By setting dds::core::policy::Presentation::drop_incomplete_coherent_set to false, you can change this behavior and, in this case, samples from incomplete coherent sets will be provided to the application. These samples have rti::core::CoherentSetInfo::incomplete_coherent_set set to true.

Compatibility

The value offered is considered compatible with the value requested if and only if the following conditions are met:

Constructor & Destructor Documentation

◆ Presentation() [1/2]

dds::core::policy::Presentation::Presentation ( )
inline

Create an instance with the default value.

◆ Presentation() [2/2]

dds::core::policy::Presentation::Presentation ( dds::core::policy::PresentationAccessScopeKind  the_access_scope,
bool  the_coherent_access,
bool  the_ordered_access 
)
inline

Creates an instance with the specified access scope and coherent and ordered access.

See the corresponding setters.

Member Function Documentation

◆ access_scope() [1/2]

Presentation& dds::core::policy::Presentation::access_scope ( dds::core::policy::PresentationAccessScopeKind  the_access_scope)
inline

Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.

[default] dds::core::policy::PresentationAccessScopeKind_def::INSTANCE

References rti::util::network_capture::enable().

◆ access_scope() [2/2]

dds::core::policy::PresentationAccessScopeKind dds::core::policy::Presentation::access_scope ( ) const
inline

Getter (see setter with the same name)

◆ coherent_access() [1/2]

Presentation& dds::core::policy::Presentation::coherent_access ( bool  enable)
inline

Controls whether coherent access is supported within the access_scope.

That is, the ability to group a set of changes as a unit on the publishing end such that they are received as a unit at the subscribing end.

Note: To use this feature, the DataWriter must be configured for RELIABLE communication (see dds::core::policy::ReliabilityKind_def::RELIABLE).

[default] false

◆ coherent_access() [2/2]

bool dds::core::policy::Presentation::coherent_access ( ) const
inline

Getter (see setter with the same name)

◆ ordered_access() [1/2]

Presentation& dds::core::policy::Presentation::ordered_access ( bool  enable)
inline

Controls whether ordered access is supported within the access_scope.

That is, the ability of the subscriber to see changes in the same order as they occurred on the publishing end.

[default] false

◆ ordered_access() [2/2]

bool dds::core::policy::Presentation::ordered_access ( ) const
inline

Getter (see setter with the same name)

◆ GroupAccessScope()

static Presentation dds::core::policy::Presentation::GroupAccessScope ( bool  coherent,
bool  ordered 
)
inlinestatic

Creates a Presentation instnace with group access scope.

◆ InstanceAccessScope()

static Presentation dds::core::policy::Presentation::InstanceAccessScope ( bool  coherent,
bool  ordered 
)
inlinestatic

Creates a Presentation instance with instance access scope.

◆ TopicAccessScope()

static Presentation dds::core::policy::Presentation::TopicAccessScope ( bool  coherent,
bool  ordered 
)
inlinestatic

Creates a Presentation instance with topic access scope.

◆ drop_incomplete_coherent_set() [1/2]

dds::core::policy::Presentation & drop_incomplete_coherent_set ( bool  enable)

<<extension>> Indicates whether or not a DataReader should drop samples from an incomplete coherent set for which not all the relevant samples where received.

Note that a coherent set will be considered incomplete if some of its samples are filtered by content or time on the DataWriter side.

By default, the samples that are received from an incomplete coherent set are dropped (and reported as lost) by the DataReader(s) and they are not provided to the application. By setting this parameter to false, you can change this behavior.

Samples from an incomplete coherent set have rti::core::CoherentSetInfo::incomplete_coherent_set set to true in dds::sub::SampleInfo::coherent_set_info.

[default] true

◆ drop_incomplete_coherent_set() [2/2]

bool drop_incomplete_coherent_set ( ) const

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