[21580] Improve mutation_tries documentation

code/DDSCodeTester.cpp

@@ -4653,7 +4653,9 @@ void dds_qos_examples()
         DomainParticipantQos participant_qos;
         // Set the guid prefix
         std::istringstream("72.61.73.70.66.61.72.6d.74.65.73.74") >> participant_qos.wire_protocol().prefix;
-        //Configure Builtin Attributes
+        // Manually set the participantId
+        participant_qos.wire_protocol().participant_id = 11;
+        // Configure Builtin Attributes
         participant_qos.wire_protocol().builtin.discovery_config.discoveryProtocol =
                 eprosima::fastdds::rtps::DiscoveryProtocol::SERVER;
         // Add locator to unicast list
@@ -4686,6 +4688,8 @@ void dds_qos_examples()
         participant_qos.wire_protocol().default_external_unicast_locators[1][0].push_back(external_locator);
         // Drop non matching locators
         participant_qos.wire_protocol().ignore_non_matching_locators = true;
+        // Increase mutation tries
+        participant_qos.wire_protocol().builtin.mutation_tries = 300u;
         // Use modified QoS in the creation of the DomainParticipant entity
         participant_ = factory_->create_participant(domain, participant_qos);
         //!--

code/XMLTester.xml

@@ -3793,6 +3793,7 @@
 <participant profile_name="UDP SERVER WP" is_default_profile="true">
     <rtps>
         <prefix>72.61.73.70.66.61.72.6d.74.65.73.74</prefix>
+        <participantID>11</participantID>
         <builtin>
             <discovery_config>
                 <discoveryProtocol>SERVER</discoveryProtocol>
@@ -3811,6 +3812,7 @@
                     <port>34567</port>
                 </udpv4>
             </metatraffic_external_unicast_locators>
+            <mutation_tries>300</mutation_tries>
         </builtin>
         <defaultUnicastLocatorList>
             <locator>

docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst

@@ -1243,6 +1243,16 @@ List of QoS Policy data members:
      |BuiltinAttributes::discovery_config-api| within |WireProtocolConfigQos::builtin-api| (see
      :ref:`DS_modify_server_list`).
 
+.. note::
+     Deployments where multiple DomainParticipants are created within the same host can lead into denying
+     available ports for them if the amount of DomainParticipants created reaches the value of
+     :cpp:var:`BuiltinAttributes::mutation_tries<eprosima::fastdds::rtps::BuiltinAttributes::mutation_tries>`
+     (100 by default).
+     When that happens, the DomainParticipants will not be able to create the listening ports (this is notified
+     with a log warning) and will be created without unicast locators configured.
+
+.. _wireprotocolconfigqos_example:
+
 Example
 """""""
 
@@ -1263,3 +1273,6 @@ Example
           :start-after: <!-->XML_WIRE_PROTOCOL_CONFIG_QOS<-->
           :end-before: <!--><-->
 
+.. note::
+    For extended XML information, refer to :ref:`domainparticipantconfig` and :ref:`builtin` XML sections.
+

docs/fastdds/transport/listening_locators.rst

@@ -177,6 +177,10 @@ further configuring the :ref:`comm-transports-configuration`.
    (neither *unicast* nor *multicast*), *Fast DDS* enables one *unicast* Locator
    that will be used for peer-to-peer communication of :ref:`dds_layer_topic_topic` data.
 
+ * If the application does not define any **participantId**, *Fast DDS* will use the value given by the
+   :ref:`dds_layer_domainParticipantFactory`, which will try always to provide the lowest available value per
+   DomainParticipantFactory (per process).
+
 For example, it is possible to prevent *multicast* traffic adding a single *metatraffic unicast* Locator
 as described in :ref:`transport_disableMulticast`.
 
@@ -212,6 +216,17 @@ The values used in these rules are explained on the following table.
 The default values can be modified using the |WireProtocolConfigQos::port-api| member of the
 :ref:`wireprotocolconfigqos` on the :ref:`dds_layer_domainParticipantQos`.
 
+.. note::
+
+     Deployments where multiple DomainParticipants are created within the same host can lead into denying
+     available ports for them if the amount of DomainParticipants created reaches the value of
+     :cpp:var:`BuiltinAttributes::mutation_tries<eprosima::fastdds::rtps::BuiltinAttributes::mutation_tries>`
+     (100 by default).
+     When that happens, the DomainParticipants will not be able to create the listening ports (this is notified
+     with a log warning) and will be created without unicast locators configured.
+
+    Refer to :ref:`this example <wireprotocolconfigqos_example>` for configuring both the *mutation_tries* values.
+
 .. list-table:: Values used in the rules to calculate well-known ports
    :header-rows: 1