Skip to content

Latest commit

 

History

History
651 lines (564 loc) · 29 KB

domainparticipant.rst

File metadata and controls

651 lines (564 loc) · 29 KB
Raw

DomainParticipant profiles

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

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, |br| so that it can be loaded later by the |DomainParticipantFactory-api|, as shown in |br| :ref:`loadingapplyingprofiles`. Mandatory
is_default_profile Sets the <participant> profile as the default profile. Thus, if a default profile |br| exists, it will be used when no other DomainParticipant profile is specified at the |br| DomainParticipant's creation. Optional

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-api| 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 :ref:`dds_layer_domainParticipant_creation_profile`. uint32_t 0
<rtps> Fast DDS DomainParticipant configurations. |br| See :ref:`RTPS`. :ref:`RTPS`  

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 |br| for user data traffic (see |br| <metatrafficUnicastLocatorList> |br| defined in :ref:`builtin`). |br| It expects a :ref:`LocatorListType`. <locator>  
<defaultMulticastLocatorList> List of default reception multicast |br| locators for user data traffic (see |br| <metatrafficMulticastLocatorList> |br| defined in :ref:`builtin`). |br| It expects a :ref:`LocatorListType`. <locator>  
<default_external_unicast_locators> List of :ref:`external_locators` |br| to announce for the default user traffic of |br| this participant. :ref:`externalLocatorListType`  
<ignore_non_matching_locators> Whether to ignore locators received on |br| announcements from other participants when |br| they don't match with any of the locators |br| announced by this participant. bool false
<sendSocketBufferSize> Size in bytes of the send socket buffer. |br| If the value is zero then Fast DDS will |br| use the system default socket size. uint32_t 0
<listenSocketBufferSize> Size in bytes of the reception socket |br| buffer. If the value is zero then |br| Fast DDS will use the system default |br| socket size. uint32_t 0
<builtin> |WireProtocolConfigQos::builtin-api| public data member of the |br| |WireProtocolConfigQos-api| class. |br| See the :ref:`builtin` section. :ref:`builtin`  
<port> Allows defining the port and gains related |br| to the RTPS protocol. See the Port section. Port  
<participantID> DomainParticipant's identifier. Typically |br| it will be automatically generated by the |br| |DomainParticipantFactory|. int32_t 0
<userTransports> Transport descriptors to be used by the |br| DomainParticipant. See |br| :ref:`transportdescriptors`. List <string>  
<useBuiltinTransports> Boolean field to indicate the system |br| whether the DomainParticipant will use the |br| default |WireProtocolConfigQos::builtin-api| transports |br| in addition to its <userTransports>. bool true
<builtinTransports> Configuration option to determine which transports |br| will be instantiated if the useBuiltinTransports is |br| set to true. See :ref:`rtps_layer_builtin_transports`. string_255 DEFAULT
<propertiesPolicy> Additional configuration properties. |br| See :ref:`propertypolicyqos`. |PolicyType|  
<allocation> Configuration regarding allocation behavior. |br| It expects a |br| |PartAlloc|. |PartAlloc|  
<userData> Additional information attached to the DomainParticipant |br| and transmitted with the discovery information. |br| See :ref:`userdataqospolicy`. List <string> Empty
<prefix> |DomainParticipant|'s |GuidPrefix_t-api| identifies peers |br| running in the same process. Two participants with identical |br| 8 first bytes on the |GuidPrefix_t-api| are considered to be |br| running in the same process, and therefore intra-process |br| delivery is used. See :ref:`intraprocess-delivery`. string Empty

Example

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PARTICIPANT<-->
    :end-before: <!--><-->
    :lines: 2-3, 5-88, 90

Builtin parameters

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

