Specifies how the samples representing changes to data instances are presented to a subscribing application. More...
Public Attributes | |
| PresentationQosPolicyAccessScopeKind | access_scope |
| Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved. More... | |
| boolean | coherent_access |
Specifies support for coherent access. Controls whether coherent access is supported within the scope access_scope. More... | |
| boolean | ordered_access |
Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope access_scope. More... | |
| boolean | drop_incomplete_coherent_set |
| <<extension>> Indicates whether or not a com.rti.dds.subscription.DataReader should drop samples from an incomplete coherent set (one for which not all the samples were received). Such samples are reported as lost in the SAMPLE_LOST Status. More... | |
 Public Attributes inherited from QosPolicy | |
| final QosPolicyId_t | id |
| The ID of this QoS policy. More... | |
| final String | policy_name |
| The name of this QoS policy. 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
- Status:
- com.rti.dds.infrastructure.StatusKind.StatusKind.OFFERED_INCOMPATIBLE_QOS_STATUS, com.rti.dds.infrastructure.StatusKind.StatusKind.REQUESTED_INCOMPATIBLE_QOS_STATUS
- Properties:
- RxO = YES
Changeable = UNTIL ENABLE
Usage
A com.rti.dds.subscription.DataReader will usually receive data in the order that it was sent by a com.rti.dds.publication.DataWriter, and the data is presented to the com.rti.dds.subscription.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 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 DataWriter, across instances of a single 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_accesscontrols whether RTI Connext will preserve the groupings of changes made by a publishing application by means of the operations com.rti.dds.publication.Publisher.begin_coherent_changes and com.rti.dds.publication.Publisher.end_coherent_changes.
ordered_accesscontrols whether RTI Connext will preserve the order of changes.
access_scopecontrols 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:
- If
access_scopeis set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS (the default), the use of com.rti.dds.publication.Publisher.begin_coherent_changes and com.rti.dds.publication.Publisher.end_coherent_changes 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.
- If
access_scopeis set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS, then coherent changes (indicated by their enclosure within calls to com.rti.dds.publication.Publisher.begin_coherent_changes and com.rti.dds.publication.Publisher.end_coherent_changes) will be made available as such to each remote com.rti.dds.subscription.DataReader independently. That is, changes made to instances within each individual com.rti.dds.publication.DataWriter will be available as coherent with respect to other changes to instances in that same com.rti.dds.publication.DataWriter, but will not be grouped with changes made to instances belonging to a different com.rti.dds.publication.DataWriter.
- If access_scope is set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, then coherent changes made to instances through a com.rti.dds.publication.DataWriter attached to a common com.rti.dds.publication.Publisher are made available as a unit to remote subscribers.
If ordered_access is set, then the access_scope controls the maximum extent for which order will be preserved by RTI Connext.
- If
access_scopeis set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS (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 com.rti.dds.publication.DataWriter.
- If
access_scopeis set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS, changes (creations, deletions, modifications) made by a single com.rti.dds.publication.DataWriter are made available to subscribers in the same order they occur. Changes made to instances though different com.rti.dds.publication.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 com.rti.dds.publication.DataWriter objects attached to the same com.rti.dds.publication.Publisher.
- Finally, if access_scope is set to com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS, changes made to instances via com.rti.dds.publication.DataWriter entities attached to the same com.rti.dds.publication.Publisher object are made available to subscribers in the same order in which they occur.
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 com.rti.dds.subscription.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 com.rti.dds.subscription.DataReader objects.
For com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS the subscribing application must use the APIs com.rti.dds.subscription.Subscriber.begin_access, com.rti.dds.subscription.Subscriber.end_access and com.rti.dds.subscription.Subscriber.get_datareaders to access the changes in the proper order. If you do not use these operations, the data may not be ordered across DataWriters.
The field com.rti.dds.subscription.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, com.rti.dds.infrastructure.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 com.rti.dds.publication.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 com.rti.dds.infrastructure.PresentationQosPolicy.drop_incomplete_coherent_set to com.rti.dds.infrastructure.false, you can change this behavior and, in this case, samples from incomplete coherent sets will be provided to the application. These samples have com.rti.dds.infrastructure.CoherentSetInfo.incomplete_coherent_set set to com.rti.dds.infrastructure.true.
Compatibility
The value offered is considered compatible with the value requested if and only if the following conditions are met:
- the inequality offered
access_scope>= requestedaccess_scopeevaluates to 'TRUE' or requestedaccess_scopeis com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.HIGHEST_OFFERED_PRESENTATION_QOS. For the purposes of this inequality, the values ofaccess_scopeare considered ordered such that com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS < com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.TOPIC_PRESENTATION_QOS < com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.GROUP_PRESENTATION_QOS.
- requested
coherent_accessis com.rti.dds.infrastructure.false, or else both offered and requestedcoherent_accessare com.rti.dds.infrastructure.true.
- requested
ordered_accessis com.rti.dds.infrastructure.false, or else both offered and requestedordered_accessare com.rti.dds.infrastructure.true.
Member Data Documentation
◆ access_scope
| PresentationQosPolicyAccessScopeKind access_scope |
Determines the largest scope spanning the entities for which the order and coherency of changes can be preserved.
[default] com.rti.dds.infrastructure.PresentationQosPolicyAccessScopeKind.PresentationQosPolicyAccessScopeKind.INSTANCE_PRESENTATION_QOS
◆ coherent_access
| boolean coherent_access |
Specifies support for coherent access. Controls whether coherent access is supported within the scope 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 com.rti.dds.infrastructure.ReliabilityQosPolicyKind.RELIABLE_RELIABILITY_QOS).
[default] com.rti.dds.infrastructure.false
◆ ordered_access
| boolean ordered_access |
Specifies support for ordered access to the samples received at the subscription end. Controls whether ordered access is supported within the scope access_scope.
That is, the ability of the subscriber to see changes in the same order as they occurred on the publishing end.
[default] com.rti.dds.infrastructure.false
◆ drop_incomplete_coherent_set
| boolean drop_incomplete_coherent_set |
<<extension>> Indicates whether or not a com.rti.dds.subscription.DataReader should drop samples from an incomplete coherent set (one for which not all the samples were received). Such samples are reported as lost in the SAMPLE_LOST Status.
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 com.rti.dds.infrastructure.false, you can change this behavior.
Samples from an incomplete coherent set have com.rti.dds.infrastructure.CoherentSetInfo.incomplete_coherent_set set to com.rti.dds.infrastructure.true in com.rti.dds.subscription.SampleInfo.coherent_set_info.
[default] com.rti.dds.infrastructure.true