Skip to content

Latest commit

 

History

History
705 lines (614 loc) · 30.5 KB

domainparticipant.rst

File metadata and controls

705 lines (614 loc) · 30.5 KB
Raw

DomainParticipant profiles

The profiles allow the definition of the configuration of 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, so that it can be loaded later by the , as shown in loadingapplyingprofiles. 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

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 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 dds_layer_domainParticipant_creation_profile. uint32_t 0
<rtps> Fast DDS DomainParticipant configurations. See RTPS.

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 for user data traffic (see <metatrafficUnicastLocatorList> defined in builtin). It expects a LocatorListType. <locator>
<defaultMulticastLocatorList> List of default reception multicast locators for user data traffic (see <metatrafficMulticastLocatorList> defined in builtin). 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.
<builtin> public data member of the class. See the builtin section. builtin
<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 . int32_t 0
<userTransports> Transport descriptors to be used by the DomainParticipant. See transportdescriptors. List <string>
<useBuiltinTransports> Boolean field to indicate the system whether the DomainParticipant will use the default 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 rtps_layer_builtin_transports. BuiltinTransportType <BuiltinTransportType>
<propertiesPolicy> Additional configuration properties. See propertypolicyqos. PropertiesPolicyType <PropertiesPolicyType>
<allocation> Configuration regarding allocation behavior. It expects a DomainParticipantAllocationType <ParticipantAllocationType>. DomainParticipantAllocationType <ParticipantAllocationType>
<userData> Additional information attached to the DomainParticipant and transmitted with the discovery information. See userdataqospolicy. List <string> Empty
<prefix> 's identifies peers running in the same process. Two participants with identical 8 first bytes on the are considered to be running in the same process, and therefore intra-process delivery is used. See intraprocess-delivery. string Empty
<builtin_controllers_sender_thread> for the builtin flow controllers sender thread.
<timed_events_thread> participant's timed events thread.
<discovery_server_thread> for the discovery server thread.
<builtin_transports_reception_threads> for the builtin transports reception threads.
<security_log_thread> for the security log thread.

Example

/../code/XMLTester.xml

Note

  • LOCATOR_LIST means a LocatorListType is expected.
  • EXTERNAL_LOCATOR_LIST means a externalLocatorListType is expected.
  • For BUILTIN details, please refer to builtin.
  • PROPERTIES_POLICY means that the label is a PropertiesPolicyType block.
  • For ALLOCATION details, please refer to ParticipantAllocationType.

Builtin parameters

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

Name Description Values Default
<discovery_config> This is the main element within which discovery-related settings can be configured. See discovery. dconf
<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 with which a will communicate. See Simple 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. historymemorypoliciesXML
<writerHistoryMemoryPolicy> Memory policy for DataWriters. See historyqospolicykind. historymemorypoliciesXML
<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
typelookup_config TypeLookup Service settings. See typelookup-service. typelookup_config

Example

/../code/XMLTester.xml

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 disc_mechanisms. If set to , <discoveryServersList> + element would be used. +
---------------------+
---------------------+
---------------------+
---------------------+
<discoveryServersList> Describes servers from which it receives only the discovery information they require to establish communication with matching endpoints. See discovery_server discserverlst
<ignoreParticipantFlags> Restricts metatraffic using several filtering criteria. See discovery_ignore_flags. partfiltering
<EDP> If set to , <simpleEDP> element would be used. + If set to STATIC, will be performed, configured with the contents of the XML file set in <static_edp_xml_config>. See discovery.
---------------------+

STATIC
<simpleEDP> Attributes of the Simple Discovery Protocol. See Simple EDP Attributes. sedp
<leaseDuration> Indicates how long the DomainParticipant should consider remote DomainParticipants alive. See discovery_lease_dur. 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 discovery_lease_announ. DurationType 3s
<initialAnnouncements> Allows the user to configure the number and period of the DomainParticipant's initial discovery messages. See Initial Announcements. InitAnnounce
<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 discovery_static. List <string>
discoveryServersList

Contains a list of <RemoteServer> (server) elements, which are defined by the and their own locator list which must be populated with . 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

/../code/XMLTester.xml

ignoreParticipantFlags
Possible values Description
All Discovery traffic is processed.
Discovery traffic from another host is discarded.
Discovery traffic from another process on the same host is discarded.
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
TypeLookup Service Configuration
Name Description Values Default
use_client Create TypeLookup Service client builtin endpoints. bool false
use_server Create TypeLookup Service server builtin endpoints. bool false

Port Configuration

According to the RTPS standard (Section 9.6.1.1), the ' 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 . 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 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 CommonAlloc to specify the total number of DomainParticipants in the domain (local and remote). See ResourceLimitedContainerConfig. CommonAlloc
<total_readers> DomainParticipant CommonAlloc to specify the total number of DataReader on each DomainParticipant (local and remote). See ResourceLimitedContainerConfig. CommonAlloc
<total_writers> DomainParticipant CommonAlloc related to the total number of DataWriters on each DomainParticipant (local and remote). See resourcelimitedcontainerconfig. CommonAlloc
<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. SendBuffers

Example

/../code/XMLTester.xml

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

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.