[21580] Improve mutation_tries documentation (backport #768)

code/DDSCodeTester.cpp

@@ -881,7 +881,7 @@ void dds_domain_examples()
             "true");
         //!--
 	}
-	
+
 	{
         // MAX_MESSAGE_SIZE_PROPERTY_PARTICIPANT
         DomainParticipantQos pqos;
@@ -4176,6 +4176,8 @@ void dds_qos_examples()
         WireProtocolConfigQos wire_protocol;
         //Set the guid prefix
         std::istringstream("72.61.73.70.66.61.72.6d.74.65.73.74") >> wire_protocol.prefix;
+        // Manually set the participantId
+        wire_protocol.participant_id = 11;
         //Configure Builtin Attributes
         wire_protocol.builtin.discovery_config.discoveryProtocol =
                 eprosima::fastrtps::rtps::DiscoveryProtocol_t::SERVER;
@@ -4208,6 +4210,8 @@ void dds_qos_examples()
         wire_protocol.default_external_unicast_locators[1][0].push_back(external_locator);
         // Drop non matching locators
         wire_protocol.ignore_non_matching_locators = true;
+        // Increase mutation tries
+        wire_protocol.builtin.mutation_tries = 300u;
         //!--
     }
 

code/XMLTester.xml

@@ -3347,6 +3347,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>
@@ -3365,6 +3366,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

@@ -1066,6 +1066,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
 """""""
 
@@ -1125,3 +1135,7 @@ XML
     :language: xml
     :start-after: <!-->XML_WRITER_RESOURCE_LIMITS_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