Quality of Service

Quality of Service (QoS) policies are sets of requested policies for how entities should behave. Each policy defines a structure to specify its data. Each entity supports a subset of the policies and defines a QoS structure that is composed of the supported policy structures. The set of allowable policies for a given entity is constrained by the policy structures nested in its QoS structure. For example, the Publisher’s QoS structure is defined in the specification’s IDL as follows:

module DDS {
  struct PublisherQos {
   PresentationQosPolicy presentation;
   PartitionQosPolicy partition;
   GroupDataQosPolicy group_data;
   EntityFactoryQosPolicy entity_factory;
 };
};

Setting policies is as simple as obtaining a structure with the default values already set, modifying the individual policy structures as necessary, and then applying the QoS structure to an entity (usually when it is created). See Default QoS Policy Values for examples of how to obtain the default QoS policies for various entity types.

Changing QoS Policies

Applications can change the QoS of any entity by calling the set_qos() operation on the entity. If the QoS policy values are either invalid or have conflicting polices, then set_qos() returns DDS::RETCODE_INCONSISTENT_POLICY. If the application attempts to change a QoS policy that is immutable (not changeable), then set_qos() returns DDS::RETCODE_IMMUTABLE_POLICY.

If the set_qos is successful, existing associations are removed if they are no longer compatible and new associations are added if they become compatible. The policies specify if they are mutable or not and how they affect associations. The application can detect failed associations caused by incompatible QoS using Offered Incompatible QoS Status for writers and Requested Incompatible QoS Status for readers.

Default QoS Policy Values

Applications obtain the default QoS policies for an entity by instantiating a QoS structure of the appropriate type for the entity and passing it by reference to the appropriate get_default_entity_qos() operation on the appropriate factory entity. (For example, you would use a domain participant to obtain the default QoS for a publisher or subscriber.) The following examples illustrate how to obtain the default policies for publisher, subscriber, topic, domain participant, data writer, and data reader.

// Get default Publisher QoS from a DomainParticipant:
DDS::PublisherQos pub_qos;
DDS::ReturnCode_t ret;
ret = domain_participant->get_default_publisher_qos(pub_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default publisher QoS" << std::endl;
}

// Get default Subscriber QoS from a DomainParticipant:
DDS::SubscriberQos sub_qos;
ret = domain_participant->get_default_subscriber_qos(sub_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default subscriber QoS" << std::endl;
}

// Get default Topic QoS from a DomainParticipant:
DDS::TopicQos topic_qos;
ret = domain_participant->get_default_topic_qos(topic_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default topic QoS" << std::endl;
}

// Get default DomainParticipant QoS from a DomainParticipantFactory:
DDS::DomainParticipantQos dp_qos;
ret = domain_participant_factory->get_default_participant_qos(dp_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default participant QoS" << std::endl;
}

// Get default DataWriter QoS from a Publisher:
DDS::DataWriterQos dw_qos;
ret = pub->get_default_datawriter_qos(dw_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default data writer QoS" << std::endl;
}

// Get default DataReader QoS from a Subscriber:
DDS::DataReaderQos dr_qos;
ret = sub->get_default_datareader_qos(dr_qos);
if (DDS::RETCODE_OK != ret) {
  std::cerr << "Could not get default data reader QoS" << std::endl;
}

Policies

Liveliness QoS

The liveliness QoS policy controls when and how the service determines whether participants are considered “alive”, meaning they are still reachable and active. This policy applies to the topic, data reader, and data writer entities via the liveliness member of their respective QoS structures. Setting this policy on a topic means it is in effect for all data readers and data writers on that topic.

Important

This policy is immutable and affects association.

IDL:

enum LivelinessQosPolicyKind {
  AUTOMATIC_LIVELINESS_QOS,
  MANUAL_BY_PARTICIPANT_LIVELINESS_QOS,
  MANUAL_BY_TOPIC_LIVELINESS_QOS
};

