RTI Connext Modern C++ API
Version 5.3.0
|
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. | |
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. | |
Presentation & | access_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. | |
dds::core::policy::PresentationAccessScopeKind | access_scope () const |
Getter (see setter with the same name) | |
Presentation & | coherent_access (bool enable) |
Controls whether coherent access is supported within the access_scope. | |
bool | coherent_access () const |
Getter (see setter with the same name) | |
Presentation & | ordered_access (bool enable) |
Controls whether ordered access is supported within the access_scope. | |
bool | ordered_access () const |
Getter (see setter with the same name) | |
Static Public Member Functions | |
static Presentation | GroupAccessScope (bool coherent, bool ordered) |
Creates a Presentation instnace with group access scope. | |
static Presentation | InstanceAccessScope (bool coherent, bool ordered) |
Creates a Presentation instance with instance access scope. | |
static Presentation | TopicAccessScope (bool coherent, bool ordered) |
Creates a Presentation instance with topic access scope. | |
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:
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 dds::pub::DataWriter to be presented to the dds::sub::DataReader only after all of the elements of the set have been received. Or you may want the data to be presented in a different order than that in which it was received. 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 allows you to specify different scopes of presentation: within a dds::pub::DataWriter, across instances of a single dds::pub::DataWriter, and even across multiple DataWriters used by different writers of a publisher. 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.
coherent_access
controls whether RTI Connext will preserve the groupings of changes made by a publishing application by means of the operations dds::pub::CoherentSet::CoherentSet and dds::pub::CoherentSet::end(). 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
controls the maximum extent of coherent changes. The behavior is as follows:
access_scope
is set to dds::core::policy::PresentationAccessScopeKind_def::INSTANCE (the default), the use of dds::pub::CoherentSet::CoherentSet and dds::pub::CoherentSet::end() has no effect on how the subscriber can access the data, because with the scope limited to each instance, changes to separate instances are considered independent and thus cannot be grouped into a coherent set. access_scope
is set to dds::core::policy::PresentationAccessScopeKind_def::TOPIC, then coherent changes (indicated by their enclosure within calls to dds::pub::CoherentSet::CoherentSet and dds::pub::CoherentSet::end()) will be made available as such to each remote dds::sub::DataReader independently. That is, changes made to instances within each individual dds::pub::DataWriter will be available as coherent with respect to other changes to instances in that same dds::pub::DataWriter, but will not be grouped with changes made to instances belonging to a different dds::pub::DataWriter. If ordered_access
is set, then the access_scope
controls the maximum extent for which order will be preserved by RTI Connext.
access_scope
is set to dds::core::policy::PresentationAccessScopeKind_def::INSTANCE (the lowest level), then changes to each instance are considered unordered relative to changes to any other instance. That means that changes (creations, deletions, modifications) made to two instances are not necessarily seen in the order they occur. This is the case even if it is the same application thread making the changes using the same dds::pub::DataWriter. access_scope
is set to dds::core::policy::PresentationAccessScopeKind_def::TOPIC, changes (creations, deletions, modifications) made by a single dds::pub::DataWriter are made available to subscribers in the same order they occur. Changes made to instances though different dds::pub::DataWriter entities are not necessarily seen in the order they occur. This is the case, even if the changes are made by a single application thread using dds::pub::DataWriter objects attached to the same 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.
The value offered is considered compatible with the value requested if and only if the following conditions are met:
access_scope
>= requested access_scope
evaluates to 'TRUE' or requested access_scope
is dds::core::policy::PresentationAccessScopeKind_def::HIGHEST_OFFERED. For the purposes of this inequality, the values of access_scope
are considered ordered such that dds::core::policy::PresentationAccessScopeKind_def::INSTANCE < dds::core::policy::PresentationAccessScopeKind_def::TOPIC < dds::core::policy::PresentationAccessScopeKind_def::GROUP. coherent_access
is false, or else both offered and requested coherent_access
are true. ordered_access
is false, or else both offered and requested ordered_access
are true.
|
inline |
Create an instance with the default value.
|
inline |
Creates an instance with the specified access scope and coherent and ordered access.
See the corresponding setters.
|
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
|
inline |
Getter (see setter with the same name)
|
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::RELIABLE).
[default] false
|
inline |
Getter (see setter with the same name)
|
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
|
inline |
Getter (see setter with the same name)
|
inlinestatic |
Creates a Presentation instnace with group access scope.
|
inlinestatic |
Creates a Presentation instance with instance access scope.
|
inlinestatic |
Creates a Presentation instance with topic access scope.