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 |
---|---|---|
|
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);
<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 |
---|---|---|
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 |
---|---|---|
Yes |
||
No |
||
Yes |
||
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 |
---|---|---|
|
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
):
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
: When a new DataReader joins, its History is filled with past samples, which are stored on persistent storage (see Persistence Service).
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 |
---|---|---|
Yes |
||
No |
||
No |
||
Yes |
||
Yes |
||
No |
||
Yes |
||
Yes |
||
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);
<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 |
---|---|---|
|
||
|
1 |
|
|
-1 (Length Unlimited) |
|
|
-1 (Length Unlimited) |
|
|
-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 |
---|---|---|
|
|
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);
This QoS Policy cannot be configured using XML for the moment.
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< |
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);
<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 |
---|---|---|
|
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 toKEEP_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:
The
depth
is only considered if thekind
is set toKEEP_LAST_HISTORY_QOS
.The
depth
must be consistent with the ResourceLimitsQosPolicy settings, which means that thedepth
must be lower or equal than the ResourceLimitsQosPolicy’smax_samples_per_instance
. Also,max_samples
must be equal or higher than the product ofmax_samples_per_instance
timesmax_instances
.The
depth
cannot be lower or equal than zero. If an unlimited depth is required, please consider usingkind
asKEEP_ALL_HISTORY_QOS
.Setting the
kind
asKEEP_ALL_HISTORY_QOS
entails that limits are set by the ResourceLimitsQosPolicy limits (max_samples_per_instance
prior thanmax_samples
).In the case of the ReliabilityQosPolicy
ReliabilityQosPolicyKind
being set toRELIABLE_RELIABILITY_QOS
and the HistoryQosPolicykind
being set toKEEP_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 asVOLATILE_DURABILITY_QOS
, the DataWriterwrite()
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 asTRANSIENT_LOCAL_DURABILITY_QOS
orTRANSIENT_DURABILITY_QOS
, the DataWriterwrite()
call will be blocked until the history has space for the new sample.
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);
<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 |
---|---|---|
|
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 |
---|---|---|
|
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);
<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
: 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 isAUTOMATIC_LIVELINESS_QOS
orMANUAL_BY_PARTICIPANT_LIVELINESS_QOS
and needs to be lower than thelease_duration
.
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 |
---|---|---|
Yes |
||
No |
||
No |
||
Yes |
||
Yes |
||
No |
||
Yes |
||
Yes |
||
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);
<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 |
---|---|---|
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 |
---|---|---|
Yes |
||
No |
||
No |
||
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);
<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 |
---|---|---|
|
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);
<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 |
---|---|---|
|
0 (Length Unlimited) |
|
Empty List |
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);
<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
: 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 |
---|---|---|
Yes |
||
No |
||
No |
||
Yes |
||
Yes |
||
No |
||
Yes |
||
Yes |
||
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
: Defines the maximum duration the DataReader must retain the information regarding an instance once itsinstance_state
becomesNOT_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 itsinstance_state
becomesNOT_ALIVE_DISPOSED_INSTANCE_STATE
. After this time elapses, the DataReader purges all the samples for the instance.
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 |
---|---|---|
|
||
|
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 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 themax_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 |
---|---|---|
Yes |
||
No |
||
Yes |
||
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);
<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 |
---|---|---|
|
5000 |
|
|
10 |
|
|
400 |
|
|
100 |
|
|
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 bemax_samples
plusextra_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:
The value of
max_samples
must be higher or equal to the value ofmax_samples_per_instance
.The value established for the HistoryQosPolicy
depth
must be lower or equal to the value stated formax_samples_per_instance
.
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);
<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 |
---|---|---|
|
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< |
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);
<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 |
---|---|---|
|
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< |
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);
<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 |
---|---|---|
|
|
Note
This QoS Policy applies to DataWriter entities.
It can be changed on enabled entities.