From c3c595b97b3ef9316e42ba2e693c34e19b9c3c05 Mon Sep 17 00:00:00 2001
From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com>
Date: Wed, 3 Jul 2024 11:57:24 +0200
Subject: [PATCH] Complete flow_controller_descriptor references in xml
 sections (#824) (#827)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Complete flow_controller_descriptor references in xml sections (#824)

* Refs #21231: Add missing <flow_controller_descriptor_list> to domainparticipant xml

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #21231: Add missing <flow_controller_name> to datawriter xml qos

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #21131: Apply Jesus rev

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

* Refs #21131: Apply Edu suggestion

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>

---------

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
(cherry picked from commit 6e7f076799dd943c9a535d6f682f5ff8f2f752de)
Signed-off-by: eduponz <eduardoponz@eprosima.com>

* Refs #21231: Fix XML snippet range

Signed-off-by: eduponz <eduardoponz@eprosima.com>

---------

Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
Signed-off-by: eduponz <eduardoponz@eprosima.com>
Co-authored-by: Mario Domínguez López <116071334+Mario-DL@users.noreply.github.com>
Co-authored-by: eduponz <eduardoponz@eprosima.com>
---
 code/XMLTester.xml                            | 15 ++++++
 code/XMLTesterExample.xml                     | 16 +++++++
 .../core/policy/eprosimaExtensions.rst        |  4 +-
 docs/fastdds/xml_configuration/common.rst     | 48 ++++++++++++++++---
 .../xml_configuration/domainparticipant.rst   |  7 ++-
 5 files changed, 80 insertions(+), 10 deletions(-)

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
index 3e3ddc898..556185a28 100644
--- a/code/XMLTester.xml
+++ b/code/XMLTester.xml
@@ -1504,6 +1504,21 @@
                     <affinity>0</affinity>
                     <stack_size>-1</stack_size>
                 </security_log_thread>
+
+                <flow_controller_descriptor_list>
+                    <flow_controller_descriptor>
+                        <name>example_flow_controller</name>
+                        <scheduler>FIFO</scheduler>
+                        <max_bytes_per_period>4096</max_bytes_per_period>
+                        <period_ms>500</period_ms>
+                        <sender_thread>
+                            <scheduling_policy>-1</scheduling_policy>
+                            <priority>0</priority>
+                            <affinity>0</affinity>
+                            <stack_size>-1</stack_size>
+                        </sender_thread>
+                    </flow_controller_descriptor>
+                </flow_controller_descriptor_list>
             </rtps>
         </participant>
 <!--
diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml
index 4e5f873c9..a281bc5be 100644
--- a/code/XMLTesterExample.xml
+++ b/code/XMLTesterExample.xml
@@ -490,6 +490,21 @@
                     <affinity>0</affinity>
                     <stack_size>-1</stack_size>
                 </security_log_thread>
+
+                <flow_controller_descriptor_list>
+                    <flow_controller_descriptor>
+                        <name>example_flow_controller</name>
+                        <scheduler>FIFO</scheduler>
+                        <max_bytes_per_period>4096</max_bytes_per_period>
+                        <period_ms>500</period_ms>
+                        <sender_thread>
+                            <scheduling_policy>-1</scheduling_policy>
+                            <priority>0</priority>
+                            <affinity>0</affinity>
+                            <stack_size>-1</stack_size>
+                        </sender_thread>
+                    </flow_controller_descriptor>
+                </flow_controller_descriptor_list>
             </rtps>
         </participant>
 
@@ -568,6 +583,7 @@
                 </partition>
                 <publishMode>
                     <kind>ASYNCHRONOUS</kind>
+                    <flow_controller_name>example_flow_controller</flow_controller_name>
                 </publishMode>
                 <reliability>
                     <kind>BEST_EFFORT</kind>
diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
index 2d3b2da4f..48df1ff12 100644
--- a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
+++ b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
@@ -243,7 +243,7 @@ It is a vector of shared pointers to |FlowControllerDescriptor-api|, which has t
      - Type
      - Default Value
    * - |FlowControllerDescriptor::name-api|
-     - ``const char *``
+     - ``string``
      -
    * - |FlowControllerDescriptor::scheduler-api|
      - |FlowControllerSchedulerPolicy-api|
@@ -529,7 +529,7 @@ List of QoS Policy data members:
      - :ref:`publishmodeqospolicykind`
      - |SYNCHRONOUS_PUBLISH_MODE-api|
    * - |PublishModeQosPolicy::flow_ctrl_name-api|
-     - ``const char *``
+     - ``string``
      - |FASTDDS_FLOW_CONTROLLER_DEFAULT-api|
 
 .. note::
diff --git a/docs/fastdds/xml_configuration/common.rst b/docs/fastdds/xml_configuration/common.rst
index f0ee16d93..526593702 100644
--- a/docs/fastdds/xml_configuration/common.rst
+++ b/docs/fastdds/xml_configuration/common.rst
@@ -718,13 +718,15 @@ Partition
 PublishMode
 """""""""""
 
-+-----------------------+---------------------------------------+------------------+------------------+
-| Name                  | Description                           | Values           | Default          |
-+=======================+=======================================+==================+==================+
-| ``<kind>``            | See :ref:`publishmodeqospolicy`.      | ``ASYNCHRONOUS`` | ``ASYNCHRONOUS`` |
-|                       |                                       +------------------+                  |
-|                       |                                       | ``SYNCHRONOUS``  |                  |
-+-----------------------+---------------------------------------+------------------+------------------+
++--------------------------+---------------------------------------+------------------+------------------+
+| Name                     | Description                           | Values           | Default          |
++==========================+=======================================+==================+==================+
+| ``<kind>``               | See :ref:`publishmodeqospolicy`.      | ``ASYNCHRONOUS`` | ``ASYNCHRONOUS`` |
+|                          |                                       +------------------+                  |
+|                          |                                       | ``SYNCHRONOUS``  |                  |
++--------------------------+---------------------------------------+------------------+------------------+
+|``<flow_controller_name>``| :ref:`flowcontrollersqos` name.       | ``<string>``     | Empty            |
++--------------------------+---------------------------------------+------------------+------------------+
 
 .. important::
 
@@ -846,3 +848,35 @@ and to :ref:`realtime-allocations` for detailed information on how to tune alloc
      - Number of new elements that will be allocated when more space is |br| necessary.
      - ``uint32_t``
      - 1
+
+.. _flowcontrollers_xml:
+
+Flow Controller Descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This ``<flow_controller_descriptor_list>`` element configures the list of flow controllers of a participant,
+so they can later be used on its DataWriters.
+Please refer to :ref:`flowcontrollersqos` for a detailed documentation.
+
+.. list-table::
+   :header-rows: 1
+   :align: left
+
+   * - Data Member Name
+     - Type
+     - Default Value
+   * - ``<name>``
+     - ``string``
+     - Empty
+   * - ``<scheduler>``
+     - |FlowControllerSchedulerPolicy-api|
+     - |FIFO_SCHED_POLICY-api|
+   * - ``<max_bytes_per_period>``
+     - ``int32_t``
+     - 0 (i.e. infinite)
+   * - ``<period_ms>``
+     - ``uint64_t``
+     - 100
+   * - ``<sender_thread>``
+     - :ref:`ThreadSettingsType`
+     -
diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst
index 1e2a74042..d9d661e3f 100644
--- a/docs/fastdds/xml_configuration/domainparticipant.rst
+++ b/docs/fastdds/xml_configuration/domainparticipant.rst
@@ -210,6 +210,11 @@ These elements allow the user to define the DomainParticipant configuration.
      - |ThreadSettings| for the security log thread.
      - |ThreadSettings|
      -
+   * - ``<flow_controller_descriptor_list>``
+     - Defined flow controller descriptors to be used by the |br|
+       DomainParticipant. See :ref:`flowcontrollers_xml`.
+     - |FlowControllersQos|
+     -
 
 **Example**
 
@@ -217,7 +222,7 @@ These elements allow the user to define the DomainParticipant configuration.
     :language: xml
     :start-after: <!-->XML-PARTICIPANT<-->
     :end-before: <!--><-->
-    :lines: 2-4, 6-128, 130-131
+    :lines: 2-4, 6-143, 145-146
 
 .. note::