3.1.2.1. Standard QoS Policies¶

This section explains each of the DDS standard QoS Policies:

3.1.2.1.1. DeadlineQosPolicy¶

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

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
`period`	`Duration_t`	`c_TimeInfinite`

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 Compatibility Rule for further details.

Compatibility Rule¶

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 TimeBasedFilterQosPolicy, which means that the deadline period must be higher or equal to the minimum separation.

Example¶

DeadlineQosPolicy deadline;
//The DeadlineQosPolicy is default constructed with an infinite period.
//Change the period to 1 second
deadline.period.seconds = 1;
deadline.period.nanosec = 0;

<data_writer profile_name="writer_xml_conf_deadline_profile">
    <qos>
        <deadline>
            <period>
                <sec>1</sec>
            </period>
        </deadline>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_deadline_profile">
    <qos>
        <deadline>
            <period>
                <sec>1</sec>
            </period>
        </deadline>
    </qos>
</data_reader>

3.1.2.1.2. DestinationOrderQosPolicy¶

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). 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 DestinationOrderQosPolicyKind.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`kind`	DestinationOrderQosPolicyKind	`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS`

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 Compatibility Rule for further details.

DestinationOrderQosPolicyKind¶

There are two possible values (see DestinationOrderQosPolicyKind):

BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS: 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_DESTINATIONORDER_QOS: 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 OwnershipQosPolicy and 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.

Compatibility Rule¶

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_DESTINATIONORDER_QOS < BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS

Table with the possible combinations:

DataWriter kind	DataReader kind	Compatibility
`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS`	`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS`	Yes
`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS`	`BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS`	No
`BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS`	`BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS`	Yes
`BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS`	`BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS`	Yes

3.1.2.1.3. DurabilityQosPolicy¶

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

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 DurabilityQosPolicyKind.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`kind`	DurabilityQosPolicyKind	`VOLATILE_DURABILITY_QOS` for DataReaders `TRANSIENT_LOCAL_DURABILITY_QOS` 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 ReliabilityQosPolicy is set to RELIABLE_RELIABILITY_QOS.

Warning

For DataWriters and DataReaders to match, they must follow the compatibility rule. See Compatibility Rule for further details.

DurabilityQosPolicyKind¶

There are four possible values (see DurabilityQosPolicyKind):

VOLATILE_DURABILITY_QOS: Past samples are ignored and a joining DataReader receives samples generated after the moment it matches.
TRANSIENT_LOCAL_DURABILITY_QOS: When a new DataReader joins, its History is filled with past samples.
TRANSIENT_DURABILITY_QOS: When a new DataReader joins, its History is filled with past samples, which are stored on persistent storage (see Persistence Service).
PERSISTENT_DURABILITY_QOS: (Not Implemented): All the samples are stored on a permanent storage, so that they can outlive a system session.

Compatibility Rule¶

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 < TRANSIENT_LOCAL_DURABILITY_QOS < TRANSIENT_DURABILITY_QOS < PERSISTENT_DURABILITY_QOS

Table with the possible combinations:

DataWriter kind	DataReader kind	Compatibility
`VOLATILE_DURABILITY_QOS`	`VOLATILE_DURABILITY_QOS`	Yes
`VOLATILE_DURABILITY_QOS`	`TRANSIENT_LOCAL_DURABILITY_QOS`	No
`VOLATILE_DURABILITY_QOS`	`TRANSIENT_DURABILITY_QOS`	No
`TRANSIENT_LOCAL_DURABILITY_QOS`	`VOLATILE_DURABILITY_QOS`	Yes
`TRANSIENT_LOCAL_DURABILITY_QOS`	`TRANSIENT_LOCAL_DURABILITY_QOS`	Yes
`TRANSIENT_LOCAL_DURABILITY_QOS`	`TRANSIENT_DURABILITY_QOS`	No
`TRANSIENT_DURABILITY_QOS`	`VOLATILE_DURABILITY_QOS`	Yes
`TRANSIENT_DURABILITY_QOS`	`TRANSIENT_LOCAL_DURABILITY_QOS`	Yes
`TRANSIENT_DURABILITY_QOS`	`TRANSIENT_DURABILITY_QOS`	Yes

Example¶

