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

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

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

10.3.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
`<netmask_filter>`	Participant’s netmask filtering configuration. See the Netmask filtering section.	`NetmaskFilterKind`	`AUTO`
`<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
`<easy_mode_ip>`	IP address of the remote discovery server to connect to using Discovery Server Easy Mode.	`string`	Empty
`<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
`<builtinTransports>`	Configuration option to determine which transports will be instantiated if the `useBuiltinTransports` is set to true. See Managing the Builtin Transports.	BuiltinTransportType
`<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
`<builtin_controllers_sender_thread>`	ThreadSettings for the builtin flow controllers sender thread.	ThreadSettings
`<timed_events_thread>`	ThreadSettings participant’s timed events thread.	ThreadSettings
`<discovery_server_thread>`	ThreadSettings for the discovery server thread.	ThreadSettings
`<typelookup_service_thread>`	ThreadSettings for the threads used by the builtin TypeLookup service to discover unknown remote types. See Remote Data Types Discovery.	ThreadSettings
`<builtin_transports_reception_threads>`	ThreadSettings for the builtin transports reception threads.	ThreadSettings
`<security_log_thread>`	ThreadSettings for the security log thread.	ThreadSettings
`<flow_controller_descriptor_list>`	Defined flow controller descriptors to be used by the DomainParticipant. See Flow Controller Descriptors.	FlowControllersQos

Example

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

                <netmask_filter>ON</netmask_filter>

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

                <builtinTransports>DEFAULT</builtinTransports>

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

                <builtin_controllers_sender_thread>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </builtin_controllers_sender_thread>

                <timed_events_thread>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </timed_events_thread>

                <discovery_server_thread>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </discovery_server_thread>

                <typelookup_service_thread>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </typelookup_service_thread>

                <builtin_transports_reception_threads>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </builtin_transports_reception_threads>

                <security_log_thread>
                    <scheduling_policy>-1</scheduling_policy>
                    <priority>0</priority>
                    <affinity>0</affinity>
                    <stack_size>-1</stack_size>
                </security_log_thread>

                <flow_controller_descriptor_list>
                    <flow_controller_descriptor>
                        <name>example_flow_controller</name>
                        <scheduler>FIFO</scheduler>
                        <max_bytes_per_period>4096</max_bytes_per_period>
                        <period_ms>500</period_ms>
                        <sender_thread>
                            <scheduling_policy>-1</scheduling_policy>
                            <priority>0</priority>
                            <affinity>0</affinity>
                            <stack_size>-1</stack_size>
                        </sender_thread>
                    </flow_controller_descriptor>
                </flow_controller_descriptor_list>
            </rtps>
        </participant>
    </profiles>
</dds>

Note

LOCATOR_LIST means a LocatorListType is expected.
EXTERNAL_LOCATOR_LIST means a ExternalLocatorListType is expected.
For BUILTIN details, please refer to Builtin parameters.
PROPERTIES_POLICY means that the label is a PropertiesPolicyType block.
For ALLOCATION details, please refer to ParticipantAllocationType.

10.3.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
`<flow_controller_name>`	FlowControllersQos name.	`string`	Empty

Example

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

        <discoveryServersList>
            <locator>
                <udpv4>
                    <address>192.168.10.57</address>
                    <port>56542</port>
                </udpv4>
            </locator>
            <locator>
                <udpv4>
                    <address>192.168.10.58</address>
                    <port>24565</port>
                </udpv4>
            </locator>
        </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>

10.3.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 not set to `SIMPLE` or `NONE`, `<discoveryServersList>` element would be used.	`SIMPLE`	`SIMPLE`
		`CLIENT`
		`SERVER`
		`BACKUP`
		`SUPER_CLIENT`
		`NONE`
`<discoveryServersList>`	Describes locators of servers from which it receives only the discovery information they require to establish communication with matching endpoints. It expects a LocatorListType.	`<locator>`
`<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`
`<EDP>`		`STATIC`	`SIMPLE`
`<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. Pro adds a property for true send rate limiting (see Fine tuning the server send rate limiter ).	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>`

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

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

10.3.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
`<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>
        <network_buffers_config>
            <initial>16</initial>
            <maximum>0</maximum>
            <increment>16</increment>
        </network_buffers_config>
    </send_buffers>

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

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

10.3.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
`<network_buffers_config>`	Network buffer Allocation Configuration to specify the number of network buffers to be allocated for each send buffer. See ResourceLimitedContainerConfig.	Allocation Configuration	(16, inf, 16)

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. On the contrary, <network_buffers_config> will default to an initial number of 16 buffers, with an infinite maximum and an increment of 16 buffers per send buffer. An initial value of 0 will imply more dynamic allocations, especially at the beginning of the execution. In case of doubt, it should be left to the default values.