Chapter 54 All QosPolicies

Connext’s behavior is controlled by the Quality of Service (QoS) policies of the Entities (DomainParticipantFactory, 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.

QosPolicies have one or more parameters that are used to configure the policy. Table 54.1 Basic QoS Policies and Table 54.1 Basic QoS Policies list each supported QosPolicy, provide a summary, and point to a section in the manual that provides further details.

QosPolicies can apply to multiple Entities; for example, the Reliability QosPolicy applies to DataWriters, DataReaders, and Topics. For QosPolicies that apply to multiple Entities, the detailed description for that QosPolicy is provided in the first chapter that discusses an Entity whose behavior is affected by that QosPolicy. Otherwise, the discussion of a QosPolicy can be found in the chapter of the particular Entity to which the policy applies. The detailed descriptions include the individual parameters that comprise the QosPolicy, as well as the how’s and why’s of tuning the parameters.

As first discussed in Chapter 11 Quality of Service (QoS), 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 that would result in an inconsistent set of policies. To indicate a failure, set_qos() will return INCONSISTENT_POLICY. 54.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 54.1 Basic QoS Policies.

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.

You may also be interested in the QoS Reference Guide.

Besides the QoS Policies, there are additional properties that you can configure through the 59.19 PROPERTY QosPolicy (DDS Extension) . These are not exposed through the formal QoS policies and are described in the Property Reference Guide.

Properties are typically added for very specific use cases and may eventually be promoted to QoS fields if and when they are found to be more generally useful in many situations. It is not necessary to be familiar with all of the possible properties. More popularly used and generally useful properties are typically documented in this User’s Manual and other documentation where their use is applicable.

Connext QoS policies are divided into Basic and Advanced (and other) categories:

Basic QoS are those policies applicable to many different use cases. They are fundamental to DDS and Connext.
Advanced QoS are applicable to a smaller subset of use cases, or provide finer-grained controls for a Basic QoS.
Additional categories help you find QoS by functionality. You can find these in the API Reference HTML documentation.

See the API Reference HTML documentation for complete QoS details, including functional categories, defaults, and other QoS attributes. (API References are here: <NDDSHOME>/doc/api/connext_dds/api_<language>) For example, click here for QoS in the Modern C++ API.

Table 54.1 Basic QoS Policies
QosPolicy	Summary
Batch	Specifies and configures the mechanism that allows Connext 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 59.2 BATCH QosPolicy (DDS Extension).
DataRepresentation	Specifies which versions of the Extended Common Data Representation (CDR) (version 1 or version 2) and which data compression setting algorithms are offered and requested for your data. See 59.3 DATA_REPRESENTATION QosPolicy.
DataWriterProtocol	This QosPolicy configures the Connext on-the-network protocol, RTPS. See 59.5 DATA_WRITER_PROTOCOL 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 59.7 DEADLINE QosPolicy.
DestinationOrder	Controls how Connext 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 59.8 DESTINATION_ORDER QosPolicy.
Discovery	Configures the mechanism used by Connext to automatically discover and connect with new remote applications. See 56.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 56.3 DISCOVERY_CONFIG QosPolicy (DDS Extension).
Durability	Specifies whether or not Connext will store and deliver data that were previously published to new DataReaders. See 59.9 DURABILITY QosPolicy.
EntityFactory	Controls whether or not child Entities are created in the enabled state. See 58.2 ENTITYFACTORY QosPolicy.
EntityName	Assigns a name and role_name to an Entity. See 59.11 ENTITY_NAME QosPolicy (DDS Extension).
History	Specifies how much data must be stored by Connext for the DataWriter or DataReader. This QosPolicy affects the 59.21 RELIABILITY QosPolicy as well as the 59.9 DURABILITY QosPolicy. See 59.12 HISTORY QosPolicy.
LatencyBudget	Suggestion to Connext on how much time is allowed to deliver data. See 59.13 LATENCYBUDGET QoS Policy.
Lifespan	Specifies how long Connext should consider data sent by an user application to be valid. See 59.14 LIFESPAN QoS Policy.
Liveliness	Specifies and configures the mechanism that allows DataReaders to detect when DataWriters become disconnected or "dead." See 59.15 LIVELINESS QosPolicy.
Logging	Configures the properties associated with Connext logging. See 55.1 LOGGING QosPolicy (DDS Extension).
Monitoring	Configures RTI Monitoring Library 2.0 to collect and distribute telemetry data (metrics and logs) associated with a Connext application, for use by the RTI Observability Framework. See 55.4 MONITORING 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 59.17 OWNERSHIP QosPolicy.
OwnershipStrength	Used to arbitrate among multiple DataWriters of the same instance of a Topic when Ownership QoSPolicy is EXLUSIVE. See 59.18 OWNERSHIP_STRENGTH QosPolicy.
Partition	Adds string identifiers that are used for matching DataReaders and DataWriters for the same Topic or for matching DomainParticipants with the same domain ID and domain tag. See 56.6 PARTITION QosPolicy.
Profile	Configures the way that XML documents containing QoS profiles are loaded by RTI. See 55.2 PROFILE QosPolicy (DDS Extension) .
Property	Stores name/value(string) pairs that can be used to configure certain parameters of Connext 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 59.19 PROPERTY QosPolicy (DDS Extension) .
PublishMode	Specifies how Connext 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 to use its own thread to send the data. See 59.20 PUBLISH_MODE QosPolicy (DDS Extension).
Reliability	Specifies whether or not Connext will deliver data reliably. See 59.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 59.22 RESOURCE_LIMITS QosPolicy.
TimeBasedFilter	Set by a DataReader to limit the number of new data values received over a period of time. See 60.4 TIME_BASED_FILTER QosPolicy.
TopicQueryDispatch	Configures the ability of a DataWriter to publish historical samples in response to a TopicQuery. See 59.24 TOPIC_QUERY_DISPATCH_QosPolicy (DDS Extension).
TransportBuiltin	Specifies which built-in transport plugins are used. See 56.8 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 60.5 TRANSPORT_MULTICAST QosPolicy (DDS Extension).
TransportUnicast	Specifies a subset of transports and port number that can be used by an Entity to receive data. See 59.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 60.6 TYPE_CONSISTENCY_ENFORCEMENT QosPolicy.
WireProtocol	Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See 56.10 WIRE_PROTOCOL QosPolicy (DDS Extension).

Table 54.2 Advanced QoS Policies
QosPolicy	Summary
AsynchronousPublisher	Configures the mechanism that sends user data in an external middleware thread. See 58.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 59.1 AVAILABILITY QosPolicy (DDS Extension).
Database	Various settings and resource limits used by Connext to control its internal database. See 56.1 DATABASE QosPolicy (DDS Extension).
DataReaderProtocol	This QosPolicy configures the Connext on-the-network protocol, RTPS. See 60.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension).
DataReaderResourceLimits	Various settings that configure how DataReaders allocate and use physical memory for internal resources. See 60.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension).
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 59.4 DATATAG QosPolicy.
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 59.6 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension).
DataWriterTransferMode	Configures the properties of a Zero Copy DataWriter. See 59.25 DATA_WRITER_TRANSFER_MODE QosPolicy.
DomainParticipantResource-Limits	Various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties. See 56.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension).
DurabilityService	Various settings to configure the external Persistence Service used by Connext for DataWriters with a Durability QoS setting of Persistent Durability. See 59.10 DURABILITY SERVICE QosPolicy.
Event	Configures the DomainParticipant’s internal thread that handles timed events. See 56.5 EVENT QosPolicy (DDS Extension).
GroupData	Along with 57.1 TOPIC_DATA QosPolicy and 59.30 USER_DATA QosPolicy, this QosPolicy is used to attach a buffer of bytes to Connext's discovery meta-data. See 58.3 GROUP_DATA QosPolicy.
MultiChannel	Configures a DataWriter’s ability to send data on different multicast groups (addresses) based on the value of the data. See 59.16 MULTI_CHANNEL QosPolicy (DDS Extension).
Presentation	Controls how Connext presents data received by an application to the DataReaders of the data. See 58.4 PRESENTATION QosPolicy.
ReaderDataLifeCycle	Controls how a DataReader manages the lifecycle of the data that it has received. See 60.3 READER_DATA_LIFECYCLE QoS Policy.
ReceiverPool	Configures threads used by Connext to receive and process data from transports (for example, UDP sockets). See 56.7 RECEIVER_POOL QosPolicy (DDS Extension).
Service	Intended for use by RTI infrastructure services. User applications should not modify its value. See 59.23 SERVICE QosPolicy (DDS Extension).
SystemResourceLimits	Configures DomainParticipant-independent resources used by Connext. Mainly used to change the maximum number of DomainParticipants that can be created within a single process (address space). See 55.3 SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension).
TopicData	Along with Group Data QosPolicy and User Data QosPolicy, used to attach a buffer of bytes to Connext's discovery meta-data. See 57.1 TOPIC_DATA QosPolicy.
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 56.9 TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension).
TransportPriority	Set by a DataWriter or DataReader to tell Connext that the data being sent is a different "priority" than other data. See 59.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 59.27 TRANSPORT_SELECTION QosPolicy (DDS Extension).
TypeSupport (DEPRECATED1)	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 59.29 TYPESUPPORT QosPolicy (DDS Extension) (DEPRECATED).
UserData	Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext's discovery meta-data. See 59.30 USER_DATA QosPolicy.
WriterDataLifeCycle	Controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. See 59.31 WRITER_DATA_LIFECYCLE QoS Policy.