DurabilityQosPolicy durability;
//The DurabilityQosPolicy is default constructed with kind = VOLATILE_DURABILITY_QOS
//Change the kind to TRANSIENT_LOCAL_DURABILITY_QOS
durability.kind = TRANSIENT_LOCAL_DURABILITY_QOS;

<data_writer profile_name="writer_xml_conf_durability_profile">
    <qos>
        <durability>
            <kind>TRANSIENT_LOCAL</kind>
         </durability>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_durability_profile">
    <qos>
        <durability>
            <kind>VOLATILE</kind>
        </durability>
    </qos>
</data_reader>

3.1.2.1.4. DurabilityServiceQosPolicy¶

Warning

This QoS Policy will be implemented in future releases.

This QoS Policy is used to configure the HistoryQosPolicy and ResourceLimitsQosPolicy of the fictitious DataReader and DataWriter used when the DurabilityQosPolicy kind is set to TRANSIENT_DURABILITY_QOS or PERSISTENT_DURABILITY_QOS (see DurabilityServiceQosPolicy).

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`	`Duration_t`	`c_TimeZero`
`history_kind`	HistoryQosPolicyKind	`KEEP_LAST_HISTORY_QOS`
`history_depth`	`int32_t`	1
`max_samples`	`int32_t`	-1 (Length Unlimited)
`max_instances`	`int32_t`	-1 (Length Unlimited)
`max_samples_per_instance`	`int32_t`	-1 (Length Unlimited)

service_cleanup_delay: 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.
- 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 has elapsed since the moment the service detected that the two previous conditions were met.
history_kind: Controls the kind of the HistoryQosPolicy associated with the Durability Service fictitious entities.
history_depth: Controls the depth of the HistoryQosPolicy associated with the Durability Service fictitious entities.
max_samples: Controls the maximum number of samples of the ResourceLimitsQosPolicy associated with the Durability Service fictitious entities. This value must be higher than the maximum number of samples per instance.
max_instances: Controls the maximum number of instances of the ResourceLimitsQosPolicy associated with the Durability Service fictitious entities.
max_samples_per_instance: Controls the maximum number of samples within an instance of the 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.

3.1.2.1.5. EntityFactoryQosPolicy¶

This QoS Policy controls the behavior of an 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 to false, the new entities will be created disabled (see EntityFactoryQosPolicy).

List of QoS Policy data members:

Data Member Name	Type	Default Value
`autoenable_created_entities`	`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.

Example¶

EntityFactoryQosPolicy entity_factory;
//The EntityFactoryQosPolicy is default constructed with autoenable_created_entities = true
//Change it to false
entity_factory.autoenable_created_entities = false;

3.1.2.1.6. GroupDataQosPolicy¶

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

This QoS Policy can be used in combination with DataWriter and DataReader listeners to implement a matching policy similar to the PartitionQosPolicy.

List of QoS Policy data members:

Data Member Name	Type	Default Value
collection	std::vector<`octet`>	Empty vector

Note

This QoS Policy concerns to Publisher and Subscriber entities.
It can be changed on enabled entities.

Example¶

GroupDataQosPolicy group_data;
//The GroupDataQosPolicy is default constructed with an empty collection
//Collection is a private member so you need to use getters and setters to access
//Add data to the collection
std::vector<eprosima::fastrtps::rtps::octet> vec;
vec = group_data.data_vec(); // Getter function

//Add two new octets to group data vector
eprosima::fastrtps::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
group_data.data_vec(vec); //Setter function

<data_writer profile_name="writer_xml_conf_groupdata_profile">
    <qos>
        <groupData>
            <value>3.a</value>
        </groupData>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_groupdata_profile">
    <qos>
        <groupData>
            <value>3.a</value>
        </groupData>
    </qos>
</data_reader>

3.1.2.1.7. HistoryQosPolicy¶

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
`kind`	HistoryQosPolicyKind	`KEEP_LAST_HISTORY_QOS`
`depth`	`int32_t`	1

kind: Controls if the service should deliver only the most recent values, all the intermediate values or do something in between. See HistoryQosPolicyKind for further details.
depth: 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 and it needs to be consistent with the 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.

HistoryQosPolicyKind¶

There are two possible values (see HistoryQosPolicyKind):

KEEP_LAST_HISTORY_QOS: 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 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: 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 ResourceLimitsQosPolicy.

Consistency rule¶

