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 applies 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

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The DeadlineQosPolicy is constructed with an infinite period by default
// Change the period to 1 second
writer_qos.deadline().period.seconds = 1;
writer_qos.deadline().period.nanosec = 0;
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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 applies 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):

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

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The DurabilityQosPolicy is constructed with kind = VOLATILE_DURABILITY_QOS by default
// Change the kind to TRANSIENT_LOCAL_DURABILITY_QOS
writer_qos.durability().kind = TRANSIENT_LOCAL_DURABILITY_QOS;
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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 applies 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

// This example uses a Participant, but it can also be applied to
// DomainParticipantFactory, Publisher and Subscriber entities
DomainParticipantQos participant_qos;
// The EntityFactoryQosPolicy is constructed with autoenable_created_entities = true by default
// Change it to false
participant_qos.entity_factory().autoenable_created_entities = false;
// Use modified QoS in the creation of the corresponding entity
participant_ = factory_->create_participant(domain, participant_qos);

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 applies to Publisher and Subscriber entities.
It can be changed on enabled entities.

Example

// This example uses a Publisher, but it can also be applied to Subscriber entities
PublisherQos publisher_qos;
// The GroupDataQosPolicy is constructed with an empty collection by default
// Collection is a private member so you need to use getters and setters to access

// Add data to the collection in initialization
std::vector<eprosima::fastdds::rtps::octet> vec;
// Add two new octets to group data vector
eprosima::fastdds::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
publisher_qos.group_data().data_vec(vec); // Setter function
// Use modified QoS in the creation of the corresponding entity
publisher_ = participant_->create_publisher(publisher_qos);

// Add data to the collection at runtime
vec = publisher_qos.group_data().data_vec(); // Getter to keep old values
val = 31;
vec.push_back(val);
publisher_qos.group_data().data_vec(vec); // Setter function
// Update the QoS in the corresponding entity
publisher_->set_qos(publisher_qos);

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 applies 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:

Example

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The HistoryQosPolicy is constructed with kind = KEEP_LAST and depth = 1 by default
// It is possible to adjust the depth and keep the kind as KEEP_LAST
writer_qos.history().depth = 20;
// Or you can also change the kind to KEEP_ALL (depth will not be used).
writer_qos.history().kind = KEEP_ALL_HISTORY_QOS;
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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 applies to Topic, DataReader and DataWriter entities.
It can be changed on enabled entities.

Example

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The LifespanQosPolicy is constructed with duration set to infinite by default
// Change the duration to 5 s
writer_qos.lifespan().duration = {5, 0};
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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

Note

This QoS Policy applies 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 < MANUAL_BY_PARTICIPANT_LIVELINESS_QOS < MANUAL_BY_TOPIC_LIVELINESS_QOS

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

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The LivelinessQosPolicy is constructed with kind = AUTOMATIC by default
// Change the kind to MANUAL_BY_PARTICIPANT
writer_qos.liveliness().kind = MANUAL_BY_PARTICIPANT_LIVELINESS_QOS;
// The LivelinessQosPolicy is constructed with lease_duration set to infinite by default
// Change the lease_duration to 1 second
writer_qos.liveliness().lease_duration = {1, 0};
// The LivelinessQosPolicy is constructed with announcement_period set to infinite by default
// Change the announcement_period to 1 ms
writer_qos.liveliness().announcement_period = {0, 1000000};
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The OwnershipQosPolicy is constructed with kind = SHARED by default
// Change the kind to EXCLUSIVE
writer_qos.ownership().kind = EXCLUSIVE_OWNERSHIP_QOS;
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies to DataWriter entities.
It can be changed on enabled entities.

Example

// This example only applies to DataWriter entities
DataWriterQos writer_qos;
// The OwnershipStrengthQosPolicy is constructed with value 0 by default
// Change the strength to 10
writer_qos.ownership_strength().value = 10;
// Use modified QoS in the creation of the corresponding DataWriter
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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 entities.

Example

// This example uses a Publisher, but it can also be applied to Subscriber entities
PublisherQos publisher_qos;
// The PartitionsQosPolicy is constructed with max_size = 0 by default
// Max_size is a private member so you need to use getters and setters to access
// Change the max_size to 20
publisher_qos.partition().set_max_size(20); // Setter function
// The PartitionsQosPolicy is constructed with an empty list of partitions by default
// Partitions is a private member so you need to use getters and setters to access

// Add new partitions in initialization
std::vector<std::string> part;
part.push_back("part1");
part.push_back("part2");
publisher_qos.partition().names(part); // Setter function
// Use modified QoS in the creation of the corresponding entity
publisher_ = participant_->create_publisher(publisher_qos);

// Add data to the collection at runtime
part = publisher_qos.partition().names(); // Getter to keep old values
part.push_back("part3");
publisher_qos.partition().names(part); // Setter function
// Update the QoS in the corresponding entity
publisher_->set_qos(publisher_qos);

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 applies 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

Note

This QoS Policy applies 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

Note

This QoS Policy applies 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 < RELIABLE_RELIABILITY_QOS

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

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The ReliabilityQosPolicy is constructed with kind = BEST_EFFORT by default
// Change the kind to RELIABLE
writer_qos.reliability().kind = RELIABLE_RELIABILITY_QOS;
// The ReliabilityQosPolicy is constructed with max_blocking_time = 100ms by default
// Change the max_blocking_time to 1s
writer_qos.reliability().max_blocking_time = {1, 0};
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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:

Example

// This example uses a DataWriter, but it can also be applied to DataReader and Topic entities
DataWriterQos writer_qos;
// The ResourceLimitsQosPolicy is constructed with max_samples = 5000 by default
// Change max_samples to 200
writer_qos.resource_limits().max_samples = 200;
// The ResourceLimitsQosPolicy is constructed with max_instances = 10 by default
// Change max_instances to 20
writer_qos.resource_limits().max_instances = 20;
// The ResourceLimitsQosPolicy is constructed with max_samples_per_instance = 400 by default
// Change max_samples_per_instance to 100 as it must be lower than max_samples
writer_qos.resource_limits().max_samples_per_instance = 100;
// The ResourceLimitsQosPolicy is constructed with allocated_samples = 100 by default
// Change allocated_samples to 50
writer_qos.resource_limits().allocated_samples = 50;
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies 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 applies to Topic entities.
It can be changed even if it is already created.

Example

// This example only applies to Topic entities
TopicQos topic_qos;
// The TopicDataQosPolicy is constructed with an empty vector by default
std::vector<eprosima::fastdds::rtps::octet> vec;
// Add two new octets to topic data vector
eprosima::fastdds::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
topic_qos.topic_data().data_vec(vec); // Setter Function
// Use modified QoS in the creation of the corresponding Topic
topic_ = participant_->create_topic("<topic_name>", "<type_name>", topic_qos);

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 applies 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 applies to DomainParticipant, DataWriter and DataReader entities.
It can be changed on enabled entities.

Example

// This example uses a DataWriter, but it can also be applied to DomainParticipant and DataReader entities
DataWriterQos writer_qos;
std::vector<eprosima::fastdds::rtps::octet> vec;
// Add two new octets to user data vector
eprosima::fastdds::rtps::octet val = 3;
vec.push_back(val);
val = 10;
vec.push_back(val);
writer_qos.user_data().data_vec(vec); // Setter Function
// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);

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 applies to DataWriter entities.
It can be changed on enabled entities.