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

12.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
"fastdds.push_mode"	"true"/"false"	"true"

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">
<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 use push mode.

Warning

• It is inconsistent to enable the pull mode and also set the ReliabilityQosPolicyKind to BEST_EFFORT_RELIABILITY_QOS.

• It is inconsistent to enable the pull mode and also set the heartbeat_period to c_TimeInfinite.

12.1.2. Unique network flows QoS Policy

This QoS Policy allows a DataReader to be created with a unique network flow, i.e. listening on a port that is not shared with any other endpoint of the same DomainParticipant. This is useful when the application needs to apply specific Network QoS parameters (for example, through 3GPP/5QI configuration on the underlying networking equipment) to the traffic of a particular topic.

The feature is enabled by adding the property "fastdds.unique_network_flows" to the PropertyPolicyQos of the DataReader.

PropertyPolicyQos name	PropertyPolicyQos value	Default value
"fastdds.unique_network_flows"	""	Not set

For a complete description of network flows in Fast DDS, the APIs used to inspect them, and a usage example, see Unique network flows.

12.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
"fastdds.statistics"	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>

12.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 FASTDDS_STATISTICS	Default value with FASTDDS_STATISTICS
"fastdds.physical_data.host"	Name of the host computer in which the application runs	Not set	""
"fastdds.physical_data.user"	Name of the user running the application	Not set	""
"fastdds.physical_data.process"	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:

1. 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].

2. If FASTDDS_STATISTICS is defined, and the user sets values to the properties, the user settings are honored.

3. If FASTDDS_STATISTICS is defined, and the user removes the physical properties from the DomainParticipantQos, then no physical information is transmitted in the DATA[p].

4. If FASTDDS_STATISTICS is not defined, it is still possible to transmit physical information in the DATA[p] by setting the aforementioned properties:

   1. If set to "", then Fast DDS will populate their value according to the described rules.

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

C++