The HistoryQos must be set consistently with the ResourceLimitsQosPolicy, but also other QoS as DurabilityQosPolicy and ReliabilityQosPolicy, so there are several cases to take into account:

The depth is only considered if the kind is set to KEEP_LAST_HISTORY_QOS.
The depth must be consistent with the ResourceLimitsQosPolicy settings, which means that the depth must be lower or equal than the ResourceLimitsQosPolicy’s max_samples_per_instance. Also, max_samples must be equal or higher than the product of max_samples_per_instance times max_instances.
The depth cannot be lower or equal than zero. If an unlimited depth is required, please consider using kind as KEEP_ALL_HISTORY_QOS.
Setting the kind as KEEP_ALL_HISTORY_QOS entails that limits are set by the ResourceLimitsQosPolicy limits (max_samples_per_instance prior than max_samples).
In the case of the ReliabilityQosPolicy ReliabilityQosPolicyKind being set to RELIABLE_RELIABILITY_QOS and the HistoryQosPolicy kind being set to KEEP_ALL_HISTORY_QOS, when the resource limits are reached, the behavior of the service is depends on the DurabilityQosPolicy:
- If the DurabilityQosPolicy kind is configured as VOLATILE_DURABILITY_QOS, the DataWriter write() call will discard the oldest sample in the history. Note that the removed sample may belong to different instances than the newly written one.
- If the DurabilityQosPolicy kind is configured as TRANSIENT_LOCAL_DURABILITY_QOS or TRANSIENT_DURABILITY_QOS, the DataWriter write() call will be blocked until the history has space for the new sample.

Example¶

HistoryQosPolicy history;
//The HistoryQosPolicy is default constructed with kind = KEEP_LAST and depth = 1.
//Change the depth to 20
history.depth = 20;
//You can also change the kind to KEEP_ALL but after that the depth will not have effect.
history.kind = KEEP_ALL_HISTORY_QOS;

<topic>
    <historyQos>
        <kind>KEEP_LAST</kind> <!-- string -->
        <depth>20</depth> <!-- uint32 -->
    </historyQos>
</topic>

3.1.2.1.8. LatencyBudgetQosPolicy¶

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

List of QoS Policy data members:

Data Member Name	Type	Default Value
`duration`	`Duration_t`	`c_TimeZero`

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 Compatibility Rule for further details.

Compatibility Rule¶

To maintain the compatibility between LatencyBudgetQosPolicy in DataReaders and DataWriters, the DataWriter duration must be lower or equal to the DataReader duration.

3.1.2.1.9. LifespanQosPolicy¶

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

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 write() member function is called or supplied by the application by means of 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
`duration`	`Duration_t`	`c_TimeInfinite`

Note

This QoS Policy concerns to Topic, DataReader and DataWriter entities.
It can be changed on enabled entities.

Example¶

LifespanQosPolicy lifespan;
//The LifespanQosPolicy is default constructed with duration set to infinite.
//Change the duration to 5 s
lifespan.duration = {5, 0};

<data_writer profile_name="writer_xml_conf_lifespan_profile">
    <qos>
        <lifespan>
            <duration>
                <sec>5</sec>
            </duration>
        </lifespan>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_lifespan_profile">
    <qos>
        <lifespan>
            <duration>
                <sec>5</sec>
            </duration>
        </lifespan>
    </qos>
</data_reader>

3.1.2.1.10. LivelinessQosPolicy¶

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

List of QoS Policy data members:

Data Member Name	Type	Default Value
`kind`	LivelinessQosPolicyKind	`AUTOMATIC_LIVELINESS_QOS`
`lease_duration`	`Duration_t`	`c_TimeInfinite`
`announcement_period`	`Duration_t`	`c_TimeInfinite`

kind: 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 LivelinessQosPolicyKind for further details.
lease_duration: Amount of time to wait since the last time the DataWriter asserts its liveliness to consider that it is no longer alive.
announcement_period: Amount of time between consecutive liveliness messages sent by the DataWriter. This data member only takes effect if the kind is AUTOMATIC_LIVELINESS_QOS or MANUAL_BY_PARTICIPANT_LIVELINESS_QOS and needs to be lower than the lease_duration.

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 Compatibility Rule for further details.

LivelinessQosPolicyKind¶

There are three possible values (see LivelinessQosPolicyKind):

