13.1. Non consolidated QoS¶
The PropertyPolicyQos Options are used to develop new eProsima Extensions QoS. Before consolidating a new QoS Policy, it is usually set using this generic QoS Policy. Consequently, this section is prone to frequent updates so the user is advised to check latest changes after upgrading to a different release version.
13.1.1. DataWriter operating mode
QoS Policy¶
By default, Fast DDS DataWriters are enabled using push mode
.
This implies that they will add new samples into their queue, and then immediately deliver them to matched readers.
For writers that produce non periodic bursts of data, this may imply saturating the network with a lot of packets,
increasing the possibility of losing them on unreliable (i.e. UDP) transports.
Depending on their QoS, DataReaders may also have to ignore some received samples, so they will have to be resent.
Configuring the DataWriters on pull mode
offers an alternative by letting each reader pace its own data stream.
It works by the writer notifying the reader what it is available, and waiting for it to request only as much as it
can handle.
At the cost of greater latency, this model can deliver reliability while using far fewer packets than push mode
.
DataWriters periodically announce the state of their queue by means of a heartbeat. Upon reception of the heartbeat, DataReaders will request the DataWriter to send the samples they want to process. Consequently, the publishing rate can be tuned setting the heartbeat period accordingly. See Tuning Heartbeat Period for more details.
PropertyPolicyQos name |
PropertyPolicyQos value |
Default value |
---|---|---|
|
|
|
C++ |
DataWriterQos wqos;
// Enable pull mode
wqos.properties().properties().emplace_back(
"fastdds.push_mode",
"false");
|
XML |
<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<data_writer profile_name="pull_mode_datawriter_xml_profile">
<propertiesPolicy>
<properties>
<!-- Enable pull mode -->
<property>
<name>fastdds.push_mode</name>
<value>false</value>
</property>
</properties>
</propertiesPolicy>
</data_writer>
</profiles>
|
Note
Communication to readers running on the same process (Intra-process delivery) will always use
push mode
.Communication to
BEST_EFFORT_RELIABILITY_QOS
readers will always usepush mode
.
Warning
It is inconsistent to enable the
pull mode
and also set theReliabilityQosPolicyKind
toBEST_EFFORT_RELIABILITY_QOS
.It is inconsistent to enable the
pull mode
and also set theheartbeatPeriod
toc_TimeInfinite
.
13.1.2. Unique network flows QoS Policy¶
Warning
This section is still under work.
13.1.3. Statistics Module Settings¶
Fast DDS Statistics Module uses the PropertyPolicyQos to indicate the statistics DataWriters that are enabled automatically (see Automatically enabling statistics DataWriters). In this case, the property value is a semicolon separated list containing the statistics topic name aliases of those DataWriters that the user wants to enable.
PropertyPolicyQos name |
PropertyPolicyQos value |
Default value |
---|---|---|
|
Semicolon separated list of statistics topic name aliases |
|
C++ |
DomainParticipantQos pqos;
// Activate Fast DDS Statistics module
pqos.properties().properties().emplace_back("fastdds.statistics",
"HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC");
|
XML |
<participant profile_name="statistics_domainparticipant_conf_xml_profile">
<rtps>
<propertiesPolicy>
<properties>
<!-- Activate Fast DDS Statistics Module -->
<property>
<name>fastdds.statistics</name>
<value>HISTORY_LATENCY_TOPIC;ACKNACK_COUNT_TOPIC;DISCOVERY_TOPIC;PHYSICAL_DATA_TOPIC</value>
</property>
</properties>
</propertiesPolicy>
</rtps>
</participant>
|
13.1.3.1. Physical Data in Discovery Information¶
It is possible to include the information conveyed in the PHYSICAL_DATA_TOPIC into the participant discovery message, a.k.a DATA[p] (see Discovery phases). This is done by setting the following properties within the PropertyPolicyQos:
PropertyPolicyQos name |
PropertyPolicyQos value |
Default value without |
Default value with |
---|---|---|---|
|
Name of the host computer in which |
Not set |
|
|
Name of the user running the application |
Not set |
|
|
Name of the process running the application |
Not set |
|
Whenever any of these properties is defined within the DomainParticipantQos
, the DomainParticipant
DATA[p]
will contained the set value.
Furthermore, if any of these properties is set to a value of ""
, which is the default when FASTDDS_STATISTICS
is
defined (see CMake options), Fast DDS will automatically populate the value using the following convention:
"fastdds.physical_data.host"
: Host name as returned by asio::ip::host_name(), followed by":<default data sharing domain id>"
"fastdds.physical_data.user"
: Name of the user running the application, or"unknown"
if it could not be retrieved."fastdds.physical_data.process"
: The process ID of the process in which the application is running.
All the previous entails that adding physical information to the DATA[p] can be done regardless of whether
FASTDDS_STATISTICS
is defined, and that it is possible to let Fast DDS set some default values into the
reported host
, user
, and process
:
If
FASTDDS_STATISTICS
is defined, and the user does not specify otherwise, Fast DDS will set default values to the physical properties of the DATA[p].If
FASTDDS_STATISTICS
is defined, and the user sets values to the properties, the user settings are honored.If
FASTDDS_STATISTICS
is defined, and the user removes the physical properties from theDomainParticipantQos
, then no physical information is transmitted in the DATA[p].If
FASTDDS_STATISTICS
is not defined, it is still possible to transmit physical information in the DATA[p] by setting the aforementioned properties:If set to
""
, then Fast DDS will populate their value according to the described rules.If set to something other than
""
, then the set value will be transmitted in the DATA[p] as-is.
In case FASTDDS_STATISTICS
is defined, and the reporting of statistics over the DISCOVERY_TOPIC
is enabled (see
Statistics Module Settings), then the physical information included in the DATA[p] is also transmitted over
the DISCOVERY_TOPIC
(see PHYSICAL_DATA_TOPIC) whenever one DomainParticipant
discovers
another one.
/* Create participant which announces default physical properties */
DomainParticipantQos pqos_default_physical;
// NOTE: If FASTDDS_STATISTICS is defined, then setting the properties to "" is not necessary
pqos_default_physical.properties().properties().emplace_back("fastdds.physical_data.host", "");
pqos_default_physical.properties().properties().emplace_back("fastdds.physical_data.user", "");
pqos_default_physical.properties().properties().emplace_back("fastdds.physical_data.process", "");
DomainParticipant* participant_with_physical = DomainParticipantFactory::get_instance()->create_participant(0,
pqos_default_physical);
/* Create participant which announces custom physical properties */
DomainParticipantQos pqos_custom_physical;
// NOTE: If FASTDDS_STATISTICS is defined, then clear the properties before setting them
// pqos_custom_physical.properties().properties().clear()
pqos_custom_physical.properties().properties().emplace_back("fastdds.physical_data.host", "custom_hostname");
pqos_custom_physical.properties().properties().emplace_back("fastdds.physical_data.user", "custom_username");
pqos_custom_physical.properties().properties().emplace_back("fastdds.physical_data.process", "custom_process");
DomainParticipant* participant_custom_physical = DomainParticipantFactory::get_instance()->create_participant(0,
pqos_custom_physical);
/* Create participant which does not announce physical properties */
DomainParticipantQos pqos_no_physical;
pqos_no_physical.properties().properties().clear();
DomainParticipant* participant_without_physical = DomainParticipantFactory::get_instance()->create_participant(
0, pqos_no_physical);
/* Load physical properties from default XML file */
DomainParticipantFactory::get_instance()->load_profiles();
DomainParticipantQos pqos_default_xml_physical =
DomainParticipantFactory::get_instance()->get_default_participant_qos();
DomainParticipant* participant_default_xml_physical =
DomainParticipantFactory::get_instance()->create_participant(0, pqos_default_xml_physical);
/* Load physical properties from specific XML file */
DomainParticipantFactory::get_instance()->load_XML_profiles_file("somefile.xml");
DomainParticipantFactory::get_instance()->load_profiles();
DomainParticipantQos pqos_custom_xml_physical =
DomainParticipantFactory::get_instance()->get_default_participant_qos();
DomainParticipant* participant_custom_xml_physical =
DomainParticipantFactory::get_instance()->create_participant(0, pqos_custom_xml_physical);
<?xml version="1.0" encoding="utf-8"?>
<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<profiles>
<participant profile_name="statistics_participant" is_default_profile="true">
<rtps>
<propertiesPolicy>
<properties>
<property>
<name>fastdds.physical_data.host</name>
<value>custom_hostname</value>
</property>
<property>
<name>fastdds.physical_data.user</name>
<value>custom_username</value>
</property>
<property>
<name>fastdds.physical_data.process</name>
<value>custom_process</value>
</property>
</properties>
</propertiesPolicy>
</rtps>
</participant>
</profiles>
</dds>
Important
The properties set using XML override those in the default QoS, which means that it is possible to set the physical
properties using XML regardless of whether FASTDDS_STATISTICS
is defined.
However, it is not possible to remove the properties using XML, meaning that an application using Fast DDS with
FASTDDS_STATISTICS
enabled which does not want for the physical information to be transmitted in the
DomainParticipant
DATA[p] must remove the properties using the aforementioned C++ API.
13.1.4. Endpoint Partitions¶
Fast DDS uses this PropertyPolicyQos to define which partitions does an endpoint belong to. This property follows the same logic regarding matching as the PartitionQosPolicy that can be defined for Publishers and Subscribers.
This property’s value is a semicolon separated list containing the partition names the user wants this endpoint to belong to.
Important
If both a Publisher and one of its DataWriters have conflicting partition configuration, this is, a DataWriter has this property defined while the Publisher has the PartitionQosPolicy defined, the DataWriter configuration takes precedence and the Publisher PartitionQosPolicy is ignored for this endpoint. This applies to Subscribers and their DataReaders as well.
This property will be automatically set when creating DataReaders and DataWriters using the create_with_profile functions. It cannot be changed after the entity has been created.
PropertyPolicyQos name |
PropertyPolicyQos value |
Default value |
---|---|---|
|
Semicolon separated list of partition names |
|
C++ |
DataWriterQos wqos;
// Add partitions
wqos.properties().properties().emplace_back(
"partitions",
"part1;part2");
DataReaderQos rqos;
// Add partitions
rqos.properties().properties().emplace_back(
"partitions",
"part1;part2");
|
XML |
<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>
|
13.1.5. Static Discovery’s Exchange Format¶
Static Discovery exchanges data in the Participant Discovery Phase (PDP).
Currently there are two different exchange formats which can be selected using the property
dds.discovery.static_edp.exchange_format
.
PropertyPolicyQos value |
Description |
Default |
---|---|---|
|
Standard exchange format for Static Discovery. |
✅ |
|
Format which reduces the necessary network bandwidth to transmit Static |
DomainParticipantQos participant_qos;
participant_qos.properties().properties().emplace_back(
"dds.discovery.static_edp.exchange_format",
"v1_Reduced"
);
<participant profile_name="participant_xml_conf_static_discovery_format_profile">
<rtps>
<propertiesPolicy>
<properties>
<property>
<name>dds.discovery.static_edp.exchange_format</name>
<value>v1_Reduced</value>
</property>
</properties>
</propertiesPolicy>
</rtps>
</participant>