Name Description Values Default
<discovery_config> This is the main element within |br| which discovery-related |br| settings can be configured. |br| See :ref:`discovery`. :ref:`dconf`  
<avoid_builtin_multicast> Restricts multicast metatraffic |br| to PDP only. bool :class:`true`
<use_WriterLivelinessProtocol> Indicates whether to use the |br| DataWriterLiveliness protocol. bool :class:`true`
<metatrafficUnicastLocatorList> Metatraffic Unicast Locator List. A set of <locator> |br| members. |br| See :ref:`LocatorListType`  
<metatrafficMulticastLocatorList> Metatraffic Multicast Locator List. A set of <locator> |br| members. |br| See :ref:`LocatorListType`  
<initialPeersList> The list of IP-port address |br| pairs of all other |br| |DomainParticipants| with which |br| a |DomainParticipant| will |br| communicate. See |br| :ref:`Simple Initial Peers` A set of <locator> |br| members. |br| See :ref:`LocatorListType`  
<metatraffic_external_unicast_locators> List of :ref:`external_locators` |br| to announce for the metatraffic of |br| this participant. :ref:`externalLocatorListType`  
<readerHistoryMemoryPolicy> Memory policy for DataReaders. |br| See :ref:`historyqospolicykind`. :ref:`historymemorypoliciesXML` |PREALLOCATED-xml-api|
<writerHistoryMemoryPolicy> Memory policy for DataWriters. |br| See :ref:`historyqospolicykind`. :ref:`historymemorypoliciesXML` |PREALLOCATED-xml-api|
<readerPayloadSize> Maximum DataReader's History |br| payload size. Allows to reserve |br| all the required memory at |br| DataReader initialization. |br| See :ref:`memorymanagementpolicy`. uint32_t 512
<writerPayloadSize> Maximum DataWriter's History |br| payload size. Allows to reserve |br| all the required memory at |br| DataWriter initialization. |br| See :ref:`memorymanagementpolicy`. uint32_t 512
<mutation_tries> Number of different ports |br| to try if DataReader's physical |br| port is already in use. uint32_t 100

Example

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-BUILTIN<-->
    :end-before: <!--><-->

discovery_config

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

Name Description Values Default
<discoveryProtocol> Indicates which discovery protocol |br| the DomainParticipant will use. |br| See :ref:`disc_mechanisms`. If set to |br| |CLIENT|, <discoveryServersList> |br| element would be used. |SIMPLE| |SIMPLE|
|CLIENT|
|SERVER|
|BACKUP|
|NONE|
<discoveryServersList> Describes servers from which it receives |br| only the discovery information they |br| require to establish communication with |br| matching endpoints. |br| See :ref:`discovery_server` :ref:`discserverlst`  
<ignoreParticipantFlags> Restricts metatraffic using several |br| filtering criteria. See :ref:`discovery_ignore_flags`. :ref:`partfiltering` |NO_FILTER|
<EDP> If set to |SIMPLE|, <simpleEDP> |br| element would be used. |br| If set to STATIC, |EDPStatic| will be |br| performed, configured with the contents |br| of the XML file set in <static_edp_xml_config>. |br| See :ref:`discovery`. |SIMPLE| |SIMPLE|
STATIC
<simpleEDP> Attributes of the Simple Discovery |br| Protocol. See :ref:`Simple EDP Attributes`. :ref:`sedp`  
<leaseDuration> Indicates how long the DomainParticipant |br| should consider remote DomainParticipants |br| alive. See :ref:`discovery_lease_dur`. :ref:`DurationType` 20s
<leaseAnnouncement> The period for the DomainParticipant to |br| send its discovery message to all other |br| discovered DomainParticipants as well as |br| to all Multicast ports. See :ref:`discovery_lease_announ`. :ref:`DurationType` 3s
<initialAnnouncements> Allows the user to configure the number |br| and period of the DomainParticipant's initial |br| discovery messages. See :ref:`Initial Announcements`. :ref:`InitAnnounce`  
<clientAnnouncementPeriod> The period for the DomainParticipant to |br| send its Discovery Message to its servers |br| and check for EDP endpoints matching. :ref:`DurationType` 450 ms
<static_edp_xml_config> The XML filename(s) with the static EDP |br| configuration. Only necessary if |br| the <EDP> member is set to |br| STATIC. See :ref:`discovery_static`. List <string>  
discoveryServersList