AUTOMATIC_LIVELINESS_QOS: 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: 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: This mode is more restrictive and requires that at least one instance within the DataWriter is asserted to consider that the DataWriter is alive.

Compatibility Rule¶

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:

DataWriter kind	DataReader kind	Compatibility
`AUTOMATIC_LIVELINESS_QOS`	`AUTOMATIC_LIVELINESS_QOS`	Yes
`AUTOMATIC_LIVELINESS_QOS`	`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	No
`AUTOMATIC_LIVELINESS_QOS`	`MANUAL_BY_TOPIC_LIVELINESS_QOS`	No
`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	`AUTOMATIC_LIVELINESS_QOS`	Yes
`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	Yes
`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	`MANUAL_BY_TOPIC_LIVELINESS_QOS`	No
`MANUAL_BY_TOPIC_LIVELINESS_QOS`	`AUTOMATIC_LIVELINESS_QOS`	Yes
`MANUAL_BY_TOPIC_LIVELINESS_QOS`	`MANUAL_BY_PARTICIPANT_LIVELINESS_QOS`	Yes
`MANUAL_BY_TOPIC_LIVELINESS_QOS`	`MANUAL_BY_TOPIC_LIVELINESS_QOS`	Yes

Additionally, the lease_duration of the DataWriter must not be greater than the lease_duration of the DataReader.

Example¶

LivelinessQosPolicy liveliness;
//The LivelinessQosPolicy is default constructed with kind = AUTOMATIC
//Change the kind to MANUAL_BY_PARTICIPANT
liveliness.kind = MANUAL_BY_PARTICIPANT_LIVELINESS_QOS;
//The LivelinessQosPolicy is default constructed with lease_duration set to infinite
//Change the lease_duration to 1 second
liveliness.lease_duration = {1, 0};
//The LivelinessQosPolicy is default constructed with announcement_period set to infinite
//Change the announcement_period to 1 ms
liveliness.announcement_period = {0, 1000000};

<data_writer profile_name="writer_xml_conf_liveliness_profile">
    <qos>
        <liveliness>
            <announcement_period>
                <nanosec>1000000</nanosec>
            </announcement_period>
            <lease_duration>
                <sec>1</sec>
            </lease_duration>
            <kind>AUTOMATIC</kind>
        </liveliness>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_liveliness_profile">
    <qos>
        <liveliness>
            <lease_duration>
                <sec>1</sec>
            </lease_duration>
	    <kind>AUTOMATIC</kind>
        </liveliness>
    </qos>
</data_reader>

3.1.2.1.11. OwnershipQosPolicy¶

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

List of QoS Policy data members:

Data Member Name	Type	Default Value
`kind`	OwnershipQosPolicyKind	`SHARED_OWNERSHIP_QOS`

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 Compatibility Rule for further details.

OwnershipQosPolicyKind¶

There are two possible values (see OwnershipQosPolicyKind):

SHARED_OWNERSHIP_QOS: 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 TimeBasedFilterQosPolicy or HistoryQosPolicy settings, so they can be filtered.
EXCLUSIVE_OWNERSHIP_QOS: 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 OwnershipStrengthQosPolicy. In case two DataWriters have the same strength value, the DataWriter with a lower GUID value would be the owner of the topic.