struct LivelinessQosPolicy {
  LivelinessQosPolicyKind kind;
  Duration_t lease_duration;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	kind lease_duration.sec lease_duration.nanosec	AUTOMATIC_LIVELINESS_QOS DURATION_INFINITE_SEC DURATION_INFINITE_NSEC

Specification: DDS v1.4 2.2.3.11 LIVELINESS

The kind member setting indicates whether liveliness is asserted automatically by the service or manually by the specified entity. A setting of AUTOMATIC_LIVELINESS_QOS means that the service will send a liveliness indication if the participant has not sent any network traffic for the lease_duration. The MANUAL_BY_PARTICIPANT_LIVELINESS_QOS or MANUAL_BY_TOPIC_LIVELINESS_QOS setting means the specified entity (data writer for the “by topic” setting or domain participant for the “by participant” setting) must either write a sample or manually assert its liveliness within a specified heartbeat interval. The desired heartbeat interval is specified by the lease_duration member. The default lease duration is a pre-defined infinite value, which disables any liveliness testing.

To manually assert liveliness without publishing a sample, the application must call the assert_liveliness() operation on the data writer (for the “by topic” setting) or on the domain participant (for the “by participant” setting) within the specified heartbeat interval.

Data writers specify (offer) their own liveliness criteria and data readers specify (request) the desired liveliness of their writers. Writers that are not heard from within the lease duration (either by writing a sample or by asserting liveliness) cause a change in the LIVELINESS_CHANGED_STATUS communication status and notification to the application (e.g., by calling the data reader listener’s on_liveliness_changed() callback operation or by signaling any related wait sets).

This policy is considered during the establishment of associations between data writers and data readers. The value of both sides of the association must be compatible in order for an association to be established. Compatibility is determined by comparing the data reader’s requested liveliness with the data writer’s offered liveliness. Both the kind of liveliness (automatic, manual by topic, manual by participant) and the value of the lease duration are considered in determining compatibility. The writer’s offered kind of liveliness must be greater than or equal to the reader’s requested kind of liveliness. The liveliness kind values are ordered as follows:

MANUAL_BY_TOPIC_LIVELINESS_QOS >
MANUAL_BY_PARTICIPANT_LIVELINESS_QOS >
AUTOMATIC_LIVELINESS_QOS

In addition, the writer’s offered lease duration must be less than or equal to the reader’s requested lease duration. Both of these conditions must be met for the offered and requested liveliness policy settings to be considered compatible and the association established.

Reliability QoS

The reliability QoS policy applies to the topic, data reader, and data writer entities via the reliability member of their respective QoS structures. This policy controls how data readers and writers treat the samples they process.

Important

This policy is immutable and affects association.

IDL:

enum ReliabilityQosPolicyKind {
  BEST_EFFORT_RELIABILITY_QOS,
  RELIABLE_RELIABILITY_QOS
};

struct ReliabilityQosPolicy {
  ReliabilityQosPolicyKind kind;
  Duration_t max_blocking_time;
};

Applicable entities	Members	Default values
Topic and DataReader	kind max_blocking_time.sec max_blocking_time.nanosec	BEST_EFFORT_RELIABILITY_QOS DURATION_INFINITE_SEC DURATION_INFINITE_NSEC
DataWriter	kind max_blocking_time.sec max_blocking_time.nanosec	RELIABLE_RELIABILITY_QOS [1] 0 100000000 (100 ms)

Specification: DDS v1.4 2.2.3.14 RELIABILITY

The “best effort” value (BEST_EFFORT_RELIABILITY_QOS) makes no promises as to the reliability of the samples and could be expected to drop samples under some circumstances. The “reliable” value (RELIABLE_RELIABILITY_QOS) indicates that the service should eventually deliver all values to eligible data readers.

The max_blocking_time member of this policy is used when the History QoS policy is set to “keep all” and the writer is unable to proceed because of Resource Limits QoS. When this situation occurs and the writer blocks for more than the specified time, then the write fails with a DDS::RETCODE_TIMEOUT return code. The default for this policy for data readers and topics is “best effort”, while the default value for data writers is “reliable”.

This policy is considered during the creation of associations between data writers and data readers. The value of both sides of the association must be compatible in order for an association to be created. The reliability kind of data writer must be greater than or equal to the value of data reader. In other words, all combinations are valid except that a reliable reader can only associate with a reliable writer, not a “best effort” one.

History QoS

The history QoS policy determines how samples are held in the data writer and data reader for a particular instance. For data writers these samples are held until the publisher retrieves them and successfully sends them to all connected subscribers. For data readers these samples are held until taken by the application. This policy applies to the topic, data reader, and data writer entities via the history member of their respective QoS structures.

Important

This policy is immutable and does not affect association.

IDL:

enum HistoryQosPolicyKind {
  KEEP_LAST_HISTORY_QOS,
  KEEP_ALL_HISTORY_QOS
};

struct HistoryQosPolicy {
  HistoryQosPolicyKind kind;
  long depth;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	kind depth	KEEP_LAST_HISTORY_QOS 1

Specification: DDS v1.4 2.2.3.18 HISTORY

The “keep all” value (KEEP_ALL_HISTORY_QOS) specifies that all possible samples for that instance should be kept. When “keep all” is specified and the number of unread samples is equal to the Resource Limits QoS field of max_samples_per_instance then any incoming samples are rejected.

The “keep last” value (KEEP_LAST_HISTORY_QOS) specifies that only the last depth values should be kept. When a data writer contains depth samples of a given instance, a write of new samples for that instance are queued for delivery and the oldest unsent samples are discarded. When a data reader contains depth samples of a given instance, any incoming samples for that instance are kept and the oldest samples are discarded.

Durability QoS

The durability QoS policy controls whether data writers should maintain samples after they have been sent to known subscribers. This policy applies to the topic, data reader, and data writer entities via the durability member of their respective QoS structures.

Important

This policy is immutable and affects association.

IDL:

enum DurabilityQosPolicyKind {
  VOLATILE_DURABILITY_QOS,         // Least Durability
  TRANSIENT_LOCAL_DURABILITY_QOS,
  TRANSIENT_DURABILITY_QOS,
  PERSISTENT_DURABILITY_QOS        // Greatest Durability
};

struct DurabilityQosPolicy {
  DurabilityQosPolicyKind kind;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	kind	VOLATILE_DURABILITY_QOS

Specification: DDS v1.4 2.2.3.4 DURABILITY

A durability kind of VOLATILE_DURABILITY_QOS means samples are discarded after being sent to all known subscribers. As a side effect, subscribers cannot recover samples sent before they connect.

A durability kind of TRANSIENT_LOCAL_DURABILITY_QOS means that data readers that are associated/connected with a data writer will be sent all of the samples in the data writer’s history.

A durability kind of TRANSIENT_DURABILITY_QOS means that samples outlive a data writer and last as long as the process is alive. The samples are kept in memory, but are not persisted to permanent storage. A data reader subscribed to the same topic and partition within the same domain will be sent all of the cached samples that belong to the same topic/partition.

A durability kind of PERSISTENT_DURABILITY_QOS provides basically the same functionality as transient durability except the cached samples are persisted and will survive process destruction.

When transient or persistent durability is specified, the Durability Service QoS QoS policy specifies additional tuning parameters for the durability cache.

The durability policy is considered during the creation of associations between data writers and data readers. The value of both sides of the association must be compatible in order for an association to be created. The durability kind value of the data writer must be greater than or equal to the corresponding value of the data reader. The durability kind values are ordered as follows:

PERSISTENT_DURABILITY_QOS >
TRANSIENT_DURABILITY_QOS >
TRANSIENT_LOCAL_DURABILITY_QOS >
VOLATILE_DURABILITY_QOS

Durability Service QoS

The durability service QoS policy controls deletion of samples in the transient or persistent durability caches. This policy applies to the topic and data writer entities via the durability_service member of their respective QoS structures and provides a way to specify History QoS and Resource Limits QoS for the sample cache.

Important

This policy is immutable and does not affect association.

IDL:

struct DurabilityServiceQosPolicy {
  Duration_t              service_cleanup_delay;
  HistoryQosPolicyKind    history_kind;
  long                    history_depth;
  long                    max_samples;
  long                    max_instances;
  long                    max_samples_per_instance;
};

Applicable entities	Members	Default values
Topic and DataWriter	service_cleanup_delay.sec service_cleanup_delay.nanosec history_kind history_depth max_samples max_instances max_samples_per_instance	DURATION_ZERO_SEC DURATION_ZERO_NSEC KEEP_LAST_HISTORY_QOS 1 LENGTH_UNLIMITED LENGTH_UNLIMITED LENGTH_UNLIMITED

Specification: DDS v1.4 2.2.3.5 DURABILITY_SERVICE

The members are analogous to, although independent of, those found in the History QoS and Resource Limits QoS policies. The service_cleanup_delay can be set to a desired value. By default, it is set to zero, which means never clean up cached samples.

Resource Limits QoS

The resource limits determines the amount of resources the service can consume in order to meet the requested QoS. This policy applies to the topic, data reader, and data writer entities via the resource_limits member of their respective QoS structures.

Important

This policy is immutable and does not affect association.

IDL:

struct ResourceLimitsQosPolicy {
  long max_samples;
  long max_instances;
  long max_samples_per_instance;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	max_samples max_instances max_samples_per_instance	LENGTH_UNLIMITED LENGTH_UNLIMITED LENGTH_UNLIMITED

Specification: DDS v1.4 2.2.3.19 RESOURCE_LIMITS

The max_samples member specifies the maximum number of samples a single data writer or data reader can manage across all of its instances. The max_instances member specifies the maximum number of instances that a data writer or data reader can manage. The max_samples_per_instance member specifies the maximum number of samples that can be managed for an individual instance in a single data writer or data reader.

Resources are used by the data writer to queue samples written to the data writer but not yet sent to all data readers because of backpressure from the transport. Resources are used by the data reader to queue samples that have been received, but not yet read/taken from the data reader.

Partition QoS

The partition QoS policy allows the creation of logical partitions within a domain. Data readers and data writers can only be associated if they have at least one matched partition string. This policy applies to the publisher and subscriber entities via the partition member of their respective QoS structures.

Important

This policy is mutable and affects association.

IDL:

struct PartitionQosPolicy {
  StringSeq name;
};

Applicable entities	Members	Default values
Publisher and Subscriber	name	(empty sequence)

Specification: DDS v1.4 2.2.3.13 PARTITION

The default partition name is an empty string and causes the entity to participate in the default partition. The partition names may contain wildcard characters as they are Fnmatch Expressions.

The establishment of data reader and data writer associations depends on matching partition strings on the publication and subscription ends. Failure to match partitions is not considered a failure and does not trigger any callbacks or set any status values.

Deadline QoS

The deadline QoS policy allows the application to detect when samples are not written or read within a specified amount of time. This policy applies to the topic, data writer, and data reader entities via the deadline member of their respective QoS structures.

Important

This policy is mutable and affects association.

IDL:

struct DeadlineQosPolicy {
  Duration_t period;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	period.sec period.nanosec	DURATION_INFINITE_SEC DURATION_INFINITE_NSEC

Specification: DDS v1.4 2.2.3.7 DEADLINE

The default value of the period member is infinite, which requires no behavior. When this policy is set to a finite value, then the data writer monitors the changes to data made by the application and indicates failure to honor the policy by setting the corresponding status condition and triggering the on_offered_deadline_missed() listener callback. A data reader that detects that the data has not changed before the period has expired sets the corresponding status condition and triggers the on_requested_deadline_missed() listener callback.

This policy is considered during the creation of associations between data writers and data readers. The value of both sides of the association must be compatible in order for an association to be created. The deadline period of the data reader must be greater than or equal to the corresponding value of data writer.

The value of this policy may change after the associated entity is enabled. In the case where the policy of a data reader or data writer is made, the change is successfully applied only if the change remains consistent with the remote end of all associations in which the reader or writer is participating. If the policy of a topic is changed, it will only affect data readers and writers that are created after the change has been made. Any existing readers or writers, and any existing associations between them, will not be affected by the topic policy value change.

Lifespan QoS

The lifespan QoS policy allows the application to specify when a sample expires. Expired samples will not be delivered to subscribers. This policy applies to the topic and data writer entities via the lifespan member of their respective QoS structures.

Important

This policy is mutable and does not affect association.

IDL:

struct LifespanQosPolicy {
  Duration_t duration;
}

Applicable entities	Members	Default values
Topic and DataWriter	duration.sec duration.nanosec	DURATION_INFINITE_SEC DURATION_INFINITE_NSEC

Specification: DDS v1.4 2.2.3.16 LIFESPAN

The default value of the duration member is infinite, which means samples never expire.

Note

OpenDDS currently supports expired sample detection on the publisher side when using a Durability QoS kind other than VOLATILE_DURABILITY_QOS. The current OpenDDS implementation may not remove samples from the data writer and data reader caches when they expire after being placed in the cache.

The value of this policy may be changed at any time, but only affects data written after the change.

User Data QoS

The user data QoS policy can be used to attach arbitrary information to the created entity. It is not available to the user when using Static Discovery. This policy applies to the domain participant, data reader, and data writer entities via the user_data member of their respective QoS structures.

Important

This policy is mutable and does not affect association.

IDL:

struct UserDataQosPolicy {
  sequence<octet> value;
};

Applicable entities	Members	Default values
DomainParticipant, DataWriter, DataReader	value	(empty sequence)

Specification: DDS v1.4 2.2.3.1 USER_DATA

The value of the policy is available in respective built-in topic data. The value’s use is defined by the application. For example, the application could attach security credentials via the policy that can be used by the remote application to authenticate the source. [2]

Warning

When using DDS Security, the user data of a participant can be leaked in unsecured discovery messages. Enabling [rtps_discovery] SecureParticipantUserData will only send and provide the real user data when it can be securely sent. This is an OpenDDS-specific extension.

Topic Data QoS

The topic data QoS policy can be used to attach arbitrary information to the created topic. This policy applies to topic entities via the topic_data member of TopicQoS structures.

Important

This policy is mutable and does not affect association.

IDL:

struct TopicDataQosPolicy {
  sequence<octet> value;
};

Applicable entities	Members	Default values
Topic	value	(empty sequence)

Specification: DDS v1.4 2.2.3.2 TOPIC_DATA

The value of the topic data policy is available in data writer, data reader, and topic built-in topic data. The value’s use is defined by the application.

Group Data QoS

The group data QoS policy can be used to attach arbitrary information to the created entity. This policy applies to the publisher and subscriber entities via the group_data member of their respective QoS structures.

Important

This policy is mutable and does not affect association.

IDL:

struct GroupDataQosPolicy {
  sequence<octet> value;
};

Applicable entities	Members	Default values
Publisher and Subscriber	value	(empty sequence)

Specification: DDS v1.4 2.2.3.3 GROUP_DATA

The value of the group data policy is propagated via built-in topics using the writer built-in topic data for the publisher and the reader built-in topic data for the subscriber. The value’s use is defined by the application. This could be used to implement matching mechanisms similar to those of the Partition QoS except the decision could be made based on an application-defined policy.

Transport Priority QoS

The transport priority QoS policy is considered a hint to the transport layer to indicate at what priority to send messages. This policy applies to topic and data writer entities via the transport_priority member of their respective QoS policy structures.

Important

OpenDDS currently only implements this for the tcp and udp transports.

This policy is immutable and does not affect association. This is opposed to the DDS specification, which specifies that it’s mutable. OpenDDS does not currently support modifications of the transport priority policy values after creation of the data writer. This can be worked around by creating new data writers as different priority values are required.

IDL:

struct TransportPriorityQosPolicy {
  long value;
};

Applicable entities	Members	Default values
Topic and DataWriter	value	0

Specification: DDS v1.4 2.2.3.15 TRANSPORT_PRIORITY

Higher values indicate higher priority. OpenDDS maps the priority value directly onto thread and DiffServ codepoint values. A default priority of zero will not modify either threads or codepoints in messages.

OpenDDS will attempt to set the thread priority of the sending transport as well as any associated receiving transport. Transport priority values are mapped from zero (default) through the maximum thread priority linearly without scaling. If the lowest thread priority is different from zero, then it is mapped to the transport priority value of zero. Where priority values on a system are inverted (higher numeric values are lower priority), OpenDDS maps these to an increasing priority value starting at zero. Priority values lower than the minimum (lowest) thread priority on a system are mapped to that lowest priority. Priority values greater than the maximum (highest) thread priority on a system are mapped to that highest priority. On most systems, thread priorities can only be set when the process scheduler has been set to allow these operations. Setting the process scheduler is generally a privileged operation and will require system privileges to perform. On POSIX based systems, the system calls of sched_get_priority_min(2) and sched_get_priority_max(2) are used to determine the system range of thread priorities.

OpenDDS will attempt to set the DiffServ codepoint on the socket used to send data for the data writer if it is supported by the transport implementation. If the network hardware honors the codepoint values, higher codepoint values will result in better (faster) transport for higher priority samples. The default value of zero will be mapped to the (default) codepoint of zero. Priority values from 1 through 63 are then mapped to the corresponding codepoint values, and higher priority values are mapped to the highest codepoint value (63).

Latency Budget QoS

The latency budget QoS policy is considered a hint to the transport layer to indicate the urgency of samples being sent. This policy applies to topic, data reader, and data writer entities via the latency_budget member of their respective QoS policy structures.

Important

This policy is mutable and affects association.

IDL:

struct LatencyBudgetQosPolicy {
  Duration_t duration;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	duration.sec duration.nanosec	DURATION_ZERO_SEC DURATION_ZERO_NSEC

Specification: DDS v1.4 2.2.3.8 LATENCY_BUDGET

The default value of duration is zero indicating that the delay should be minimized. OpenDDS uses the value to bound a delay interval for reporting unacceptable delay in transporting samples from publication to subscription. This policy is used for monitoring purposes only at this time. Use Transport Priority QoS to modify the sending priority of samples.

There is an OpenDDS-specific Budget Exceeded Status that reports when the duration is exceeded.

The data writer policy value is used only for compatibility comparisons and if left at the default value of zero will result in all requested duration values from data readers being matched. The data writer policy value must be greater or equal to a data reader policy value for an association to occur or continue to exist.

Entity Factory QoS

The entity factory QoS policy controls whether entities are automatically enabled by their factories when they are created. This policy applies to domain participant factory (as a factory for domain participants), domain participant (as a factory for publishers, subscribers, and topics), publisher (as a factory for data writers), or subscriber (as a factory for data readers).

Important

This policy is mutable and does not affect association.

IDL:

struct EntityFactoryQosPolicy {
  boolean autoenable_created_entities;
};

Applicable entities	Members	Default values
DomainParticipantFactory, DomainParticipant, Publisher, and Subscriber	autoenable_created_entities	true

Specification: DDS v1.4 2.2.3.20 ENTITY_FACTORY

Applications that wish to explicitly enable entities some time after they are created should set the value of the autoenable_created_entities member of this policy to false and apply the policy to the appropriate factory entities. The application must then manually enable the entity by calling the entity’s enable() operation. One use of setting this policy to false is binding specfic transport configurations to readers and writers.

The value of this policy may be changed at any time, but this only affects entities created after the change.

Presentation QoS

The presentation QoS policy controls how changes to instances by publishers are presented to data readers. It affects the relative ordering of these changes and the scope of this ordering.

Important

This policy is immutable and affects association.

IDL:

enum PresentationQosPolicyAccessScopeKind {
  INSTANCE_PRESENTATION_QOS,
  TOPIC_PRESENTATION_QOS,
  GROUP_PRESENTATION_QOS
};

struct PresentationQosPolicy {
  PresentationQosPolicyAccessScopeKind access_scope;
  boolean coherent_access;
  boolean ordered_access;
};

Applicable entities	Members	Default values
Publisher and Subscriber	access_scope coherent_access ordered_access	INSTANCE_PRESENTATION_QOS 0 0

Specification: DDS v1.4 2.2.3.6 PRESENTATION

The scope of these changes (access_scope) specifies the level in which an application may be made aware:

• INSTANCE_PRESENTATION_QOS (the default) indicates that changes occur to instances independently. Instance access essentially acts as a no-op with respect to coherent_access and ordered_access. Setting either of these values to true has no observable affect within the subscribing application.

• TOPIC_PRESENTATION_QOS indicates that accepted changes are limited to all instances within the same data reader or data writer.

• GROUP_PRESENTATION_QOS indicates that accepted changes are limited to all instances within the same publisher or subscriber.

Coherent changes (coherent_access) allow one or more changes to an instance be made available to an associated data reader as a single change. If a data reader does not receive the entire set of coherent changes made by a publisher, then none of the changes are made available. The semantics of coherent changes are similar in nature to those found in transactions provided by many relational databases. By default, coherent_access is false.

Changes may also be made available to associated data readers in the order sent by the publisher (ordered_access). This is similar in nature to the Destination Order QoS policy, however ordered_access permits data to be ordered independently of instance ordering. By default, ordered_access is false.

Note

This policy controls the ordering and scope of samples made available to the subscriber, but the subscriber application must use the proper logic in reading samples to guarantee the requested behavior. For more details, see DDS v1.4 2.2.2.5.1.9 Data access patterns.

For a reader and writer to associate, all the following must be true:

• The writer’s access_scope must be greater or equal to the reader’s.

• The writer’s coherent_access must be false or else both the reader’s and writer’s coherent_access must both be true.

• The writer’s ordered_access must be false or else both the reader’s and writer’s ordered_access must both be true.

Destination Order QoS

The destination order QoS policy controls the order in which samples within a given instance are made available to a data reader.

Important

This policy is immutable and affects association.

IDL:

enum DestinationOrderQosPolicyKind {
  BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS,
  BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS
};

struct DestinationOrderQosPolicy {
  DestinationOrderQosPolicyKind kind;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	kind	BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS

Specification: DDS v1.4 2.2.3.17 DESTINATION_ORDER

If a History QoS depth of one (the default) is specified, the instance will reflect the most recent value written by all data writers to that instance.

The BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS value (the default) indicates that samples within an instance are ordered in the order in which they were received by the data reader. Note that samples are not necessarily received in the order sent by the same data writer. To enforce this type of ordering, the BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS value should be used.

The BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS value indicates that samples within an instance are ordered based on a timestamp provided by the data writer. It should be noted that if multiple data writers write to the same instance, care should be taken to ensure that clocks are synchronized to prevent incorrect ordering on the data reader.

For a reader and writer to associate, the writer’s kind must be greater or equal to the reader’s. In other words, if the reader is BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS, then it the writer can be either value. If the reader is BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS, then the writer must also be BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS.

Writer Data Lifecycle QoS

The writer data lifecycle QoS policy controls the lifecycle of instances managed by a DataWriter.

Important

This policy is mutable and does not affect association.

IDL:

struct WriterDataLifecycleQosPolicy {
  boolean autodispose_unregistered_instances;
};

Applicable entities	Members	Default values
DataWriter	autodispose_unregistered_instances	true

Specification: DDS v1.4 2.2.3.21 WRITER_DATA_LIFECYCLE

When autodispose_unregistered_instances is set to true (the default), a data writer disposes an instance when it is unregistered. In some cases, it may be desirable to prevent an instance from being disposed when an instance is unregistered. This policy could, for example, allow an exclusive ownership data writer to gracefully defer to the next data writer without affecting the instance state. Deleting a data writer implicitly unregisters all of its instances prior to deletion.

Reader Data Lifecycle QoS

The reader data lifecycle QoS policy controls the lifecycle of instances managed by a DataReader.

Important

This policy is mutable and does not affect association.

IDL:

struct ReaderDataLifecycleQosPolicy {
  Duration_t autopurge_nowriter_samples_delay;
  Duration_t autopurge_disposed_samples_delay;
};

Applicable entities	Members	Default values
DataReader	autopurge_nowriter_samples_delay.sec autopurge_nowriter_samples_delay.nanosec autopurge_disposed_samples_delay.sec autopurge_disposed_samples_delay.nanosec	DURATION_INFINITE_SEC DURATION_INFINITE_NSEC DURATION_INFINITE_SEC DURATION_INFINITE_NSEC

Specification: DDS v1.4 2.2.3.22 READER_DATA_LIFECYCLE

Normally, a data reader maintains data for all instances until there are no more associated data writers for the instance, the instance has been disposed, or the data has been taken by the user.

In some cases, it may be desirable to constrain the reclamation of these resources. This policy could, for example, permit a late-joining data writer to prolong the lifetime of an instance in fail-over situations.

The autopurge_nowriter_samples_delay controls how long the data reader waits before reclaiming resources once an instance transitions to the NOT_ALIVE_NO_WRITERS state. By default, autopurge_nowriter_samples_delay is infinite.

The autopurge_disposed_samples_delay controls how long the data reader waits before reclaiming resources once an instance transitions to the NOT_ALIVE_DISPOSED state. By default, autopurge_disposed_samples_delay is infinite.

Time Based Filter QoS

The time based filter QoS policy controls how often a DataReader may be interested in changes in values to an instance.

Important

This policy is mutable and does not affect association.

IDL:

struct TimeBasedFilterQosPolicy {
  Duration_t minimum_separation;
};

Applicable entities	Members	Default values
DataReader	minimum_separation.sec minimum_separation.nanosec	DURATION_ZERO_SEC DURATION_ZERO_NSEC

Specification: DDS v1.4 2.2.3.12 TIME_BASED_FILTER

An interval (minimum_separation) may be specified on the data reader. This interval defines a minimum delay between instance value changes; this permits the data reader to throttle changes without affecting the state of the associated data writer. By default, minimum_separation is zero, which indicates that no data is filtered. This QoS policy does not conserve bandwidth as instance value changes are still sent to the subscriber process. It only affects which samples are made available via the data reader.

Ownership QoS

The ownership QoS policy controls whether more than one DataWriter is able to write samples for the same instance.

Important

This policy is immutable and affects association.

IDL:

enum OwnershipQosPolicyKind {
  SHARED_OWNERSHIP_QOS,
  EXCLUSIVE_OWNERSHIP_QOS
};

struct OwnershipQosPolicy {
  OwnershipQosPolicyKind kind;
};

Applicable entities	Members	Default values
Topic, DataWriter, and DataReader	kind	SHARED_OWNERSHIP_QOS

Specification: DDS v1.4 2.2.3.9 OWNERSHIP

If the kind member is set to SHARED_OWNERSHIP_QOS, more than one data writer is allowed to update the same instance. If the kind member is set to EXCLUSIVE_OWNERSHIP_QOS, only one data writer is allowed to update a given instance (i.e., the data writer is considered to be the owner of the instance) and associated DataReaders will only see samples written by that data writer. The owner of the instance is determined by value of the Ownership Strength QoS policy; the data writer with the highest value of strength is considered the owner of the instance. Other factors may also influence ownership, such as whether the data writer with the highest strength is “alive” (as defined by the Liveliness QoS policy) and has not violated its offered publication deadline constraints (as defined by the Deadline QoS policy).

For a reader and writer to associate, the kind must be the same.

Ownership Strength QoS

The ownership strength QoS policy is used in conjunction with the Ownership QoS EXCLUSIVE_OWNERSHIP_QOS policy on DataWriters.

Important

This policy is mutable and does not affect association.

IDL:

struct OwnershipStrengthQosPolicy {
  long value;
};

Applicable entities	Members	Default values
DataWriter	value	0

Specification: DDS v1.4 2.2.3.10 OWNERSHIP_STRENGTH

The value member is used to determine which data writer is the owner of the instance. The default value is zero.

Property QoS

The property QoS policy contains sequences of key-value pairs for the DomainParticipant.

Important

This policy is mutable, but updates to properties after creating the participant might not an effect. This policy affects association indirectly through security.

IDL:

struct Property_t {
  string name;
  string value;
  boolean propagate;
};
typedef sequence<Property_t> PropertySeq;

struct BinaryProperty_t {
  string name;
  OctetSeq value;
  boolean propagate;
};
typedef sequence<BinaryProperty_t> BinaryPropertySeq;

struct PropertyQosPolicy {
  PropertySeq value;
  BinaryPropertySeq binary_value;
};

Applicable entities	Members	Default values
DomainParticipant	value binary_value	(empty sequence) (empty sequence)

Specification: DDS Security v1.1 7.2.5 PropertyQosPolicy, DomainParticipantQos, DataWriterQos, and DataReaderQos

Right now these are only used for DDS Security Configuration via Property Qos Policy.

Data Representation QoS

The data representation QoS policy defines how a DataWriter encodes samples and what encodings a DataReader will accept. This XTypes concept is explained in detail in Data Representation.

Important

This policy is immutable and affects association.

IDL:

module DDS {
  const DataRepresentationId_t XCDR_DATA_REPRESENTATION = 0;
  const DataRepresentationId_t XML_DATA_REPRESENTATION = 1;
  const DataRepresentationId_t XCDR2_DATA_REPRESENTATION = 2;

