11.2. DomainParticipant profiles

The DomainParticipant profiles allow the definition of the configuration of DomainParticipants through XML files. These profiles are defined within the <participant> XML tags.

11.2.1. DomainParticipant XML attributes

The <participant> element has two attributes defined: profile_name and is_default_profile.

Name

Description

Use

profile_name

Sets the name under which the <participant> profile is registered in the DDS Domain,
so that it can be loaded later by the DomainParticipantFactory, as shown in
Loading and applying profiles.

Mandatory

is_default_profile

Sets the <participant> profile as the default profile. Thus, if a default profile
exists, it will be used when no other DomainParticipant profile is specified at the
DomainParticipant’s creation.

Optional

11.2.2. DomainParticipant configuration

The <participant> element has two child elements: <domainId> and <rtps>. All the DomainParticipant configuration options belong to the <rtps> element, except for the DDS DomainId which is defined by the <domainId> element. Below a list with the configuration XML elements is presented:

Name

Description

Values

Default

<domainId>

DomainId to be used by the DomainParticipant. See Profile based creation of a DomainParticipant.

uint32_t

0

<rtps>

Fast DDS DomainParticipant configurations.
See RTPS element type.

RTPS element type

11.2.2.1. RTPS element type

The following is a list with all the possible child XML elements of the <rtps> element. These elements allow the user to define the DomainParticipant configuration.

Name

Description

Values

Default

<name>

The DomainParticipant’s name.

string_255

<defaultUnicastLocatorList>

List of default reception unicast locators
for user data traffic (see
<metatrafficUnicastLocatorList>
defined in Builtin parameters).
It expects a LocatorListType.

<locator>

<defaultMulticastLocatorList>

List of default reception multicast
locators for user data traffic (see
<metatrafficMulticastLocatorList>
defined in Builtin parameters).
It expects a LocatorListType.

<locator>

<default_external_unicast_locators>

List of External Locators
to announce for the default user traffic of
this participant.

ExternalLocatorListType

<ignore_non_matching_locators>

Whether to ignore locators received on
announcements from other participants when
they don’t match with any of the locators
announced by this participant.

bool

false

<sendSocketBufferSize>

Size in bytes of the send socket buffer.
If the value is zero then Fast DDS will
use the system default socket size.

uint32_t

0

<listenSocketBufferSize>

Size in bytes of the reception socket
buffer. If the value is zero then
Fast DDS will use the system default
socket size.

uint32_t

0

<builtin>

builtin public data member of the
WireProtocolConfigQos class.
See the Builtin parameters section.

Builtin parameters

<port>

Allows defining the port and gains related
to the RTPS protocol. See the Port section.

Port

<participantID>

DomainParticipant’s identifier. Typically
it will be automatically generated by the
DomainParticipantFactory.

int32_t

0

<userTransports>

Transport descriptors to be used by the
DomainParticipant. See
Transport descriptors.

List <string>

<useBuiltinTransports>

Boolean field to indicate the system
whether the DomainParticipant will use the
default builtin transports
in addition to its <userTransports>.

bool

true

<propertiesPolicy>

Additional configuration properties.
See PropertyPolicyQos.

PropertiesPolicyType

<allocation>

Configuration regarding allocation behavior.
It expects a
DomainParticipantAllocationType.

DomainParticipantAllocationType

<userData>

Additional information attached to the DomainParticipant
and transmitted with the discovery information.
See UserDataQosPolicy.

List <string>

Empty

<prefix>

DomainParticipant’s GuidPrefix_t identifies peers
running in the same process. Two participants with identical
8 first bytes on the GuidPrefix_t are considered to be
running in the same process, and therefore intra-process
delivery is used. See Intra-process delivery.

string

Empty

