4.2 QosPolicies

Connext DDS’s behavior is controlled by the Quality of Service (QoS) policies of the data communication Entities (DomainParticipant, Topic, Publisher, Subscriber, DataWriter, and DataReader) used in your applications. This section summarizes each of the QosPolicies that you can set for the various Entities.

The QosPolicy class is the abstract base class for all the QosPolicies. It provides the basic mechanism for an application to specify quality of service parameters. Table 4.2 QosPolicies lists each supported QosPolicy (in alphabetical order), provides a summary, and points to a section in the manual that provides further details.

The detailed description of a QosPolicy that applies to multiple Entities is provided in the first chapter that discusses an Entity whose behavior the QoS affects. Otherwise, the discussion of a QosPolicy can be found in the chapter of the particular Entity to which the policy applies. As you will see in the detailed description sections, all QosPolicies have one or more parameters that are used to configure the policy. The how’s and why’s of tuning the parameters are also discussed in those sections.

As first discussed in 2.7.1 Controlling Behavior with Quality of Service (QoS) Policies, QosPolicies may interact with each other, and certain values of QosPolicies can be incompatible with the values set for other policies.

The set_qos() operation will fail if you attempt to specify a set of values would result in an inconsistent set of policies. To indicate a failure, set_qos() will return INCONSISTENT_POLICY. 4.2.1 QoS Requested vs. Offered Compatibility—the RxO Property provides further information on QoS compatibility within an Entity as well as across matching Entities, as does the discussion/reference section for each QosPolicy listed in Table 4.2 QosPolicies.

The values of some QosPolicies cannot be changed after the Entity is created or after the Entity is enabled. Others may be changed at any time. The detailed section on each QosPolicy states when each policy can be changed. If you attempt to change a QosPolicy after it becomes immutable (because the associated Entity has been created or enabled, depending on the policy), set_qos() will fail with a return code of IMMUTABLE_POLICY.

Table 4.2 QosPolicies

QosPolicy

Summary

Asynchronous-
Publisher

Configures the mechanism that sends user data in an external middleware thread. See 7.4.1 ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension).

Availability

This QoS policy is used in the context of two features:

For a Collaborative DataWriter, specifies the group of DataWriters expected to collaboratively provide data and the timeouts that control when to allow data to be available that may skip DDS samples.

For a Durable Subscription, configures a set of Durable Subscriptions on a DataWriter.

See 7.5.1 AVAILABILITY QosPolicy (DDS Extension).

Batch

Specifies and configures the mechanism that allows Connext DDS to collect multiple DDS data samples to be sent in a single network packet, to take advantage of the efficiency of sending larger packets and thus increase effective throughput. See 7.5.2 BATCH QosPolicy (DDS Extension).

Database

Various settings and resource limits used by Connext DDS to control its internal database. See 9.5.1 DATABASE QosPolicy (DDS Extension).

DataReaderProtocol

This QosPolicy configures the Connext DDS on-the-network protocol, RTPS. See 8.6.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension).

DataReaderResourceLimits

Various settings that configure how DataReaders allocate and use physical memory for internal resources. See 8.6.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension).

DataRepresentation

Specifies which versions of the Extended Common Data Representation (CDR) are offered and requested.

A DataWriter offers a single representation, which indicates the CDR version the DataWriter uses to serialize its data. A DataReader requests one or more representations, which indicate the CDR versions the DataReader accepts.

See 7.5.3 DATA_REPRESENTATION QosPolicy.

DataTag

This QosPolicy can be used to associate a set of tags in the form of (name, value) pairs with a DataReader or DataWriter. The Access Control plugin may use these tags to determine publish and subscribe permissions. See 7.5.4 DATATAG QosPolicy.

DataWriterProtocol

This QosPolicy configures the Connext DDS on-the-network protocol, RTPS. See 7.5.5 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension).

DataWriterResourceLimits

Controls how many threads can concurrently block on a write() call of this DataWriter. Also controls the number of batches managed by the DataWriter and the instance-replacement kind used by the DataWriter. See 7.5.6 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension).

Deadline

For a DataReader, specifies the maximum expected elapsed time between arriving DDS data samples.