  typedef sequence<DataRepresentationId_t> DataRepresentationIdSeq;

  struct DataRepresentationQosPolicy {
    DataRepresentationIdSeq value;
  };
};

module OpenDDS {
  module DCPS {
    const DDS::DataRepresentationId_t UNALIGNED_CDR_DATA_REPRESENTATION = -12140;
  };
};

Applicable entities	Members	Default values
DataWriter using the RTPS/UDP Transport	value	(empty sequence) – interpreted as a sequence containing XCDR2_DATA_REPRESENTATION
DataReader using the RTPS/UDP Transport	value	(empty sequence) – interpreted as a sequence containing XCDR_DATA_REPRESENTATION and XCDR2_DATA_REPRESENTATION
DataWriter using other transports	value	(empty sequence) – interpreted as a sequence containing UNALIGNED_CDR_DATA_REPRESENTATION
DataReader using other transports	value	(empty sequence) – interpreted as a sequence containing XCDR_DATA_REPRESENTATION, XCDR2_DATA_REPRESENTATION, and UNALIGNED_CDR_DATA_REPRESENTATION

Specification: DDS XTypes v1.3 7.6.3.1 Data Representation QoS Policy

Warning

The default interpretation of value is OpenDDS-specific as of XTypes 1.3. The XTypes specification v1.3 specifies that it should be interpreted as a sequence containing XCDR_DATA_REPRESENTATION. This is because OpenDDS defaults to XCDR2 instead of XCDR1 when using the RTPS/UDP Transport, the use of unaligned CDR, and the desire to have readers be as compatible as possible by default. See Data Representation for details.

For a reader and writer to associate, the first value in the writer’s effective value must be contained in the reader’s effective value. Other items values in a writer’s value are ignored.

Type Consistency Enforcement QoS

The type consistency enforcement QoS policy lets the application fine-tune details of how topic types may differ between DataWriters and DataReaders. This XTypes concept is explained in detail in Type Consistency Enforcement.

Important

OpenDDS only supports this with RTPS Discovery.

This policy is immutable and affects association.

IDL:

enum TypeConsistencyKind {
  DISALLOW_TYPE_COERCION,
  ALLOW_TYPE_COERCION
};

struct TypeConsistencyEnforcementQosPolicy {
  TypeConsistencyEnforcementQosPolicyKind_t kind;
  boolean ignore_sequence_bounds;
  boolean ignore_string_bounds;
  boolean ignore_member_names;
  boolean prevent_type_widening;
  boolean force_type_validation;
};

Applicable entities	Members	Default values
DataReader	kind ignore_sequence_bounds ignore_string_bounds ignore_member_names prevent_type_widening force_type_validation	ALLOW_TYPE_COERCION true true false false false

Specification: DDS XTypes v1.3 7.6.3.4 Type Consistency Enforcement QoS Policy

Attention

OpenDDS only supports ignore_member_names. All other members should be left at their default values.

ignore_member_names defaults to false so member names (along with member IDs, see Member ID assignment) are significant for type compatibility. Changing this to true means that only member IDs are used for type compatibility.

Policy Example

The following sample code illustrates some policies being set and applied for a publisher.

DDS::DataWriterQos dw_qos;
pub->get_default_datawriter_qos (dw_qos);

dw_qos.history.kind = DDS::KEEP_ALL_HISTORY_QOS;

dw_qos.reliability.kind = DDS::RELIABLE_RELIABILITY_QOS;
dw_qos.reliability.max_blocking_time.sec = 10;
dw_qos.reliability.max_blocking_time.nanosec = 0;

dw_qos.resource_limits.max_samples_per_instance = 100;

DDS::DataWriter_var dw =
  pub->create_datawriter(topic,
                         dw_qos,
                         0,   // No listener
                         OpenDDS::DCPS::DEFAULT_STATUS_MASK);

This code creates a publisher with the following qualities:

• History QoS set to “keep all”

• Reliability QoS set to “reliable” with a maximum blocking time of 10 seconds

• The maximum samples per instance Resource Limits QoS set to 100

This means that when 100 samples are waiting to be delivered, the writer can block up to 10 seconds before returning an error code. These same QoS settings on the data reader side would mean that up to 100 unread samples are queued by the framework before any are rejected. Rejected samples are dropped and the SampleRejectedStatus is updated.

Footnotes

[1]

For OpenDDS versions, up to 2.0, the default reliability kind for data writers is best effort. For versions 2.0.1 and later, this is changed to reliable (to conform to the DDS specification).

[2]

This is an example that was given by the DDS specification. If you actually need to authenticate remote participants in a secure way, it’s highly recommended to use DDS Security.