Example

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="domainparticipant_profile_name">
        <domainId>4</domainId>
        <rtps>
            <name>DomainParticipant Name</name>

            <defaultUnicastLocatorList>
                <!-- LOCATOR_LIST -->
                <locator>
                    <udpv4>
                        <port>7400</port>
                        <address>192.168.1.41</address>
                    </udpv4>
                </locator>
            </defaultUnicastLocatorList>

            <defaultMulticastLocatorList>
                <!-- LOCATOR_LIST -->
                <locator>
                    <udpv4>
                        <port>7400</port>
                        <address>192.168.2.41</address>
                    </udpv4>
                </locator>
            </defaultMulticastLocatorList>

            <default_external_unicast_locators>
                <!-- EXTERNAL_LOCATOR_LIST -->
                <udpv4 externality="1" cost="0" mask="24">
                    <address>100.100.100.10</address>
                    <port>23456</port>
                </udpv4>
            </default_external_unicast_locators>

            <ignore_non_matching_locators>true</ignore_non_matching_locators>

            <sendSocketBufferSize>8192</sendSocketBufferSize>

            <listenSocketBufferSize>8192</listenSocketBufferSize>

            <builtin>
                <!-- BUILTIN -->
            </builtin>

            <port>
                <portBase>7400</portBase>
                <domainIDGain>200</domainIDGain>
                <participantIDGain>10</participantIDGain>
                <offsetd0>0</offsetd0>
                <offsetd1>1</offsetd1>
                <offsetd2>2</offsetd2>
                <offsetd3>3</offsetd3>
            </port>

            <participantID>99</participantID>

            <userTransports>
                <transport_id>TransportId1</transport_id>
                <transport_id>TransportId2</transport_id>
            </userTransports>

            <useBuiltinTransports>false</useBuiltinTransports>

            <propertiesPolicy>
                <!-- PROPERTIES_POLICY -->
                <properties>
                    <property>
                        <name>Property1Name</name>
                        <value>Property1Value</value>
                        <propagate>false</propagate>
                    </property>
                </properties>
            </propertiesPolicy>

            <allocation>
                <!-- ALLOCATION -->
            </allocation>

            <userData>
                <value>3.4.7.0.C</value>
            </userData>

            <prefix>72.61.73.70.66.61.72.6d.74.65.73.74</prefix>
        </rtps>
    </participant>
</profiles>

Note

11.2.2.2. Builtin parameters

By calling the wire_protocol() member function of the DomainParticipantQos, it is possible to access the builtin public data member of the WireProtocolConfigQos class. This section specifies the available XML members for the configuration of this builtin parameters.

Name

Description

Values

Default

<discovery_config>

This is the main element within
which discovery-related
settings can be configured.
See Discovery.

discovery_config

<avoid_builtin_multicast>

Restricts multicast metatraffic
to PDP only.

bool

true

<use_WriterLivelinessProtocol>

Indicates whether to use the
DataWriterLiveliness protocol.

bool

true

<metatrafficUnicastLocatorList>

Metatraffic Unicast Locator List.

A set of <locator>
members.
See LocatorListType

<metatrafficMulticastLocatorList>

Metatraffic Multicast Locator List.

A set of <locator>
members.
See LocatorListType

<initialPeersList>

The list of IP-port address
pairs of all other
DomainParticipants with which
a DomainParticipant will
communicate. See
Initial peers

A set of <locator>
members.
See LocatorListType

<metatraffic_external_unicast_locators>

List of External Locators
to announce for the metatraffic of
this participant.

ExternalLocatorListType

<readerHistoryMemoryPolicy>

Memory policy for DataReaders.
See HistoryQosPolicyKind.

HistoryMemoryPolicy

PREALLOCATED

<writerHistoryMemoryPolicy>

Memory policy for DataWriters.
See HistoryQosPolicyKind.

HistoryMemoryPolicy

PREALLOCATED

<readerPayloadSize>

Maximum DataReader’s History
payload size. Allows to reserve
all the required memory at
DataReader initialization.
See MemoryManagementPolicy.

uint32_t

512

<writerPayloadSize>

Maximum DataWriter’s History
payload size. Allows to reserve
all the required memory at
DataWriter initialization.
See MemoryManagementPolicy.

uint32_t

512

<mutation_tries>

Number of different ports
to try if DataReader’s physical
port is already in use.

uint32_t

100

Example

