You are here: Part 2: Core Concepts > Sending Data > Publisher/Subscriber QosPolicies > PRESENTATION QosPolicy

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 to be presented to the receiving DataReader 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 DDS 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.

There are three components to this QoS, the boolean flag coherent_access, the boolean flag ordered_access, and an enumerated setting for the access_scope. The structure used is shown in .

DDS_PresentationQosPolicy

Type

Field Name

Description

DDS_Presentation_
QosPolicyAccessScopeKind

access_scope

Controls the granularity used when coherent_access and/or ordered_access are TRUE.

If both coherent_access and ordered_access are FALSE, access_scope’s setting has no effect.

  • DDS_INSTANCE_PRESENTATION_QOS:
    Queue is ordered/sorted per instance

  • DDS_TOPIC_PRESENTATION_QOS:
    Queue is ordered/sorted per topic (across all instances)

  • DDS_GROUP_PRESENTATION_QOS:
    Queue is ordered/sorted per topic across all instances belonging to DataWriter (or DataReaders) within the same Publisher (or Subscriber). Not supported for coherent_access = TRUE.

  • DDS_HIGHEST_OFFERED_PRESENTATION_QOS: Only applies to Subscribers. With this setting, the Subscriber will use the access scope specified by each remote Publisher.

DDS_Boolean

coherent_access

Controls whether Connext DDS will preserve the groupings of changes made by the publishing application by means of begin_coherent_changes() and end_coherent_changes().

  • DDS_BOOLEAN_FALSE:Coherency is not preserved. The value of access_scope is ignored.

  • DDS_BOOLEAN_TRUE:Changes made to instances within each DataWriter will be available to the DataReader as a coherent set, based on the value of access_scope. Not supported for access_scope = GROUP.

DDS_Boolean

ordered_access

Controls whether Connext DDS will preserve the order of changes.

  • DDS_BOOLEAN_FALSE:The order of DDS samples is only preserved for each instance, not across instances. The value of access_scope is ignored.

  • DDS_BOOLEAN_TRUE:The order of DDS samples from a DataWriter is preserved, based on the value set in access_scope.

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 Writing Coherent Sets of DDS Data Samples).

If access_scope is GROUP, coherent changes made to instances through a DataWriter attached to a common Publisher are made available as a unit to remote subscribers. Coherent access with GROUP access scope is currently not supported.

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:

The data stored in the DataReader is accessed by the DataReader’s read()/take() APIs. The application does not have to access the DDS data samples in the same order as they are stored in the queue. How the application actually gets the data from the DataReader is ultimately under the control of the user code, see Using DataReaders to Access Data (Read & Take).

Example

Coherency is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the 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 .

Effect of ordered_access for access_scope INSTANCE and TOPIC

PRESENTATION QoS

Sequence retrieved via “read()”.

Order sent was {A1, B1, C1, A2, B2, C2}

Order received was {A1, A2, B1, B2, C1, C2}

ordered_access = FALSE

access_scope = <any>

{A1, A2, B1, B2, C1, C2}

ordered_access = TRUE

access_scope = INSTANCE

{A1, A2, B1, B2, C1, C2}

ordered_access = TRUE

access_scope = TOPIC

{A1, B1, C1, A2, B2, C2}

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 Beginning and Ending Group-Ordered Access).

Effect of ordered_access for access_scope GROUP

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)}

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 and for ordered_access and for coherent_access.

Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = False

{ordered_access/access_scope}

Subscriber Requests:

False/Instance

False/Topic

False/Group

False/Highest

Publisher offers:

False/Instance

4

incompatible

incompatible

4

False/Topic

4

4

incompatible

4

False/Group

4

4

4

4

True/Instance

4

incompatible

incompatible

4

True/Topic

4

4

incompatible

4

True/Group

4

4

4

4

 

Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = True

{ordered_access/access_scope}

Subscriber Requests:

True/Instance

True/Topic

True/Group

True/Highest

Publisher offers:

False/Instance

incompatible

incompatible

incompatible

incompatible

False/Topic

incompatible

incompatible

incompatible

incompatible

False/Group

incompatible

incompatible

incompatible

incompatible

True/Instance

4

incompatible

incompatible

4

True/Topic

4

4

incompatible

4

True/Group

4

4

4

4

 

Valid Combinations of Presentation Coherent Access and Access Scope

{coherent_access/access_scope}

Subscriber requests:

False/Instance

False/Topic

True/Instance

True/Topic

Publisher offers:

False/Instance

4

incompatible

incompatible

incompatible

False/Topic

4

4

incompatible

incompatible

True/Instance

4

incompatible

4

incompatible

True/Topic

4

4

4

4

Related QosPolicies

Applicable DDS Entities

System Resource Considerations

The use of this policy does not significantly impact the usage of resources.

© 2016 RTI