Improve mutation_tries documentation (#768)

* Refs #20934: Improve documentation Signed-off-by: JesusPoderoso <[email protected]> * Refs #20934: Apply internal rev suggestions Signed-off-by: JesusPoderoso <[email protected]> * Refs #20934: Update namespaces Signed-off-by: JesusPoderoso <[email protected]> * Refs #21580: Apply rev suggestions Signed-off-by: JesusPoderoso <[email protected]> * Refs #21580: Apply rev suggestions (2) Signed-off-by: JesusPoderoso <[email protected]> --------- Signed-off-by: JesusPoderoso <[email protected]>
eProsima · Sep 6, 2024 · 26b6700 · 26b6700
1 parent f88b356
commit 26b6700
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 1 deletion.
diff --git a/code/DDSCodeTester.cpp b/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);
         //!--

diff --git a/code/XMLTester.xml b/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>

diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/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.
+
diff --git a/docs/fastdds/transport/listening_locators.rst b/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