<builtin>
    <discovery_config>
        <discoveryProtocol>CLIENT</discoveryProtocol>

        <discoveryServersList>
            <RemoteServer prefix="72.61.73.70.66.61.72.6d.74.65.73.74">
                <metatrafficUnicastLocatorList>
                    <locator>
                        <udpv4>
                            <address>192.168.10.57</address>
                            <port>56542</port>
                        </udpv4>
                    </locator>
                </metatrafficUnicastLocatorList>
                <metatrafficMulticastLocatorList>
                    <locator>
                        <udpv4>
                            <address>192.168.10.58</address>
                            <port>24565</port>
                        </udpv4>
                    </locator>
                </metatrafficMulticastLocatorList>
            </RemoteServer>
        </discoveryServersList>

        <ignoreParticipantFlags>FILTER_DIFFERENT_HOST</ignoreParticipantFlags>

        <EDP>SIMPLE</EDP>

        <simpleEDP>
            <PUBWRITER_SUBREADER>true</PUBWRITER_SUBREADER>
            <PUBREADER_SUBWRITER>true</PUBREADER_SUBWRITER>
        </simpleEDP>

        <leaseDuration>
            <!-- DURATION -->
            <sec>20</sec>
        </leaseDuration>

        <leaseAnnouncement>
            <!-- DURATION -->
            <sec>3</sec>
        </leaseAnnouncement>

        <initialAnnouncements>
            <!-- INITIAL_ANNOUNCEMENTS -->
            <count>10</count>
            <period>
                <nanosec>50</nanosec>
            </period>
        </initialAnnouncements>

        <clientAnnouncementPeriod>
            <nanosec>250000000</nanosec>
        </clientAnnouncementPeriod>

        <static_edp_xml_config>file://filename1.xml</static_edp_xml_config>
        <static_edp_xml_config>file://filename2.xml</static_edp_xml_config>
        <static_edp_xml_config>file://filename3.xml</static_edp_xml_config>
    </discovery_config>

    <avoid_builtin_multicast>true</avoid_builtin_multicast>

    <use_WriterLivelinessProtocol>false</use_WriterLivelinessProtocol>

    <metatrafficUnicastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4>
                <address>192.168.0.1</address>
            </udpv4>
        </locator>
    </metatrafficUnicastLocatorList>

    <metatrafficMulticastLocatorList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4>
                <address>192.168.0.1</address>
            </udpv4>
        </locator>
    </metatrafficMulticastLocatorList>

    <initialPeersList>
        <!-- LOCATOR_LIST -->
        <locator>
            <udpv4>
                <address>192.168.0.1</address>
            </udpv4>
        </locator>
    </initialPeersList>

    <metatraffic_external_unicast_locators>
        <!-- EXTERNAL_LOCATOR_LIST -->
        <udpv4 externality="1" cost="0" mask="24">
            <address>100.100.100.10</address>
            <port>34567</port>
        </udpv4>
    </metatraffic_external_unicast_locators>

    <readerHistoryMemoryPolicy>PREALLOCATED_WITH_REALLOC</readerHistoryMemoryPolicy>

    <writerHistoryMemoryPolicy>PREALLOCATED_WITH_REALLOC</writerHistoryMemoryPolicy>

    <readerPayloadSize>512</readerPayloadSize>

    <writerPayloadSize>512</writerPayloadSize>

    <mutation_tries>55</mutation_tries>
</builtin>

11.2.2.2.1. discovery_config

Through the <discovery_config> element, Fast DDS allows the configuration of the discovery mechanism via an XML file. Please refer to the Discovery section for more detail on the various types of discovery mechanisms and configurable settings.

Name

Description

Values

Default

<discoveryProtocol>

Indicates which discovery protocol
the DomainParticipant will use.
See Discovery mechanisms. If set to
CLIENT, <discoveryServersList>
element would be used.

SIMPLE

SIMPLE

CLIENT

SERVER

BACKUP

NONE

<discoveryServersList>

Describes servers from which it receives
only the discovery information they
require to establish communication with
matching endpoints.
See Discovery Server Settings

discoveryServersList

<ignoreParticipantFlags>

Restricts metatraffic using several
filtering criteria. See Ignore Participant flags.

ignoreParticipantFlags

NO_FILTER

<EDP>

If set to SIMPLE, <simpleEDP>
element would be used.
If set to STATIC, EDPStatic will be
performed, configured with the contents
of the XML file set in <static_edp_xml_config>.
See Discovery.