For a DataWriter, specifies a commitment to publish DDS samples with no greater elapsed time between them.

See 7.5.7 DEADLINE QosPolicy.

DestinationOrder

Controls how Connext DDS will deal with data sent by multiple DataWriters for the same topic. Can be set to "by reception timestamp" or to "by source timestamp." See 7.5.8 DESTINATION_ORDER QosPolicy.

Discovery

Configures the mechanism used by Connext DDS to automatically discover and connect with new remote applications. See 9.5.2 DISCOVERY QosPolicy (DDS Extension).

DiscoveryConfig

Controls the amount of delay in discovering Entities in the system and the amount of discovery traffic in the network. See 9.5.3 DISCOVERY_CONFIG QosPolicy (DDS Extension).

DomainParticipantResource-Limits

Various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties. See 9.5.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).

Durability

Specifies whether or not Connext DDS will store and deliver data that were previously published to new DataReaders. See 7.5.9 DURABILITY QosPolicy.

DurabilityService

Various settings to configure the external Persistence Service used by Connext DDS for DataWriters with a Durability QoS setting of Persistent Durability. See 7.5.10 DURABILITY SERVICE QosPolicy.

EntityFactory

Controls whether or not child Entities are created in the enabled state. See 7.4.2 ENTITYFACTORY QosPolicy.

EntityName

Assigns a name and role_name to an Entity. See 7.5.11 ENTITY_NAME QosPolicy (DDS Extension).

Event

Configures the DomainParticipant’s internal thread that handles timed events. See 9.5.5 EVENT QosPolicy (DDS Extension).

ExclusiveArea

Configures multi-thread concurrency and deadlock prevention capabilities. See 7.4.3 EXCLUSIVE_AREA QosPolicy (DDS Extension).

GroupData

Along with 5.2.1 TOPIC_DATA QosPolicy and 7.5.30 USER_DATA QosPolicy, this QosPolicy is used to attach a buffer of bytes to Connext DDS's discovery meta-data. See 7.4.4 GROUP_DATA QosPolicy.

History

Specifies how much data must be stored by Connext DDS for the DataWriter or DataReader. This QosPolicy affects the 7.5.21 RELIABILITY QosPolicy as well as the 7.5.9 DURABILITY QosPolicy. See 7.5.12 HISTORY QosPolicy.

LatencyBudget

Suggestion to Connext DDS on how much time is allowed to deliver data. See 7.5.13 LATENCYBUDGET QoS Policy.

Lifespan

Specifies how long Connext DDS should consider data sent by an user application to be valid. See 7.5.14 LIFESPAN QoS Policy.

Liveliness

Specifies and configures the mechanism that allows DataReaders to detect when DataWriters become disconnected or "dead." See 7.5.15 LIVELINESS QosPolicy.

Logging

Configures the properties associated with Connext DDS logging. See 9.4.1 LOGGING QosPolicy (DDS Extension).

MultiChannel

Configures a DataWriter’s ability to send data on different multicast groups (addresses) based on the value of the data. See 7.5.16 MULTI_CHANNEL QosPolicy (DDS Extension).

Ownership

Along with Ownership Strength, specifies if DataReaders for a topic can receive data from multiple DataWriters at the same time. See 7.5.17 OWNERSHIP QosPolicy.

OwnershipStrength

Used to arbitrate among multiple DataWriters of the same instance of a Topic when Ownership QoSPolicy is EXLUSIVE. See 7.5.18 OWNERSHIP_STRENGTH QosPolicy.

Partition

Adds string identifiers that are used for matching DataReaders and DataWriters for the same Topic. See 7.4.5 PARTITION QosPolicy.

Presentation

Controls how Connext DDS presents data received by an application to the DataReaders of the data. See 7.4.6 PRESENTATION QosPolicy.

Profile

Configures the way that XML documents containing QoS profiles are loaded by RTI. See 9.4.2 PROFILE QosPolicy (DDS Extension) .

Property

Stores name/value(string) pairs that can be used to configure certain parameters of Connext DDS that are not exposed through formal QoS policies. It can also be used to store and propagate application-specific name/value pairs, which can be retrieved by user code during discovery. See 7.5.19 PROPERTY QosPolicy (DDS Extension) .

