46.4 PRESENTATION QosPolicy
Usually DataReaders will receive data in the order that it was sent by a DataWriter. In addition, data is presented to the DataReader as soon as the application receives the next value expected.
Sometimes, you may want a set of data for the same DataWriter or different DataWriters to be presented to the receiving DataReader(s) only after ALL the elements of the set have been received, but not before. You may also want the data to be presented in a different order than it was received. Specifically, for keyed data, you may want Connext to present the data in keyed or instance order.
The Presentation QosPolicy allows you to specify different scopes of presentation: within a DataWriter, across instances of a DataWriter, and even across different DataWriters of a Publisher. It also controls whether or not a set of changes within the scope must be delivered at the same time or delivered as soon as each element is received. The structure used is shown in Table 46.4 DDS_PresentationQosPolicy.
|
Type |
Field Name |
Description |
|
DDS_Presentation_ |
Determines the largest scope spanning the entities for which the ordered_access and coherent_access of samples can be preserved (if coherent_access and/or ordered_access are TRUE). access_scope's setting has no effect unless either coherent_access or ordered_access is set to TRUE.
|
|
|
DDS_Boolean |
Controls whether Connext will preserve the groupings of changes made by the publishing application by means of begin_coherent_changes() and end_coherent_changes().
|
|
|
DDS_Boolean |
Controls whether Connext will preserve the order of changes.
|
|
|
DDS_Boolean |
drop_incomplete_coherent_set |
Indicates whether a DataReader should drop (and report as lost) samples from an incomplete coherent set (one for which not all the samples were received):
Note that a coherent set is also considered incomplete if some of its samples are filtered by content or time on the DataWriter side. Samples from an incomplete coherent set have incomplete_coherent_set in the coherent_set_info field in the 41.6 The SampleInfo Structure set to TRUE. |
46.4.1 Coherent Access
A 'coherent set' is a set of DDS data-sample modifications that must be propagated in such a way that they are interpreted at the receiver's side as a consistent set; that is, the receiver will only be able to access the data after all the modifications in the set are available at the subscribing end.
Coherency enables a publishing application to change the value of several data-instances and have those changes be seen atomically (as a cohesive set) by the readers.
Setting coherent_access to TRUE only behaves as described in the DDS specification when the DataWriter and DataReader are configured for reliable delivery. Non-reliable DataReaders will never receive DDS samples that belong to a coherent set.
To send a coherent set of DDS data samples, the publishing application uses the Publisher’s begin_coherent_changes() and end_coherent_changes() operations (see 31.10 Writing Coherent Sets of DDS Data Samples).
If coherent_access is TRUE, then the access_scope controls the maximum extent of the coherent changes, as follows:
- If access_scope is INSTANCE, the behavior is the same as TOPIC.
- If access_scope is TOPIC, then coherent changes done by a DataWriter (indicated by their enclosure within calls to begin_coherent_changes() and end_coherent_changes()) will be made available as a unit to each remote DataReader independently. That is, changes made to instances within each individual DataWriter will be presented as a unit. They will not be grouped with changes made to instances belonging to a different DataWriter.
- If access_scope is GROUP, coherent changes made to instances through a set of DataWriters attached to a common Publisher are presented as a unit to the DataReaders within a Subscriber.
46.4.2 Ordered Access
If ordered_access is TRUE, then access_scope controls the scope of the order in which DDS samples are presented to the subscribing application, as follows:
- If access_scope is INSTANCE, the relative order of DDS samples sent by a 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 DataReader’s 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.
- If access_scope is TOPIC, the relative order of DDS samples sent by a DataWriter is preserved for all DDS samples of all instances. The coherent grouping and/or order in which DDS samples appear in the DataReader’s queue is consistent with the grouping/order in which the changes occurred in that DataWriter—even if the DDS samples affect different instances.
- If access_scope is GROUP, the scope spans all instances belonging to DataWriters within the same Publisher—even if they are instances of different topics. Changes made to instances via DataWriters attached to the same Publisher are presented to the DataReaders within a Subscriber in the same order in which they occurred.
- If access_scope is HIGHEST_OFFERED, the Subscriber will use the access scope specified by each remote Publisher.
If the Subscriber's access_scope is GROUP or HIGHEST_OFFERED and ordered_access is TRUE, the application is required to use the Subscriber's begin_access() and end_access() operations to access the DDS samples in order across DataWriters of the same group (a Publisher with access_scope of GROUP). If you do not use these operations, the data may not be ordered across DataWriters. See 39.5 Beginning and Ending Group-Ordered Access for additional details.
Ultimately, the data stored in the DataReader queue is accessed by the DataReader’s read()/take() APIs. The application does not have to access the DDS data samples in the order indicated by the combination of access_scope and ordered_access. How the application actually gets the data from the DataReader is ultimately under the control of the user code. See Chapter 41 Using DataReaders to Access Data (Read & Take) for additional details.
46.4.3 Example
Coherency is useful in cases where the grouping matters across multiple Topics of a single Publisher. For example, consider an "Aircraft State" Publisher with two DataWriters, one for a Topic representing the altitude and the other for a Topic representing the velocity vector. If both altitude and velocity are changed for a given aircraft in the producer application, it may be significant to communicate those values in a way the reader can see both together as a group; otherwise, a consumer application may, for example, erroneously interpret that an aircraft is on a collision course.
Ordered access is useful when you need to ensure that DDS samples appear on the DataReader’s queue in the order sent by one or multiple DataWriters within the same Publisher.
To illustrate the effect of the PRESENTATION QosPolicy with TOPIC and INSTANCE access scope, assume the following sequence of DDS samples was written by the DataWriter: {A1, B1, C1, A2, B2, C2}. In this example, A, B, and C represent different instances (i.e., different keys). Assume all of these DDS samples have been propagated to the DataReader’s history queue before your application invokes the read() operation. The DDS data-sample sequence returned depends on how the PRESENTATION QoS is set, as shown in Table 46.5 Effect of ordered_access for access_scope INSTANCE and TOPIC.
To illustrate the effect of a PRESENTATION QosPolicy with GROUP access_scope, assume the following sequence of DDS samples was written by two DataWriters, W1 and W2, within the same Publisher: {(W1,A1), (W2,B1), (W1,C1), (W2,A2), (W1,B2), (W2,C2)}. As in the previous example, A, B, and C represent different instances (i.e., different keys). With access_scope set to INSTANCE or TOPIC, the middleware cannot guarantee that the application will receive the DDS samples in the same order they were published by W1 and W2. With access_scope set to GROUP, the middleware is able to provide the DDS samples in order to the application as long as the read()/take() operations are invoked within a begin_access()/end_access() block (see 39.5 Beginning and Ending Group-Ordered Access).
|
PRESENTATION QoS |
Sequence retrieved via “read()”. Order sent was {(W1,A1), (W2,B1), (W1,C1), (W2,A2), (W1,B2), (W2,C2)} |
|
ordered_access = FALSE or access_scope = TOPIC or INSTANCE |
The order across DataWriters will not be preserved. DDS samples may be delivered in multiple orders. For example: {(W1,A1), (W1,C1), (W1,B2), (W2,B1), (W2,A2), (W2,C2)} {(W1,A1), (W2,B1), (W1,B2), (W1,C1), (W2,A2), (W2,C2)} |
|
ordered_access = TRUE access_scope = GROUP |
DDS samples are delivered in the same order they were published: {(W1,A1), (W2,B1), (W1,C1), (W2,A2), (W1,B2), (W2,C2)} |
46.4.4 Properties
This QosPolicy cannot be modified after the Publisher or Subscriber is enabled.
This QoS must be set compatibly between the DataWriter’s Publisher and the DataReader’s Subscriber. The compatible combinations are shown in Table 46.7 Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = False and Table 46.8 Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = True for ordered_access and Table 46.9 Valid Combinations of Presentation Coherent Access and Access Scope for coherent_access.
46.4.5 Related QosPolicies
- The 47.8 DESTINATION_ORDER QosPolicy is closely related and also affects the ordering of DDS data samples on a per-instance basis when there are multiple DataWriters.
- The 48.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension) may be used to configure the DDS sample ordering process in the Subscribers configured with GROUP or HIGHEST_OFFERED access_scope.
46.4.6 Applicable DDS Entities
46.4.7 System Resource Considerations
The use of this policy does not significantly impact the usage of resources.