SIMPLE

SIMPLE

STATIC

<simpleEDP>

Attributes of the Simple Discovery
Protocol. See Simple EDP Attributes.

simpleEDP

<leaseDuration>

Indicates how long the DomainParticipant
should consider remote DomainParticipants
alive. See Lease Duration.

DurationType

20s

<leaseAnnouncement>

The period for the DomainParticipant to
send its discovery message to all other
discovered DomainParticipants as well as
to all Multicast ports. See Announcement Period.

DurationType

3s

<initialAnnouncements>

Allows the user to configure the number
and period of the DomainParticipant’s initial
discovery messages. See Initial Announcements.

Initial Announcements

<clientAnnouncementPeriod>

The period for the DomainParticipant to
send its Discovery Message to its servers
and check for EDP endpoints matching.

DurationType

450 ms

<static_edp_xml_config>

The XML filename(s) with the static EDP
configuration. Only necessary if
the <EDP> member is set to
STATIC. See STATIC Discovery Settings.

List <string>
discoveryServersList

Contains a list of <RemoteServer> (server) elements, which are defined by the GuidPrefix_t and their own locator list which must be populated with RemoteServerAttributes. The DomainParticipant set as client would discover the servers described in this section.

Server attributes

The <RemoteServer> element has a mandatory attribute defined: prefix.

Name

Description

Use

prefix

RTPS standard participant unique identifier, a 12-byte chain.
This identifier allows clients to assess whether they are
receiving messages from the right server.

Mandatory

RemoteServer configuration

Each client (or a server connecting to another server) must keep a list of locators associated to the servers to which it wants to link. Those locator would be defined as metatrafficUnicastLocatorList or metatrafficMulticastLocatorList.

Name

Description

Values

<metatrafficUnicastLocatorList>

Metatraffic Unicast Locator List.

A set of <locator> members.
See LocatorListType

<metatrafficMulticastLocatorList>

Metatraffic Multicast Locator List.

A set of <locator> members.
See LocatorListType

Example

<?xml version="1.0" encoding="UTF-8" ?>
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
    <participant profile_name="UDP CLIENT" is_default_profile="true">
        <rtps>
            <builtin>
                <discovery_config>
                    <discoveryProtocol>CLIENT</discoveryProtocol>
                    <discoveryServersList>
                        <RemoteServer prefix="72.61.73.70.66.61.72.6d.74.65.73.74">
                            <metatrafficUnicastLocatorList>
                                <locator>
                                    <udpv4>
                                        <address>192.168.10.57</address>
                                        <port>56542</port>
                                    </udpv4>
                                </locator>
                            </metatrafficUnicastLocatorList>
                            <metatrafficMulticastLocatorList>
                                <locator>
                                    <udpv4>
                                        <address>192.168.10.58</address>
                                        <port>24565</port>
                                    </udpv4>
                                </locator>
                            </metatrafficMulticastLocatorList>
                        </RemoteServer>
                    </discoveryServersList>
                </discovery_config>
            </builtin>
        </rtps>
    </participant>
</profiles>
ignoreParticipantFlags

Possible values

Description

NO_FILTER

All Discovery traffic is processed.

FILTER_DIFFERENT_HOST

Discovery traffic from another host is discarded.

FILTER_DIFFERENT_PROCESS

Discovery traffic from another process on the same host is discarded.

FILTER_SAME_PROCESS

Discovery traffic from DomainParticipant’s own process is discarded.

This option also supports the OR (|) operator to filter discovery traffic from other configurations. For instance, FILTER_DIFFERENT_PROCESS|FILTER_SAME_PROCESS value discards discovery traffic from the DomainParticipant’s own host.

simpleEDP

Name

Description

Values

Default

<PUBWRITER_SUBREADER>

Indicates if the participant must use
Publication DataWriter and Subscription DataReader.

bool

true

<PUBREADER_SUBWRITER>

Indicates if the participant must use
Publication DataReader and Subscription DataWriter.

bool

true
Initial Announcements

Name

Description

Values

Default

<count>

Number of initial discovery messages to send at the period specified by
<period>. After these announcements, the DomainParticipant will continue
sending its discovery messages at the <leaseAnnouncement> rate.