Compatibility Rule¶

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`	`SHARED_OWNERSHIP_QOS`	Yes
`SHARED_OWNERSHIP_QOS`	`EXCLUSIVE_OWNERSHIP_QOS`	No
`EXCLUSIVE_OWNERSHIP_QOS`	`SHARED_OWNERSHIP_QOS`	No
`EXCLUSIVE_OWNERSHIP_QOS`	`EXCLUSIVE_OWNERSHIP_QOS`	Yes

Example¶

OwnershipQosPolicy ownership;
//The OwnershipQosPolicy is default constructed with kind = SHARED.
//Change the kind to EXCLUSIVE
ownership.kind = EXCLUSIVE_OWNERSHIP_QOS;

<data_writer profile_name="writer_xml_conf_ownership_profile">
    <qos>
      <ownership>
	    <kind>EXCLUSIVE</kind>
      </ownership>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_ownership_profile">
    <qos>
        <ownership>
	    <kind>EXCLUSIVE</kind>
        </ownership>
    </qos>
</data_reader>

3.1.2.1.12. OwnershipStrengthQosPolicy¶

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 OwnershipQosPolicy kind is set to EXCLUSIVE_OWNERSHIP_QOS. See OwnershipStrengthQosPolicy.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`value`	`uint32_t`	0

Note

This QoS Policy concerns to DataWriter entities.
It can be changed on enabled entities.

Example¶

OwnershipStrengthQosPolicy ownership_strength;
//The OwnershipStrengthQosPolicy is default constructed with value 0
//Change the strength to 10
ownership_strength.value = 10;

<data_writer profile_name="writer_xml_conf_ownership_strength_profile">
    <qos>
        <ownershipStrength>
	    <value>10</value>
        </ownershipStrength>
    </qos>
</data_writer>

3.1.2.1.13. PartitionQosPolicy¶

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

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
`max_size`	`uint32_t`	0 (Length Unlimited)
`names`	`SerializedPayload_t`	Empty List

max_size: Maximum size for the list of partition names.
names: 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 here.
It can be changed on enabled Publishers and Subscribers.

Example¶

PartitionQosPolicy partitions;
//The PartitionsQosPolicy is default constructed with max_size = 0.
//Max_size is a private member so you need to use getters and setters to access
//Change the max_size to 20
partitions.set_max_size(20); //Setter function
//The PartitionsQosPolicy is default constructed with an empty list of partitions
//Partitions is a private member so you need to use getters and setters to access
//Add new partitions
std::vector<std::string> part = partitions.names(); //Getter function
part.push_back("part1");
part.push_back("part2");
partitions.names(part); //Setter function

<data_writer profile_name="pub_partition_example">
    <qos>
        <partition>
            <names>
                <name>part1</name>
                <name>part2</name>
            </names>
        </partition>
    </qos>
</data_writer>

<data_reader profile_name="sub_partition_example">
    <qos>
        <partition>
            <names>
                <name>part1</name>
                <name>part2</name>
            </names>
        </partition>
    </qos>
</data_reader>

3.1.2.1.14. PresentationQosPolicy¶

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.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`access_scope`	PresentationQosPolicyAccessScopeKind	`INSTANCE_PRESENTATION_QOS`
`coherent_access`	`bool`	`false`
`ordered_access`	`bool`	`false`

access_scope: Determines the largest scope spanning the entities for which the order and coherency can be preserved. See PresentationQosPolicyAccessScopeKind for further details.
coherent_access: 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: 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 Compatibility Rule for further details.

PresentationQosPolicyAccessScopeKind¶

There are three possible values, which have different behaviors depending on the values of coherent_access and ordered_access variables (see PresentationQosPolicyAccessScopeKind):

INSTANCE_PRESENTATION_QOS: 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: 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: 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.

Compatibility Rule¶

To maintain the compatibility between PresentationQosPolicy in DataReaders and DataWriters, the Publisher access_scope must be higher or equal to the Subscriber access_scope. 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:

Publisher scope	Subscriber scope	Compatibility
`INSTANCE_PRESENTATION_QOS`	`INSTANCE_PRESENTATION_QOS`	Yes
`INSTANCE_PRESENTATION_QOS`	`TOPIC_PRESENTATION_QOS`	No
`INSTANCE_PRESENTATION_QOS`	`GROUP_PRESENTATION_QOS`	No
`TOPIC_PRESENTATION_QOS`	`INSTANCE_PRESENTATION_QOS`	Yes
`TOPIC_PRESENTATION_QOS`	`TOPIC_PRESENTATION_QOS`	Yes
`TOPIC_PRESENTATION_QOS`	`GROUP_PRESENTATION_QOS`	No
`GROUP_PRESENTATION_QOS`	`INSTANCE_PRESENTATION_QOS`	Yes
`GROUP_PRESENTATION_QOS`	`TOPIC_PRESENTATION_QOS`	Yes
`GROUP_PRESENTATION_QOS`	`GROUP_PRESENTATION_QOS`	Yes

Additionally, the coherent_access and ordered_access of the Subscriber can only be enabled if they are also enabled on the Publisher.

3.1.2.1.15. ReaderDataLifecycleQosPolicy¶

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 HistoryQosPolicy and ResourceLimitsQosPolicy. See ReaderDataLifecycleQosPolicy.

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:

Data Member Name	Type	Default Value
`autopurge_no_writer_samples_delay`	`Duration_t`	`c_TimeInfinite`
`autopurge_disposed_samples_delay`	`Duration_t`	`c_TimeInfinite`

autopurge_no_writer_samples_delay: Defines the maximum duration the DataReader must retain the information regarding an instance once its instance_state becomes NOT_ALIVE_NO_WRITERS_INSTANCE_STATE. After this time elapses, the DataReader purges all the internal information of the instance, including the untaken samples that will be lost.
autopurge_disposed_samples_delay: Defines the maximum duration the DataReader must retain the information regarding an instance once its instance_state becomes NOT_ALIVE_DISPOSED_INSTANCE_STATE. 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.

3.1.2.1.16. ReliabilityQosPolicy¶

This QoS Policy indicates the level of reliability offered and requested by the service. See ReliabilityQosPolicy.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`kind`	ReliabilityQosPolicyKind	`BEST_EFFORT_RELIABILITY_QOS` for DataReaders `RELIABLE_RELIABILITY_QOS` for DataWriters
`max_blocking_time`	`Duration_t`	100 ms

kind: Specifies the behavior of the service regarding delivery of the samples. See ReliabilityQosPolicyKind for further details.
max_blocking_time: 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 affects to the DurabilityQosPolicy, making the endpoints behave as VOLATILE_DURABILITY_QOS.

Warning

For DataWriters and DataReaders to match, they must follow the compatibility rule. See Compatibility Rule for further details.

ReliabilityQosPolicyKind¶

There are two possible values ():

BEST_EFFORT_RELIABILITY_QOS: 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: 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 max_blocking_time is set that will unblock it once the time expires. But if the max_blocking_time expires before the data is sent, the write operation will return an error.

Compatibility Rule¶

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`	`BEST_EFFORT_RELIABILITY_QOS`	Yes
`BEST_EFFORT_RELIABILITY_QOS`	`RELIABLE_RELIABILITY_QOS`	No
`RELIABLE_RELIABILITY_QOS`	`BEST_EFFORT_RELIABILITY_QOS`	Yes
`RELIABLE_RELIABILITY_QOS`	`RELIABLE_RELIABILITY_QOS`	Yes

