This section explains each of the DDS standard QoS Policies:
- DeadlineQosPolicy
- DestinationOrderQosPolicy
- DurabilityQosPolicy
- DurabilityServiceQosPolicy
- EntityFactoryQosPolicy
- GroupDataQosPolicy
- HistoryQosPolicy
- LatencyBudgetQosPolicy
- LifespanQosPolicy
- LivelinessQosPolicy
- OwnershipQosPolicy
- OwnershipStrengthQosPolicy
- PartitionQosPolicy
- PresentationQosPolicy
- ReaderDataLifecycleQosPolicy
- ReliabilityQosPolicy
- ResourceLimitsQosPolicy
- TimeBasedFilterQosPolicy
- TopicDataQosPolicy
- TransportPriorityQosPolicy
- UserDataQosPolicy
- WriterDataLifecycleQosPolicy
This QoS policy raises an alarm when the frequency of new samples falls below a certain threshold. It is useful for cases where data is expected to be updated periodically (see |DeadlineQosPolicy-api|).
On the publishing side, the deadline defines the maximum period in which the application is expected to supply a new sample. On the subscribing side, it defines the maximum period in which new samples should be received.
For |Topics| with keys, this QoS is applied by key. Suppose that the positions of some vehicles have to be published periodically. In that case, it is possible to set the ID of the vehicle as the key of the data type and the deadline QoS to the desired publication period.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |DeadlineQosPolicy::period-api| | |Duration_t-api| | |c_TimeInfinite-api| |
Note
This QoS Policy concerns to |Topic|, |DataReader| and |DataWriter| entities.
It can be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`deadline_compatibilityrule` for further details.
To maintain the compatibility between DeadlineQosPolicy in DataReaders and DataWriters, the offered deadline period (configured on the DataWriter) must be less than or equal to the requested deadline period (configured on the DataReader), otherwise, the entities are considered to be incompatible.
The DeadlineQosPolicy must be set consistently with the :ref:`timebasedfilterqospolicy`, which means that the deadline period must be higher or equal to the minimum separation.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_DEADLINE_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_DEADLINE
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
Multiple |DataWriters| can send messages in the same |Topic| using the same key, and on the |DataReader| side all those messages are stored within the same instance of data (see |DestinationOrderQosPolicy-api|). This QoS policy controls the criteria used to determine the logical order of those messages. The behavior of the system depends on the value of the :ref:`destinationorderqospolicykind`.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |DestinationOrderQosPolicy::kind-api| | :ref:`destinationorderqospolicykind` | |BY_RECEPTION_TIMESTAMP| |
Note
This QoS Policy concerns to Topic, DataReader and DataWriter entities.
It cannot be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`destinationorder_compatibilityrule` for further details.
There are two possible values (see |DestinationOrderQosPolicyKind-api|):
- |BY_RECEPTION_TIMESTAMP|: This indicates that the data is ordered based on the reception time at each DataReader, which means that the last received value should be the one kept. This option may cause that each DataReader ends up with a different final value, since the DataReaders may receive the data at different times.
- |BY_SOURCE_TIMESTAMP|: This indicates that the data is ordered based on the DataWriter timestamp at the time the message is sent. This option guarantees the consistency of the final value.
Both options depend on the values of the :ref:`ownershipqospolicy` and :ref:`ownershipstrengthqospolicy`, meaning that if the Ownership is set to EXCLUSIVE and the last value came from a DataWriter with low ownership strength, it will be discarded.
To maintain the compatibility between DestinationOrderQosPolicy in DataReaders and DataWriters when they have different kind values, the DataWriter kind must be higher or equal to the DataReader kind. And the order between the different kinds is:
|BY_RECEPTION_TIMESTAMP| < |BY_SOURCE_TIMESTAMP|
Table with the possible combinations:
| DataWriter kind | DataReader kind | Compatibility |
|---|---|---|
| |BY_RECEPTION_TIMESTAMP| | |BY_RECEPTION_TIMESTAMP| | Yes |
| |BY_RECEPTION_TIMESTAMP| | |BY_SOURCE_TIMESTAMP| | No |
| |BY_SOURCE_TIMESTAMP| | |BY_RECEPTION_TIMESTAMP| | Yes |
| |BY_SOURCE_TIMESTAMP| | |BY_SOURCE_TIMESTAMP| | Yes |
A |DataWriter| can send messages throughout a |Topic| even if there are no |DataReaders| on the network. Moreover, a DataReader that joins to the Topic after some data has been written could be interested in accessing that information (see |DurabilityQosPolicy-api|).
The DurabilityQoSPolicy defines how the system will behave regarding those samples that existed on the Topic before the DataReader joins. The behavior of the system depends on the value of the :ref:`DurabilityQosPolicyKind<durabilitykind>`.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |DurabilityQosPolicy::kind-api| | :ref:`durabilitykind` | |VOLATILE_DURABILITY_QOS-api| for DataReaders
|TRANSIENT_LOCAL_DURABILITY_QOS-api| for DataWriters |
Note
This QoS Policy concerns to Topic, DataReader and DataWriter entities.
It cannot be changed on enabled entities.
Important
In order to receive past samples in the DataReader, besides setting this Qos Policy, it is required that the :ref:`reliabilityqospolicy` is set to |RELIABLE_RELIABILITY_QOS-api|.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`durability_compatibilityrule` for further details.
There are four possible values (see |DurabilityQosPolicyKind-api|):
- |VOLATILE_DURABILITY_QOS-api|: Past samples are ignored and a joining DataReader receives samples generated after the moment it matches.
- |TRANSIENT_LOCAL_DURABILITY_QOS-api|: When a new DataReader joins, its History is filled with past samples.
- |TRANSIENT_DURABILITY_QOS-api|: When a new DataReader joins, its History is filled with past samples, which are stored on persistent storage (see :ref:`persistence_service`).
- |PERSISTENT_DURABILITY_QOS-api|: (Not Implemented): All the samples are stored on a permanent storage, so that they can outlive a system session.
To maintain the compatibility between DurabilityQosPolicy in DataReaders and DataWriters when they have different kind values, the DataWriter kind must be higher or equal to the DataReader kind. And the order between the different kinds is:
|VOLATILE_DURABILITY_QOS-api| < |TRANSIENT_LOCAL_DURABILITY_QOS-api| < |TRANSIENT_DURABILITY_QOS-api| < |PERSISTENT_DURABILITY_QOS-api|
Table with the possible combinations:
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_DURABILITY_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->PUBSUB_API_CONF_PUBSUB_DURABILITY
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
This QoS Policy is used to configure the :ref:`historyqospolicy` and :ref:`resourcelimitsqospolicy` of the fictitious |DataReader| and |DataWriter| used when the :ref:`durabilityqospolicy` kind is set to |TRANSIENT_DURABILITY_QOS-api| or |PERSISTENT_DURABILITY_QOS-api| (see |DurabilityServiceQosPolicy-api|).
Those entities are used to simulate the persistent storage. The fictitious DataReader reads the data written on the |Topic| and stores it, so that if the user DataWriter does not have the information requested by the user DataReaders, the fictitious DataWriter takes care of sending that information.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |service_cleanup_delay-api| | |Duration_t-api| | |c_TimeZero-api| |
| |history_kind-api| | :ref:`historyqospolicykind` | |KEEP_LAST_HISTORY_QOS-api| |
| |history_depth-api| | int32_t |
1 |
| |max_samples-api| | int32_t |
-1 (Length Unlimited) |
| |max_instances-api| | int32_t |
-1 (Length Unlimited) |
| |max_samples_per_instance-api| | int32_t |
-1 (Length Unlimited) |
- |service_cleanup_delay-api|: It controls when the service can remove all the information regarding a data instance.
That information is kept until all the following conditions are met:
- The instance has been explicitly disposed and its InstanceState becomes |NOT_ALIVE_DISPOSED_INSTANCE_STATE-api|.
- There is not any alive DataWriter writing the instance, which means that all existing writers either unregister the instance or lose their liveliness.
- A time interval longer than the one established on the |service_cleanup_delay-api| has elapsed since the moment the service detected that the two previous conditions were met.
- |history_kind-api|: Controls the kind of the :ref:`historyqospolicy` associated with the Durability Service fictitious entities.
- |history_depth-api|: Controls the depth of the :ref:`historyqospolicy` associated with the Durability Service fictitious entities.
- |max_samples-api|: Controls the maximum number of samples of the :ref:`resourcelimitsqospolicy` associated with the Durability Service fictitious entities. This value must be higher than the maximum number of samples per instance.
- |max_instances-api|: Controls the maximum number of instances of the :ref:`resourcelimitsqospolicy` associated with the Durability Service fictitious entities.
- |max_samples_per_instance-api|: Controls the maximum number of samples within an instance of the :ref:`resourcelimitsqospolicy` associated with the Durability Service fictitious entities. This value must be lower than the maximum number of samples.
Note
This QoS Policy concerns to Topic and DataWriter entities.
It cannot be changed on enabled entities.
This QoS Policy controls the behavior of an :ref:`dds_layer_core_entity` when it acts as a factory for other entities.
By default, all the entities are created enabled, but if you change the value of the |autoenable_created_entities-api|
to false, the new entities will be created disabled (see |EntityFactoryQosPolicy-api|).
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |autoenable_created_entities-api| | bool |
true |
Note
This QoS Policy concerns to |DomainParticipantFactory| (as factory for |DomainParticipant|), DomainParticipant
(as factory for
|Publisher|, |Subscriber| and |Topic|), Publisher (as factory for |DataWriter|) and Subscriber (as factory for
|DataReader|).
It can be changed on enabled entities, but it only affects those entities created after the change.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_ENTITY_FACTORY_QOS_POLICY
:end-before: //!
.. tab:: XML
This QoS Policy cannot be configured using XML for the moment.
Allows the application to attach additional information to created |Publishers| or |Subscribers|. This data is common to all |DataWriters|/|DataReaders| belonging to the Publisher/Subscriber and it is propagated by means of the built-in topics (see |GroupDataQosPolicy-api|).
This QoS Policy can be used in combination with DataWriter and DataReader listeners to implement a matching policy similar to the :ref:`PartitionQosPolicy <partitionqospolicy>`.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| collection | std::vector<|octet-api|> | Empty vector |
Note
This QoS Policy concerns to Publisher and Subscriber entities.
It can be changed on enabled entities.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_GROUP_DATA_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_CHANGE_GROUP_DATA_QOS_POLICY
:end-before: <!--><-->
This QoS Policy controls the behavior of the system when the value of an instance changes one or more times before it can be successfully communicated to the existing DataReader entities.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |HistoryQosPolicy::kind-api| | :ref:`historyqospolicykind` | |KEEP_LAST_HISTORY_QOS-api| |
| |HistoryQosPolicy::depth-api| | int32_t |
1 |
- |HistoryQosPolicy::kind-api|: Controls if the service should deliver only the most recent values, all the intermediate values or do something in between. See :ref:`historyqospolicykind` for further details.
- |HistoryQosPolicy::depth-api|: Establishes the maximum number of samples that must be kept on the history. It only has effect if the kind is set to |KEEP_LAST_HISTORY_QOS-api| and it needs to be consistent with the :ref:`resourcelimitsqospolicy`, which means that its value must be lower or equal to max_samples_per_instance.
Note
This QoS Policy concerns to Topic, DataWriter and DataReader entities.
It cannot be changed on enabled entities.
There are two possible values (see |HistoryQosPolicyKind-api|):
- |KEEP_LAST_HISTORY_QOS-api|: The service will only attempt to keep the most recent values of the instance and discard the older ones. The maximum number of samples to keep and deliver is defined by the depth of the HistoryQosPolicy, which needs to be consistent with the :ref:`resourcelimitsqospolicy` settings. If the limit defined by depth is reached, the system will discard the oldest sample to make room for a new one.
- |KEEP_ALL_HISTORY_QOS-api|: The service will attempt to keep all the values of the instance until it can be delivered to all the existing Subscribers. If this option is selected, the depth will not have any effect, so the history is only limited by the values set in :ref:`resourcelimitsqospolicy`.
The HistoryQos must be set consistently with the :ref:`resourcelimitsqospolicy`, but also other QoS as :ref:`durabilityqospolicy` and :ref:`reliabilityqospolicy`, so there are several cases to take into account:
- The |HistoryQosPolicy::depth-api| is only considered if the |HistoryQosPolicy::kind-api| is set to |KEEP_LAST_HISTORY_QOS-api|.
- The |HistoryQosPolicy::depth-api| must be consistent with the :ref:`resourcelimitsqospolicy` settings, which means that the |HistoryQosPolicy::depth-api| must be lower or equal than the :ref:`resourcelimitsqospolicy`'s |ResourceLimitsQosPolicy::max_samples_per_instance-api|. Also, |ResourceLimitsQosPolicy::max_samples-api| must be equal or higher than the product of |ResourceLimitsQosPolicy::max_samples_per_instance-api| times |ResourceLimitsQosPolicy::max_instances-api|.
- The |HistoryQosPolicy::depth-api| cannot be lower or equal than zero. If an unlimited depth is required, please consider using |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api|.
- Setting the |HistoryQosPolicy::kind-api| as |KEEP_ALL_HISTORY_QOS-api| entails that limits are set by the :ref:`resourcelimitsqospolicy` limits (|ResourceLimitsQosPolicy::max_samples_per_instance-api| prior than |ResourceLimitsQosPolicy::max_samples-api|).
- In the case of the :ref:`reliabilityqospolicy` |ReliabilityQosPolicyKind-api| being set to
|RELIABLE_RELIABILITY_QOS-api| and the :ref:`historyqospolicy` |HistoryQosPolicy::kind-api| being set to
|KEEP_ALL_HISTORY_QOS-api|, when the resource limits are reached, the behavior of the service is depends on the
:ref:`durabilityqospolicy`:
- If the :ref:`durabilityqospolicy` |DurabilityQosPolicy::kind-api| is configured as |VOLATILE_DURABILITY_QOS-api|, the DataWriter |DataWriter::write-api| call will discard the oldest sample in the history. Note that the removed sample may belong to different :ref:`instances<dds_layer_topic_instances>` than the newly written one.
- If the :ref:`durabilityqospolicy` |DurabilityQosPolicy::kind-api| is configured as |TRANSIENT_LOCAL_DURABILITY_QOS-api| or |TRANSIENT_DURABILITY_QOS-api|, the DataWriter |DataWriter::write-api| call will be blocked until the history has space for the new sample.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_HISTORY_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML-HISTORY<-->
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
This QoS Policy specifies the maximum acceptable delay from the time the data is written until the data is inserted on the DataReader History and notified of the fact. That delay by default is set to 0 in order to optimize the internal operations (see |LatencyBudgetQosPolicy-api|).
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |LatencyBudgetQosPolicy::duration-api| | |Duration_t-api| | |c_TimeZero-api| |
Note
This QoS Policy concerns to |Topic|, |DataWriter| and |DataReader| entities.
It can be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`latencybudget_compatibilityrule` for further details.
To maintain the compatibility between LatencyBudgetQosPolicy in DataReaders and DataWriters, the DataWriter duration must be lower or equal to the DataReader duration.
Each data sample written by a |DataWriter| has an associated expiration time beyond which the data is removed from the DataWriter and DataReader history as well as from the transient and persistent information caches (see |LifespanQosPolicy-api|).
By default, the duration is infinite, which means that there is not a maximum duration for the validity of the samples written by the DataWriter.
The expiration time is computed by adding the duration to the source timestamp, which can be calculated automatically if |DataWriter::write-api| member function is called or supplied by the application by means of :func:`write_w_timestamp` member function. The DataReader is allowed to use the reception timestamp instead of the source timestamp.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |LifespanQosPolicy::duration-api| | |Duration_t-api| | |c_TimeInfinite-api| |
Note
This QoS Policy concerns to |Topic|, |DataReader| and |DataWriter| entities.
It can be changed on enabled entities.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_LIFESPAN_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_LIFESPAN
:end-before: <!--><-->
This QoS Policy controls the mechanism used by the service to ensure that a particular entity on the network is still alive. There are different settings that allow distinguishing between applications where data is updated periodically and applications where data is changed sporadically. It also allows customizing the application regarding the kind of failures that should be detected by the liveliness mechanism (see |LivelinessQosPolicy-api|).
List of QoS Policy data members:
- |LivelinessQosPolicy::kind-api|: This data member establishes if the service needs to assert the liveliness automatically or if it needs to wait until the liveliness is asserted by the publishing side. See :ref:`livelinessqospolicykind` for further details.
- |LivelinessQosPolicy::lease_duration-api|: Amount of time to wait since the last time the DataWriter asserts its liveliness to consider that it is no longer alive.
- |LivelinessQosPolicy::announcement_period-api|: Amount of time between consecutive liveliness messages sent by the DataWriter. This data member only takes effect if the kind is |AUTOMATIC_LIVELINESS_QOS-api| or |MANUAL_BY_PARTICIPANT_LIVELINESS_QOS-api| and needs to be lower than the |LivelinessQosPolicy::lease_duration-api|.
Note
This QoS Policy concerns to |Topic|, |DataReader| and |DataWriter| entities.
It cannot be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`liveliness_compatibilityrule` for further details.
There are three possible values (see |LivelinessQosPolicyKind-api|):
- |AUTOMATIC_LIVELINESS_QOS-api|: The service takes the responsibility for renewing the leases at the required rates, as long as the local process where the participant is running and the link connecting it to remote participants exists, the entities within the remote participant will be considered alive. This kind is suitable for applications that only need to detect whether a remote application is still running.
- The two Manual modes require that the application on the publishing side asserts the liveliness periodically
before the lease_duration timer expires.
Publishing any new data value implicitly asserts the DataWriter's liveliness, but it can be done explicitly
by calling the assert_liveliness member function.
- |MANUAL_BY_PARTICIPANT_LIVELINESS_QOS-api|: If one of the entities in the publishing side asserts its liveliness, the service deduces that all other entities within the same DomainParticipant are also alive.
- |MANUAL_BY_TOPIC_LIVELINESS_QOS-api|: This mode is more restrictive and requires that at least one instance within the DataWriter is asserted to consider that the DataWriter is alive.
To maintain the compatibility between LivelinessQosPolicy in DataReaders and DataWriters, the DataWriter kind must be higher or equal to the DataReader kind. And the order between the different kinds is:
|AUTOMATIC_LIVELINESS_QOS-api| < |MANUAL_BY_PARTICIPANT_LIVELINESS_QOS-api| < |MANUAL_BY_TOPIC_LIVELINESS_QOS-api|
Table with the possible combinations:
Additionally, the |LivelinessQosPolicy::lease_duration-api| of the DataWriter must not be greater than the |LivelinessQosPolicy::lease_duration-api| of the DataReader.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_LIVELINESS_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->PUBSUB_API_CONF_PUBSUB_LIVELINESS
:end-before: <!--><-->
This QoS Policy specifies whether it is allowed for multiple DataWriters to update the same instance of data, and if so, how these modifications should be arbitrated (see |OwnershipQosPolicy-api|).
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |OwnershipQosPolicy::kind-api| | :ref:`ownershipqospolicykind` | |SHARED_OWNERSHIP_QOS-api| |
Note
This QoS Policy concerns to |Topic|, |DataReader| and |DataWriter| entities.
It cannot be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`ownership_compatibilityrule` for further details.
There are two possible values (see |OwnershipQosPolicyKind-api|):
- |SHARED_OWNERSHIP_QOS-api|: This option indicates that the service does not enforce unique ownership for each instance. In this case, multiple DataWriters are allowed to update the same data instance and all the updates are made available to the existing DataReaders. Those updates are also subject to the :ref:`timebasedfilterqospolicy` or :ref:`historyqospolicy` settings, so they can be filtered.
- |EXCLUSIVE_OWNERSHIP_QOS-api|: This option indicates that each instance can only be updated by one DataWriter, meaning that at any point in time a single DataWriter owns each instance and is the only one whose modifications will be visible for the existing DataReaders. The owner can be changed dynamically according to the highest strength between the alive DataWriters, which has not violated the deadline contract concerning the data instances. That strength can be changed using the :ref:`ownershipstrengthqospolicy`. In case two DataWriters have the same strength value, the DataWriter with a lower GUID value would be the owner of the topic.
To maintain the compatibility between OwnershipQosPolicy in |DataReaders| and |DataWriters|, the DataWriter kind must be equal to the DataReader kind.
Table with the possible combinations:
| DataWriter kind | DataReader kind | Compatibility |
|---|---|---|
| |SHARED_OWNERSHIP_QOS-api| | |SHARED_OWNERSHIP_QOS-api| | Yes |
| |SHARED_OWNERSHIP_QOS-api| | |EXCLUSIVE_OWNERSHIP_QOS-api| | No |
| |EXCLUSIVE_OWNERSHIP_QOS-api| | |SHARED_OWNERSHIP_QOS-api| | No |
| |EXCLUSIVE_OWNERSHIP_QOS-api| | |EXCLUSIVE_OWNERSHIP_QOS-api| | Yes |
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_OWNERSHIP_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->PUBSUB_API_CONF_PUBSUB_OWNERSHIP
:end-before: <!--><-->
This QoS Policy specifies the value of the strength used to arbitrate among multiple DataWriters that attempt to modify the same data instance. It is only applicable if the :ref:`ownershipqospolicy` kind is set to |EXCLUSIVE_OWNERSHIP_QOS-api|. See |OwnershipStrengthQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |OwnershipStrengthQosPolicy::value-api| | uint32_t |
0 |
Note
This QoS Policy concerns to DataWriter entities.
It can be changed on enabled entities.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_OWNERSHIP_STRENGTH_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->PUBSUB_API_CONF_PUBSUB_OWNERSHIP_STRENGTH
:end-before: <!--><-->
This Qos Policy allows the introduction of a logical partition inside the physical partition introduced by a domain. For a DataReader to see the changes made by a DataWriter, not only the Topic must match, but also they have to share at least one logical partition (see |PartitionQosPolicy-api|).
The empty string is also considered as a valid partition and it matches with other partition names using the same rules of string matching and regular-expression matching used for any other partition name.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |PartitionQosPolicy::max_size-api| | uint32_t |
0 (Length Unlimited) |
| |PartitionQosPolicy::names-api| | |SerializedPayload_t-api| | Empty List |
- |PartitionQosPolicy::max_size-api|: Maximum size for the list of partition names.
- |PartitionQosPolicy::names-api|: List of partition names.
Note
This QoS Policy concerns to Publisher and Subscriber entities.
Partitions can also be explicitly defined at the endpoint level to override this configuration. Information
to do so can be found :ref:`here<property_policies_partitions>`.
It can be changed on enabled Publishers and Subscribers.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_PARTITION_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML-PARTITION
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
This QoS Policy specifies how the samples representing changes to data instances are presented to the subscribing application. It controls the extent to which changes to data instances can be made dependent on each other, as well as the kind of dependencies that can be propagated and maintained. See |PresentationQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |access_scope-api| | :ref:`presentationqospolicyaccessscopekind` | |INSTANCE_PRESENTATION_QOS-api| |
| |coherent_access-api| | bool |
false |
| |ordered_access-api| | bool |
false |
- |access_scope-api|: Determines the largest scope spanning the entities for which the order and coherency can be preserved. See :ref:`presentationqospolicyaccessscopekind` for further details.
- |coherent_access-api|: Controls whether the service will preserve grouping of changes made on the publishing side, such that they are received as a unit on the subscribing side.
- |ordered_access-api|: Controls whether the service supports the ability of the subscriber to see changes in the same order as they occurred on the publishing side.
Note
This QoS Policy concerns to |Publisher| and |Subscriber| entities.
It cannot be changed on enabled entities.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`presentation_compatibilityrule` for further details.
There are three possible values, which have different behaviors depending on the values of coherent_access and ordered_access variables (see |PresentationQosPolicyAccessScopeKind-api|):
- |INSTANCE_PRESENTATION_QOS-api|: The changes to a data instance do not need to be coherent nor ordered with respect to
the changes to any other instance, which means that the order and coherent changes apply to each instance separately.
- Enabling the coherent_access, in this case, has no effect on how the subscriber can access the data as the scope is limited to each instance, changes to separate instances are considered independent and thus cannot be grouped by a coherent change.
- Enabling the ordered_access, in this case, only affects to the changes within the same instance. Therefore, the changes made to two instances are not necessarily seen in the order they occur even if the same application thread and DataWriter made them.
- |TOPIC_PRESENTATION_QOS-api|: The scope spans to all the instances within the same DataWriter.
- Enabling the coherent_access makes that the grouping made with changes within the same DataWriter will be available as coherent with respect to other changes to instances in that DataWriter, but will not be grouped with changes made to instances belonging to different DataWriters.
- Enabling the ordered_access means that the changes made by a single DataWriter are made available to the subscribers in the same order that they occur, but the changes made to instances through different DataWriters are not necessarily seen in order.
- |GROUP_PRESENTATION_QOS-api|: The scope spans to all the instances belonging to DataWriters within the same Publisher.
- Enabling the coherent_access, means that the coherent changes made to instances through DataWriters attached to a common Publisher are made available as a unit to remote subscribers.
- Enabling the ordered_access with this scope makes that the changes done by any of the DataWriters attached to the same Publisher are made available to the subscribers in the same order they occur.
To maintain the compatibility between PresentationQosPolicy in DataReaders and DataWriters, the Publisher |access_scope-api| must be higher or equal to the Subscriber |access_scope-api|. And the order between the different access scopes is:
|INSTANCE_PRESENTATION_QOS-api| < |TOPIC_PRESENTATION_QOS-api| < |GROUP_PRESENTATION_QOS-api|
Table with the possible combinations:
Additionally, the coherent_access and ordered_access of the Subscriber can only be enabled if they are also enabled on the Publisher.
Warning
This QoS Policy will be implemented in future releases.
This QoS Policy specifies the behavior of the |DataReader| with respect to the lifecycle of the data instances it manages, that is, the instances that have been received and for which the DataReader maintains some internal resources. The DataReader maintains the samples that have not been taken by the application, subject to the constraints imposed by :ref:`historyqospolicy` and :ref:`resourcelimitsqospolicy`. See |ReaderDataLifecycleQosPolicy-api|.
Under normal circumstances, the DataReader can only reclaim the resources associated with data instances if there are no writers and all the samples have been taken. But this fact can cause problems if the application does not take those samples as the service will prevent the DataReader from reclaiming the resources and they will remain in the DataReader indefinitely. This QoS exist to avoid that situation.
List of QoS Policy data members:
- |ReaderDataLifecycleQosPolicy::autopurge_no_writer_samples_delay-api|: Defines the maximum duration the DataReader must retain the information regarding an instance once its |SampleInfo::instance_state-api| becomes |NOT_ALIVE_NO_WRITERS_INSTANCE_STATE-api|. After this time elapses, the DataReader purges all the internal information of the instance, including the untaken samples that will be lost.
- |ReaderDataLifecycleQosPolicy::autopurge_disposed_samples_delay-api|: Defines the maximum duration the DataReader must retain the information regarding an instance once its |SampleInfo::instance_state-api| becomes |NOT_ALIVE_DISPOSED_INSTANCE_STATE-api|. After this time elapses, the DataReader purges all the samples for the instance.
Note
This QoS Policy concerns to DataReader entities.
It can be changed on enabled entities.
This QoS Policy indicates the level of reliability offered and requested by the service. See |ReliabilityQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |ReliabilityQosPolicy::kind-api| | :ref:`reliabilityqospolicykind` | |BEST_EFFORT_RELIABILITY_QOS-api|
for DataReaders
|RELIABLE_RELIABILITY_QOS-api| for DataWriters |
| |ReliabilityQosPolicy::max_blocking_time-api| | |Duration_t-api| | 100 ms |
- |ReliabilityQosPolicy::kind-api|: Specifies the behavior of the service regarding delivery of the samples. See :ref:`reliabilityqospolicykind` for further details.
- |ReliabilityQosPolicy::max_blocking_time-api|: Configures the maximum duration that the write operation can be blocked.
Note
This QoS Policy concerns to |Topic|, |DataWriter| and |DataReader| entities.
It cannot be changed on enabled entities.
Important
Setting this QoS Policy to |BEST_EFFORT_RELIABILITY_QOS-api| affects to the :ref:`durabilityqospolicy`, making the endpoints behave as |VOLATILE_DURABILITY_QOS-api|.
Warning
For DataWriters and DataReaders to match, they must follow the compatibility rule. See :ref:`reliability_compatibilityrule` for further details.
There are two possible values ():
|BEST_EFFORT_RELIABILITY_QOS-api|: It indicates that it is acceptable not to retransmit the missing samples, so the messages are sent without waiting for an arrival confirmation. Presumably new values for the samples are generated often enough that it is not necessary to re-send any sample. However, the data samples sent by the same DataWriter will be stored in the DataReader history in the same order they occur. In other words, even if the DataReader misses some data samples, an older value will never overwrite a newer value.
|RELIABLE_RELIABILITY_QOS-api|: It indicates that the service will attempt to deliver all samples of the DataWriter's history expecting an arrival confirmation from the DataReader. The data samples sent by the same DataWriter cannot be made available to the DataReader if there are previous samples that have not been received yet. The service will retransmit the lost data samples in order to reconstruct a correct snapshot of the DataWriter history before it is accessible by the DataReader.
This option may block the write operation, hence the |ReliabilityQosPolicy::max_blocking_time-api| is set that will unblock it once the time expires. But if the |ReliabilityQosPolicy::max_blocking_time-api| expires before the data is sent, the write operation will return an error.
To maintain the compatibility between ReliabilityQosPolicy in DataReaders and DataWriters, the DataWriter kind must be higher or equal to the DataReader kind. And the order between the different kinds is:
|BEST_EFFORT_RELIABILITY_QOS-api| < |RELIABLE_RELIABILITY_QOS-api|
Table with the possible combinations:
| DataWriter kind | DataReader kind | Compatibility |
|---|---|---|
| |BEST_EFFORT_RELIABILITY_QOS-api| | |BEST_EFFORT_RELIABILITY_QOS-api| | Yes |
| |BEST_EFFORT_RELIABILITY_QOS-api| | |RELIABLE_RELIABILITY_QOS-api| | No |
| |RELIABLE_RELIABILITY_QOS-api| | |BEST_EFFORT_RELIABILITY_QOS-api| | Yes |
| |RELIABLE_RELIABILITY_QOS-api| | |RELIABLE_RELIABILITY_QOS-api| | Yes |
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_RELIABILITY_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_RELIABILITY
:end-before: <!--><-->
This QoS Policy controls the resources that the service can use in order to meet the requirements imposed by the application and other QoS Policies. See |ResourceLimitsQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |ResourceLimitsQosPolicy::max_samples-api| | int32_t |
5000 |
| |ResourceLimitsQosPolicy::max_instances-api| | int32_t |
10 |
| |ResourceLimitsQosPolicy::max_samples_per_instance-api| | int32_t |
400 |
| |ResourceLimitsQosPolicy::allocated_samples-api| | int32_t |
100 |
| |ResourceLimitsQosPolicy::extra_samples-api| | int32_t |
1 |
- |ResourceLimitsQosPolicy::max_samples-api|: Controls the maximum number of samples that the DataWriter or DataReader can manage across all the instances associated with it. In other words, it represents the maximum samples that the middleware can store for a DataReader or DataWriter. Value 0 means infinite resources.
- |ResourceLimitsQosPolicy::max_instances-api|: Controls the maximum number of instances that a DataWriter or DataReader can manage. Value 0 means infinite resources.
- |ResourceLimitsQosPolicy::max_samples_per_instance-api|: Controls the maximum number of samples within an instance that the DataWriter or DataReader can manage. Value 0 means infinite resources.
- |ResourceLimitsQosPolicy::allocated_samples-api|: States the number of samples that will be allocated on initialization.
- |ResourceLimitsQosPolicy::extra_samples-api|: States the number of extra samples that will be allocated on the pool, so the maximum number of samples on the pool will be |ResourceLimitsQosPolicy::max_samples-api| plus |ResourceLimitsQosPolicy::extra_samples-api|. These extra samples act as a reservoir of samples even when the history is full.
Note
This QoS Policy concerns to Topic, DataWriter and DataReader entities.
It cannot be changed on enabled entities.
To maintain the consistency within the ResourceLimitsQosPolicy, the values of the data members must follow the next conditions:
- The value of |ResourceLimitsQosPolicy::max_samples-api| must be higher or equal to the value of |ResourceLimitsQosPolicy::max_samples_per_instance-api|.
- The value established for the :ref:`historyqospolicy` |HistoryQosPolicy::depth-api| must be lower or equal to the value stated for |ResourceLimitsQosPolicy::max_samples_per_instance-api|.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_RESOURCE_LIMITS_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_RESOURCE_LIMITS
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
Filter that allows a |DataReader| to specify that it is interested only in a subset of the values of the data. This filter states that the DataReader does not want to receive more than one value each |TimeBasedFilterQosPolicy::minimum_separation-api|, regardless of how fast the changes occur. See |TimeBasedFilterQosPolicy-api|.
The |TimeBasedFilterQosPolicy::minimum_separation-api| must be lower than the :ref:`deadlineqospolicy` |DeadlineQosPolicy::period-api|. By default, the |TimeBasedFilterQosPolicy::minimum_separation-api| is zero, which means that the DataReader is potentially interested in all the values.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |TimeBasedFilterQosPolicy::minimum_separation-api| | |Duration_t-api| | |c_TimeZero-api| |
Note
This QoS Policy concerns to DataReader entities.
It can be changed on enabled entities.
Allows the application to attach additional information to a created |Topic| so that when it is discovered by a remote application, it can access the data and use it. See |TopicDataQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| collection | std::vector<|octet-api|> | Empty vector |
Note
This QoS Policy concerns to Topic entities.
It can be changed even if it is already created.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_TOPIC_DATA_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_CHANGE_TOPIC_DATA_QOS_POLICY
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
The purpose of this QoS Policy is to allow the service to take advantage of those transports capable of sending messages with different priorities. It establishes the priority of the underlying transport used to send the data. See |TransportPriorityQosPolicy-api|
You can choose any value within the 32-bit range for the priority. The higher the value, the higher the priority.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |TransportPriorityQosPolicy::value-api| | uint32_t |
0 |
Note
This QoS Policy concerns to |Topic| and |DataWriter| entities.
It can be changed on enabled entities.
Allows the application to attach additional information to the |Entity| object so that when the entity is discovered the remote application can access the data and use it. For example, it can be used to attach the security credentials to authenticate the source from the remote application. See |UserDataQosPolicy-api|.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| collection | std::vector<|octet-api|> | Empty vector |
Note
This QoS Policy concerns to all DDS entities.
It can be changed on enabled entities.
.. tabs::
.. tab:: C++
.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //DDS_CHANGE_USER_DATA_QOS_POLICY
:end-before: //!
.. tab:: XML
.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->XML_CHANGE_USER_DATA_QOS_POLICY
:end-before: <!--><-->
Warning
This QoS Policy will be implemented in future releases.
This QoS Policy specifies the behavior of the DataWriter with respect to the lifecycle of the data instances it manages , that is, the instance that has been either explicitly registered with the DataWriter using the register operations or implicitly by directly writing data.
The |WriterDataLifecycleQosPolicy::autodispose_unregistered_instances-api| controls whether a DataWriter will automatically dispose an instance each time it is unregistered. Even if it is disabled, the application can still get the same result if it uses the dispose operation before unregistering the instance.
List of QoS Policy data members:
| Data Member Name | Type | Default Value |
|---|---|---|
| |WriterDataLifecycleQosPolicy::autodispose_unregistered_instances-api| | bool |
true |
Note
This QoS Policy concerns to DataWriter entities.
It can be changed on enabled entities.