uint32_t

5

<period>

The period for the DomainParticipant to send its discovery messages.

DurationType

100 ms

11.2.2.3. Port Configuration

According to the RTPS standard (Section 9.6.1.1), the RTPSParticipants’ discovery traffic unicast listening ports are calculated using the following equation: \(7400 + 250 * DomainId + 10 + 2 * ParticipantId\). Therefore the following parameters can be specified:

Name

Description

Values

Default

<portBase>

Base port.

uint16_t

7400

<domainIDGain>

Gain in DomainId.

uint16_t

250

<participantIDGain>

Gain in participant_id.

uint16_t

2

<offsetd0>

Multicast metadata offset.

uint16_t

0

<offsetd1>

Unicast metadata offset.

uint16_t

10

<offsetd2>

Multicast user data offset.

uint16_t

1

<offsetd3>

Unicast user data offset.

uint16_t

11

Warning

Changing these default parameters may break compatibility with other RTPS compliant implementations, as well as with other Fast DDS applications with default port settings.

11.2.2.4. ParticipantAllocationType

The ParticipantAllocationType defines the <allocation> element, which allows setting of the parameters related with the allocation behavior on the DomainParticipant. Please refer to ParticipantResourceLimitsQos for a detailed documentation on DomainParticipants allocation configuration.

Name

Description

Values

Default

<remote_locators>

Defines the limits for the remote locators’ collections.
See RemoteLocatorsAllocationAttributes.

Remote Locators Allocations

<total_participants>

DomainParticipant Allocation Configuration to specify the
total number of DomainParticipants in the domain
(local and remote). See
ResourceLimitedContainerConfig.

Allocation Configuration

<total_readers>

DomainParticipant Allocation Configuration to specify the
total number of DataReader on each DomainParticipant
(local and remote). See
ResourceLimitedContainerConfig.

Allocation Configuration

<total_writers>

DomainParticipant Allocation Configuration related to the
total number of DataWriters on each DomainParticipant
(local and remote). See ResourceLimitedContainerConfig.

Allocation Configuration

<max_partitions>

Maximum size of the partitions submessage.
Set to zero for no limit.

uint32_t

<max_user_data>

Maximum size of the user data submessage.
Set to zero for no limit.

uint32_t

<max_properties>

Maximum size of the properties submessage.
Set to zero for no limit.

uint32_t

<send_buffers>

Allocation behaviour for the send buffer
manager.

Send buffers

Example

<allocation>
    <remote_locators>
        <max_unicast_locators>4</max_unicast_locators>
        <max_multicast_locators>1</max_multicast_locators>
    </remote_locators>

    <total_participants>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_participants>

    <total_readers>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_readers>

    <total_writers>
        <initial>0</initial>
        <maximum>0</maximum>
        <increment>1</increment>
    </total_writers>

    <max_partitions>256</max_partitions>

    <max_user_data>256</max_user_data>

    <max_properties>512</max_properties>

    <send_buffers>
        <preallocated_number>127</preallocated_number>
        <dynamic>true</dynamic>
    </send_buffers>

    <!-- content_filter cannot be configured using XML (yet) -->
</allocation>

11.2.2.4.1. Remote Locators Allocations

Name

Description

Values

Default

<max_unicast_locators>

Maximum number of unicast locators expected on a
remote entity. It is recommended to use the maximum
number of network interfaces available on the machine
on which DomainParticipant is running.
See RemoteLocatorsAllocationAttributes.

uint32_t

4

<max_multicast_locators>

Maximum number of multicast locators expected on a
remote entity. May be set to zero to disable multicast
traffic. See RemoteLocatorsAllocationAttributes.

uint32_t

1

11.2.2.4.2. Send buffers

Name

Description

Values

Default

<preallocated_number>

Initial number of send buffers to allocate. See
SendBuffersAllocationAttributes.

uint32_t

0

<dynamic>

Whether the number of send buffers is allowed to grow.
See SendBuffersAllocationAttributes.

bool

false

Note

The default value 0 of <preallocated_number> will perform an initial guess of the number of buffers required, based on the number of threads from which a send operation could be started. So it does not mean there are no buffers, instead it would use the maximum amount of buffers available.