Example¶

ReliabilityQosPolicy reliability;
//The ReliabilityQosPolicy is default constructed with kind = BEST_EFFORT
//Change the kind to RELIABLE
reliability.kind = RELIABLE_RELIABILITY_QOS;
//The ReliabilityQosPolicy is default constructed with max_blocking_time = 100ms
//Change the max_blocking_time to 1s
reliability.max_blocking_time = {1, 0};

<data_writer profile_name="writer_xml_conf_reliability_profile">
    <qos>
        <reliability>
            <kind>RELIABLE</kind>
            <max_blocking_time>
                <sec>1</sec>
            </max_blocking_time>
        </reliability>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_reliability_profile">
    <qos>
        <reliability>
            <kind>BEST_EFFORT</kind>
        </reliability>
    </qos>
</data_reader>

3.1.2.1.17. ResourceLimitsQosPolicy¶

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.

List of QoS Policy data members:

Data Member Name	Type	Default Value
`max_samples`	`int32_t`	5000
`max_instances`	`int32_t`	10
`max_samples_per_instance`	`int32_t`	400
`allocated_samples`	`int32_t`	100
`extra_samples`	`int32_t`	1

max_samples: 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 less or equal to 0 means infinite resources.
max_instances: Controls the maximum number of instances that a DataWriter or DataReader can manage. Value less or equal to 0 means infinite resources.
max_samples_per_instance: Controls the maximum number of samples within an instance that the DataWriter or DataReader can manage. Value less or equal to 0 means infinite resources.
allocated_samples: States the number of samples that will be allocated on initialization.
extra_samples: States the number of extra samples that will be allocated on the pool, so the maximum number of samples on the pool will be max_samples plus extra_samples. 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.

Consistency Rule¶

To maintain the consistency within the ResourceLimitsQosPolicy, the values of the data members must follow the next conditions:

The value of max_samples must be higher or equal to the value of max_samples_per_instance.
The value established for the HistoryQosPolicy depth must be lower or equal to the value stated for max_samples_per_instance.

Example¶