PublishMode

Specifies how Connext DDS sends application data on the network. By default, data is sent in the user thread that calls the DataWriter’s write() operation. However, this QosPolicy can be used to tell Connext DDS to use its own thread to send the data. See 7.5.20 PUBLISH_MODE QosPolicy (DDS Extension).

ReaderDataLifeCycle

Controls how a DataReader manages the lifecycle of the data that it has received. See 8.6.3 READER_DATA_LIFECYCLE QoS Policy.

ReceiverPool

Configures threads used by Connext DDS to receive and process data from transports (for example, UDP sockets). See 9.5.6 RECEIVER_POOL QosPolicy (DDS Extension).

Reliability

Specifies whether or not Connext DDS will deliver data reliably. See 7.5.21 RELIABILITY QosPolicy.

ResourceLimits

Controls the amount of physical memory allocated for Entities, if dynamic allocations are allowed, and how they occur. Also controls memory usage among different instance values for keyed topics. See 7.5.22 RESOURCE_LIMITS QosPolicy.

Service

Intended for use by RTI infrastructure services. User applications should not modify its value. See 7.5.23 SERVICE QosPolicy (DDS Extension).

SystemResourceLimits

Configures DomainParticipant-independent resources used by Connext DDS. Mainly used to change the maximum number of DomainParticipants that can be created within a single process (address space). See 9.4.3 SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension).

TimeBasedFilter

Set by a DataReader to limit the number of new data values received over a period of time. See 8.6.4 TIME_BASED_FILTER QosPolicy.

TopicData

Along with Group Data QosPolicy and User Data QosPolicy, used to attach a buffer of bytes to Connext DDS's discovery meta-data. See 5.2.1 TOPIC_DATA QosPolicy.

TopicQueryDispatch

Configures the ability of a DataWriter to publish historical samples in response to a TopicQuery. See 7.5.24 TOPIC_QUERY_DISPATCH_QosPolicy (DDS Extension).

TransferMode

Configures the properties of a Zero Copy DataWriter. See 7.5.25 TRANSFER_MODE QosPolicy.

TransportBuiltin

Specifies which built-in transport plugins are used. See 9.5.7 TRANSPORT_BUILTIN QosPolicy (DDS Extension).

TransportMulticast

Specifies the multicast address on which a DataReader wants to receive its data. Can specify a port number as well as a subset of the available transports with which to receive the multicast data. See 8.6.5 TRANSPORT_MULTICAST QosPolicy (DDS Extension).

TransportMulticastMapping

Specifies the automatic mapping between a list of topic expressions and multicast address that can be used by a DataReader to receive data for a specific topic. See 9.5.8 TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension).

TransportPriority

Set by a DataWriter or DataReader to tell Connext DDS that the data being sent is a different "priority" than other data. See 7.5.26 TRANSPORT_PRIORITY QosPolicy.

TransportSelection

Allows you to select which physical transports a DataWriter or DataReader may use to send or receive its data. See 7.5.27 TRANSPORT_SELECTION QosPolicy (DDS Extension).

TransportUnicast

Specifies a subset of transports and port number that can be used by an Entity to receive data. See 7.5.28 TRANSPORT_UNICAST QosPolicy (DDS Extension).

TypeConsistencyEnforcement

Defines rules that determine whether the type used to publish a given data stream is consistent with that used to subscribe to it. See 8.6.6 TYPE_CONSISTENCY_ENFORCEMENT QosPolicy.

TypeSupport

Used to attach application-specific value(s) to a DataWriter or DataReader. These values are passed to the serialization or deserialization routine of the associated data type. Also controls whether padding bytes are set to 0 during serialization. See 7.5.29 TYPESUPPORT QosPolicy (DDS Extension).

UserData

Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext DDS's discovery meta-data. See 7.5.30 USER_DATA QosPolicy.

WireProtocol

Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See 9.5.9 WIRE_PROTOCOL QosPolicy (DDS Extension).

WriterDataLifeCycle

Controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. See 7.5.31 WRITER_DATA_LIFECYCLE QoS Policy.

© 2020 RTI