/* 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

<?xml version="1.0" encoding="utf-8"?>
<dds xmlns="http://www.eprosima.com">
    <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.

12.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
"partitions"	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>

12.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
"v1"	Standard exchange format for Static Discovery.	✅
"v1_Reduced"	Format which reduces the necessary network bandwidth to transmit Static Discovery’s information in the Participant Discovery Phase (PDP).

C++

DomainParticipantQos participant_qos;
participant_qos.properties().properties().emplace_back(
    "dds.discovery.static_edp.exchange_format",
    "v1_Reduced"
    );

XML

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

12.1.6. SHM transport meta-traffic enforcement

A DomainParticipant will by default configure both a UDP Transport and a Shared Memory Transport. When a participant on another process in the same host is discovered, the endpoint discovery might be done using either transport.

Avoiding Shared Memory communication for discovery traffic can save valuable resources. The behavior regarding this can be configured using the property fastdds.shm.enforce_metatraffic.

PropertyPolicyQos value	Description	Default
"none"	Use other transports for meta-traffic.	✅
"unicast"	Enable SHM transport unicast communications.
"all"	Enable SHM transport unicast and multicast communications. This will enable discovery between SHM only participants and participants having several transports.

Note

When SHM is the only transport configured for a participant, the setting of this property is ignored, and considered to be "all".

C++

DomainParticipantQos participant_qos;

// SHM transport will listen for unicast meta-traffic
participant_qos.properties().properties().emplace_back(
    "fastdds.shm.enforce_metatraffic",
    "unicast");

XML

<participant profile_name="participant_xml_conf_shm_enforce_metatraffic_profile">
    <rtps>
        <propertiesPolicy>
            <properties>
                <property>
                    <name>fastdds.shm.enforce_metatraffic</name>
                    <value>unicast</value>
                </property>
            </properties>
        </propertiesPolicy>
    </rtps>
</participant>

12.1.7. Maximum Message Size

One common requirement is the differentiation between the maximum size of received and sent datagrams. This capability is especially important in scenarios where a system might need to handle large incoming data sizes but should restrict the size of the data it sends to prevent overwhelming network resources or complying with network traffic policies. The primary attribute for controlling datagram size is maxMessageSize, which sets the upper limit for both the size of datagrams that can be received and those that can be sent. Property fastdds.max_message_size allows restricting the size of outgoing datagrams without changing the size of incoming ones. This property allows for the specific configuration of the maximum number of bytes for datagrams that are sent. By configuring this property to a value lower than the smallest maxMessageSize across all transports, applications can achieve a lower sending limit while maintaining the ability to receive larger datagrams.

PropertyPolicyQos name	PropertyPolicyQos value	Default value
"fastdds.max_message_size"	uint32_t	"4294967295"

Note

An invalid value of fastdds.max_message_size would log an error, and the default value will be used.

12.1.7.1. Setting fastdds.max_message_size At Participant Level

C++

DomainParticipantQos pqos;

// Set maximum number of bytes of the datagram to be sent
pqos.properties().properties().emplace_back(
    "fastdds.max_message_size",
    "1200");

XML

<?xml version="1.0" encoding="UTF-8" ?>
<participant profile_name="max_message_size_participant_xml_profile">
    <rtps>
        <propertiesPolicy>
            <properties>
                <!-- Set the maximum size in bytes for all RTPS datagrams sent by the participant -->
                <property>
                    <name>fastdds.max_message_size</name>
                    <value>1200</value>
                </property>
            </properties>
        </propertiesPolicy>
    </rtps>
</participant>

12.1.7.2. Setting fastdds.max_message_size At Writer Level

C++

DataWriterQos wqos;

// Set maximum number of bytes of the datagram to be sent
wqos.properties().properties().emplace_back(
    "fastdds.max_message_size",
    "1200");

XML

<?xml version="1.0" encoding="UTF-8" ?>
<data_writer profile_name="max_msg_size_datawriter_xml_profile">
    <propertiesPolicy>
        <properties>
            <!-- Set the maximum size in bytes for all RTPS datagrams sent by the writer -->
            <property>
                <name>fastdds.max_message_size</name>
                <value>1200</value>
            </property>
        </properties>
    </propertiesPolicy>
</data_writer>

12.1.8. Type Propagation

By default, Fast DDS leverages Remote Data Types Discovery both to discover remote types and to propagate local ones. Type propagation entails both adding meta-information to the EDP messages (see Discovery phases) and using a dedicated set of builtin endpoints to transmit type definitions between the different DomainParticipants in the network.

Depending on the application design and deployment, it might be desirable to change the default type propagation behavior to save bandwidth and/or resources. For this reason, Fast DDS DomainParticipants can be configured with a property fastdds.type_propagation that controls how type information is propagated.

PropertyPolicyQos name	PropertyPolicyQos value	Default value
"fastdds.type_propagation"	"disabled" "enabled" "minimal_bandwidth" "registration_only"	"enabled"

The different property values have the following effects on the local DomainParticipant:

Value	TypeObject registration	Send type information on EDP	Receive type information on EDP	Type lookup service replies
"disabled"	NO	NO	IGNORED	DISABLED
"enabled"	COMPLETE and MINIMAL	COMPLETE and MINIMAL	PROCESSED	ENABLED
"minimal_bandwidth"	MINIMAL only	MINIMAL only	Only MINIMAL PROCESSED	ENABLED
"registration_only"	COMPLETE and MINIMAL	COMPLETE and MINIMAL	IGNORED	DISABLED

C++

DomainParticipantQos pqos;

pqos.properties().properties().emplace_back(
    "fastdds.type_propagation",
    "disabled");

XML

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <participant profile_name="type_propagation_domainparticipant_xml_profile">
            <rtps>
                <propertiesPolicy>
                    <properties>
                        <property>
                            <name>fastdds.type_propagation</name>
                            <value>disabled</value>
                        </property>
                    </properties>
                </propertiesPolicy>
            </rtps>
        </participant>
    </profiles>
</dds>

12.1.9. Adding optional QoS to Discovery data

During Discovery, DomainParticipants, DataWriters and DataReaders acknowledge each other. This is performed in two phases, the Participant Discovery Phase (PDP) and the Endpoint Discovery Phase (EDP). To do that, the DomainParticipants share information about their DataWriters and DataReaders with each other, using the communication channels established during the PDP phase. This information contains all data required to match the endpoints, such as the Topic, data type, and certain QoS Policies that might affect matching. Specific compatibility rules can be found in each QoS section of QoS Policies.

However, there are some QoS that are not mandatory for matching, but can be useful to have upon discovery. Property fastdds.serialize_optional_qos allows the user to include these optional QoS during discovery. This property is configured at the DomainParticipant level through the policy PropertyPolicyQos. Hence, the DomainParticipant and all its associated endpoints will send their optional QoS in the discovery messages.

Optional QoS, like any other QoS, will only be serialized if they have non-default values. Not receiving information about a QoS in the EDP message means that it has a default value. Optional QoS will be serialized if the value of the property is set to TRUE, True, true or 1, any other value will be considered as not set or FALSE.

The following table lists all the optional QoS that can be serialized in the discovery messages:

PropertyPolicyQos	Applies to:
WireProtocolConfigQos	DomainParticipant.
ResourceLimitsQosPolicy	DataWriter and DataReaders.
TransportPriorityQosPolicy	DataWriter.
WriterDataLifecycleQosPolicy	DataWriter.
ReaderDataLifecycleQosPolicy	DataReaders.
PublishModeQosPolicy	DataWriter.
RTPSReliableWriterQos	DataWriter.
RTPSReliableReaderQos	DataReaders.
RTPSEndpointQos	DataWriter and DataReaders.
WriterResourceLimitsQos	DataWriter.
ReaderResourceLimitsQos	DataReaders.

C++

DomainParticipantQos pqos;

pqos.properties().properties().emplace_back(
    "fastdds.serialize_optional_qos",
    "true"); // true or True or TRUE or 1

XML

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <participant profile_name="serialize_optional_qos_domainparticipant_xml_profile">
            <rtps>
                <propertiesPolicy>
                    <properties>
                        <property>
                            <name>fastdds.serialize_optional_qos</name>
                            <value>true</value> <!-- true, True, TRUE, 1 -->
                        </property>
                    </properties>
                </propertiesPolicy>
            </rtps>
        </participant>
    </profiles>
</dds>

12.1.10. SQL Filter Expression limits

When creating content-filtered topics using the default SQL-like filter, some restrictions apply to the SQL expressions that can be used for content-based filtering. The default limits are set to values that should be enough for most use cases, but they can be customized using the following properties when a participant is created:

PropertyPolicyQos name	PropertyPolicyQos value	Default value
"dds.sql.expression.max_expression_length"	Maximum length of the SQL expression, in characters.	16384
"dds.sql.expression.max_subexpressions"	Maximum number of sub-expressions in the SQL expression.	256

Creating content-filtered topics with expressions exceeding any of these limits will fail. Expressions received in discovery messages exceeding any of these limits will be ignored, and filtering will happen in the reader side.

C++

DomainParticipantQos pqos;

pqos.properties().properties().emplace_back(
    "dds.sql.expression.max_expression_length",
    "20000");
pqos.properties().properties().emplace_back(
    "dds.sql.expression.max_subexpressions",
    "10");

XML

<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com">
    <profiles>
        <participant profile_name="custom_sql_limits_domainparticipant_xml_profile">
            <rtps>
                <propertiesPolicy>
                    <properties>
                        <property>
                            <name>dds.sql.expression.max_expression_length</name>
                            <value>20000</value>
                        </property>
                        <property>
                            <name>dds.sql.expression.max_subexpressions</name>
                            <value>10</value>
                        </property>
                    </properties>
                </propertiesPolicy>
            </rtps>
        </participant>
    </profiles>
</dds>