ResourceLimitsQosPolicy resource_limits;
//The ResourceLimitsQosPolicy is default constructed with max_samples = 5000
//Change max_samples to 200
resource_limits.max_samples = 200;
//The ResourceLimitsQosPolicy is default constructed with max_instances = 10
//Change max_instances to 20
resource_limits.max_instances = 20;
//The ResourceLimitsQosPolicy is default constructed with max_samples_per_instance = 400
//Change max_samples_per_instance to 100 as it must be lower than max_samples
resource_limits.max_samples_per_instance = 100;
//The ResourceLimitsQosPolicy is default constructed with allocated_samples = 100
//Change allocated_samples to 50
resource_limits.allocated_samples = 50;

<data_writer profile_name="writer_xml_conf_resource_limits_profile">
    <topic>
        <resourceLimitsQos>
            <max_samples>200</max_samples>
            <max_instances>20</max_instances>
            <max_samples_per_instance>100</max_samples_per_instance>
            <allocated_samples>50</allocated_samples>
        </resourceLimitsQos>
    </topic>
</data_writer>

<data_reader profile_name="reader_xml_conf_resource_limits_profile">
    <topic>
        <resourceLimitsQos>
            <max_samples>200</max_samples>
            <max_instances>20</max_instances>
            <max_samples_per_instance>100</max_samples_per_instance>
            <allocated_samples>50</allocated_samples>
        </resourceLimitsQos>
    </topic>
</data_reader>

3.1.2.1.18. TimeBasedFilterQosPolicy¶

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 minimum_separation, regardless of how fast the changes occur. See TimeBasedFilterQosPolicy.

The minimum_separation must be lower than the DeadlineQosPolicy period. By default, the minimum_separation 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
`minimum_separation`	`Duration_t`	`c_TimeZero`

Note

This QoS Policy concerns to DataReader entities.
It can be changed on enabled entities.

3.1.2.1.19. TopicDataQosPolicy¶

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.

List of QoS Policy data members:

Data Member Name	Type	Default Value
collection	std::vector<`octet`>	Empty vector

Note

This QoS Policy concerns to Topic entities.
It can be changed even if it is already created.

Example¶

//The TopicDataQosPolicy is default constructed with an empty vector.
TopicDataQosPolicy topic_data;
std::vector<eprosima::fastrtps::rtps::octet> vec;
vec = topic_data.data_vec(); // Getter Function

//Add two new octets to topic data vector
eprosima::fastrtps::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
topic_data.data_vec(vec); //Setter Function

<data_writer profile_name="writer_xml_conf_topicdata_profile">
    <qos>
        <topicData>
            <value>3.a</value>
        </topicData>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_topicdata_profile">
    <qos>
        <topicData>
            <value>3.a</value>
        </topicData>
    </qos>
</data_reader>

3.1.2.1.20. TransportPriorityQosPolicy¶

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

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
`value`	`uint32_t`	0

Note

This QoS Policy concerns to Topic and DataWriter entities.
It can be changed on enabled entities.

3.1.2.1.21. UserDataQosPolicy¶

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.

List of QoS Policy data members:

Data Member Name	Type	Default Value
collection	std::vector<`octet`>	Empty vector

Note

This QoS Policy concerns to all DDS entities.
It can be changed on enabled entities.

Example¶

//The TopicDataQosPolicy is default constructed with an empty vector.
UserDataQosPolicy user_data;
std::vector<eprosima::fastrtps::rtps::octet> vec;
vec = user_data.data_vec(); // Getter Function

//Add two new octets to user data vector
eprosima::fastrtps::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
user_data.data_vec(vec); //Setter Function

<participant profile_name="participant_xml_conf_userdata_profile">
    <rtps>
        <userData>
            <value>3.a</value>
        </userData>
    </rtps>
</participant>

<data_writer profile_name="writer_xml_conf_userdata_profile">
    <qos>
        <userData>
            <value>3.a</value>
        </userData>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_userdata_profile">
    <qos>
        <userData>
            <value>3.a</value>
        </userData>
    </qos>
</data_reader>

3.1.2.1.22. WriterDataLifecycleQosPolicy¶

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 autodispose_unregistered_instances 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
`autodispose_unregistered_instances`	`bool`	`true`

Note

This QoS Policy concerns to DataWriter entities.
It can be changed on enabled entities.