Contains a list of <RemoteServer> (server) elements, which are defined by the |GuidPrefix_t-api| and their own locator list which must be populated with |RemoteServerAttributes-api|. 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. |br| This identifier allows clients to assess whether they are |br| 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. |br| See :ref:`LocatorListType`
<metatrafficMulticastLocatorList> Metatraffic Multicast Locator List. A set of <locator> members. |br| See :ref:`LocatorListType`

Example

.. literalinclude:: /../code/XMLTester.xml
   :language: xml
   :start-after: <!-->CONF_DS_MAIN_SCENARIO_CLIENT<-->
   :end-before: <!--><-->
   :lines: 2-3,5-
   :append: </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 |br| Publication DataWriter and Subscription DataReader. bool true
<PUBREADER_SUBWRITER> Indicates if the participant must use |br| 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 |br| <period>. After these announcements, the DomainParticipant will continue |br| sending its discovery messages at the <leaseAnnouncement> rate. uint32_t 5
<period> The period for the DomainParticipant to send its discovery messages. :ref:`DurationType` 100 ms

Port Configuration

According to the RTPS standard (Section 9.6.1.1), the |RTPSParticipants-api|' 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 |WireProtocolConfigQos::participant_id-api|. 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.

ParticipantAllocationType

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

Name Description Values Default
<remote_locators> Defines the limits for the remote locators' collections. |br| See :ref:`remotelocatorsallocationattributes`. :ref:`remote_locators_allocations`  
<total_participants> DomainParticipant :ref:`CommonAlloc` to specify the |br| total number of DomainParticipants in the domain |br| (local and remote). See |br| :ref:`ResourceLimitedContainerConfig`. :ref:`CommonAlloc`  
<total_readers> DomainParticipant :ref:`CommonAlloc` to specify the |br| total number of DataReader on each DomainParticipant |br| (local and remote). See |br| :ref:`ResourceLimitedContainerConfig`. :ref:`CommonAlloc`  
<total_writers> DomainParticipant :ref:`CommonAlloc` related to the |br| total number of DataWriters on each DomainParticipant |br| (local and remote). See :ref:`resourcelimitedcontainerconfig`. :ref:`CommonAlloc`  
<max_partitions> Maximum size of the partitions submessage. |br| Set to zero for no limit. uint32_t  
<max_user_data> Maximum size of the user data submessage. |br| Set to zero for no limit. uint32_t  
<max_properties> Maximum size of the properties submessage. |br| Set to zero for no limit. uint32_t  
<send_buffers> Allocation behaviour for the send buffer |br| manager. :ref:`SendBuffers`  

Example

.. literalinclude:: /../code/XMLTester.xml
    :language: xml
    :start-after: <!-->XML-PARTICIPANT-ALLOCATION<-->
    :end-before: <!--><-->

Remote Locators Allocations

Name Description Values Default
<max_unicast_locators> Maximum number of unicast locators expected on a |br| remote entity. It is recommended to use the maximum |br| number of network interfaces available on the machine |br| on which DomainParticipant is running. |br| See :ref:`remotelocatorsallocationattributes`. uint32_t 4
<max_multicast_locators> Maximum number of multicast locators expected on a |br| remote entity. May be set to zero to disable multicast |br| traffic. See :ref:`remotelocatorsallocationattributes`. uint32_t 1

Send buffers

Name Description Values Default
<preallocated_number> Initial number of send buffers to allocate. See |br| :ref:`sendbuffersallocationattributes`. uint32_t 0
<dynamic> Whether the number of send buffers is allowed to grow. |br| See :ref:`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.