Add XML configuration for FlowControllerDescriptor to 2.x (#804)

* Add XML configuration for FlowControllerDescriptor to 2.x (#793) * Refs #21136: Add XML Flow Controller Descriptors documentation Signed-off-by: Mario Dominguez <[email protected]> * Refs #21136: Apply rev Signed-off-by: Mario Dominguez <[email protected]> * Refs #21136: Fix XML repr. Signed-off-by: Mario Dominguez <[email protected]> --------- Signed-off-by: Mario Dominguez <[email protected]> (cherry picked from commit f3f4f0e) # Conflicts: # code/XMLTester.xml # docs/fastdds/use_cases/large_data/large_data.rst * Refs #21244: Solve conflicts and remove thread settings Signed-off-by: Mario Dominguez <[email protected]> * Refs #21244: Complete flow controller descirptor Signed-off-by: Mario Dominguez <[email protected]> * Refs #21244: Nit Signed-off-by: Mario Dominguez <[email protected]> --------- Signed-off-by: Mario Dominguez <[email protected]> Co-authored-by: Mario Domínguez López <[email protected]> Co-authored-by: Mario Dominguez <[email protected]>
eProsima · Jun 27, 2024 · c94b258 · c94b258
1 parent 04a895c
commit c94b258
Show file tree

Hide file tree

Showing 7 changed files with 177 additions and 88 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -3921,6 +3921,8 @@ void dds_qos_examples()
         //The PublishModeQosPolicy is default constructed with kind = SYNCHRONOUS
         //Change the kind to ASYNCHRONOUS
         publish_mode.kind = ASYNCHRONOUS_PUBLISH_MODE;
+        // Optionally, select the flow controller name
+        publish_mode.flow_controller_name = "example_flow_controller";
         //!--
     }
 

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -800,13 +800,26 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
 -->
+    <participant profile_name="participant_profile_qos_flowcontroller">
+        <rtps>
+            <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>
+                </flow_controller_descriptor>
+            </flow_controller_descriptor_list>
+        </rtps>
+    </participant>
+
     <data_writer profile_name="writer_profile_qos_flowcontroller">
-        <!-- NOTE: This tag has been deprecated but doesn't have an
-             equivalent XML tag yet -->
-        <throughputController>
-            <bytesPerPeriod>300000</bytesPerPeriod>
-            <periodMillisecs>1000</periodMillisecs>
-        </throughputController>
+        <qos>
+            <publishMode>
+                <kind>ASYNCHRONOUS</kind>
+                <flow_controller_name>example_flow_controller</flow_controller_name>
+            </publishMode>
+        </qos>
     </data_writer>
 <!--><-->
 
@@ -815,6 +828,7 @@
     <qos>
         <publishMode>
             <kind>ASYNCHRONOUS</kind>
+            <flow_controller_name>example_flow_controller</flow_controller_name>
         </publishMode>
     </qos>
 </data_writer>
@@ -1600,6 +1614,15 @@
             <userData>
                 <value>13.40.37.00.CE</value>
             </userData>
+
+            <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>
+                </flow_controller_descriptor>
+            </flow_controller_descriptor_list>
         </rtps>
     </participant>
 <!--

diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml
@@ -277,6 +277,14 @@
                         </property>
                     </properties>
                 </propertiesPolicy>
+                <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>
+                    </flow_controller_descriptor>
+                </flow_controller_descriptor_list>
             </rtps>
         </participant>
 
@@ -333,6 +341,7 @@
                 </partition>
                 <publishMode>
                     <kind>ASYNCHRONOUS</kind>
+                    <flow_controller_name>example_flow_controller</flow_controller_name>
                 </publishMode>
                 <disablePositiveAcks>
                     <enabled>true</enabled>

diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
@@ -512,6 +512,9 @@ There are two possible values (see |PublishModeQosPolicyKind-api|):
 * |ASYNCHRONOUS_PUBLISH_MODE-api|: An internal thread takes the responsibility of sending the data asynchronously.
   The write operation returns before the data is actually sent.
 
+Also, the |PublishModeQosPolicy::flow_ctrl_name-api| has to be set to the name of a valid :ref:`flow-controllers`
+descriptor name.
+
 Example
 """""""
 

diff --git a/docs/fastdds/use_cases/large_data/large_data.rst b/docs/fastdds/use_cases/large_data/large_data.rst
@@ -246,22 +246,24 @@ They only differ in the way they decide the order in which the samples are sent.
 Example configuration
 ^^^^^^^^^^^^^^^^^^^^^
 
-+------------------------------------------------+
-| **C++**                                        |
-+------------------------------------------------+
-| .. literalinclude:: /../code/DDSCodeTester.cpp |
-|    :language: c++                              |
-|    :start-after: //CONF-QOS-FLOWCONTROLLER     |
-|    :end-before: //!--                          |
-|    :dedent: 8                                  |
-+------------------------------------------------+
-| **XML**                                        |
-+------------------------------------------------+
-| There is currently no way of configuring flow  |
-| controllers with XML.                          |
-| This will be added in future releases of the   |
-| product                                        |
-+------------------------------------------------+
+.. tabs::
+
+   .. tab:: C++
+
+      .. literalinclude:: /../code/DDSCodeTester.cpp
+         :language: c++
+         :start-after: //CONF-QOS-FLOWCONTROLLER
+         :end-before: //!--
+         :dedent: 8
+
+   .. tab:: XML
+
+      .. literalinclude:: /../code/XMLTester.xml
+         :language: xml
+         :start-after: <!-->CONF-QOS-FLOWCONTROLLER
+         :end-before: <!--><-->
+         :lines: 2-3, 5-
+         :append: </profiles>
 
 .. Warning::
 

diff --git a/docs/fastdds/xml_configuration/common.rst b/docs/fastdds/xml_configuration/common.rst
@@ -330,6 +330,22 @@ Partition
 |                           |                                                                             |            |
 +---------------------------+-----------------------------------------------------------------------------+------------+
 
+
+.. _xml_publishmode:
+
+PublishMode
+"""""""""""
+
++--------------------------+---------------------------------------+------------------+------------------+
+| Name                     | Description                           | Values           | Default          |
++==========================+=======================================+==================+==================+
+| ``<kind>``               | See :ref:`publishmodeqospolicy`.      | ``ASYNCHRONOUS`` | ``ASYNCHRONOUS`` |
+|                          |                                       +------------------+                  |
+|                          |                                       | ``SYNCHRONOUS``  |                  |
++--------------------------+---------------------------------------+------------------+------------------+
+|``<flow_controller_name>``| :ref:`flowcontrollersqos` name.       | ``<string>``     | Empty            |
++--------------------------+---------------------------------------+------------------+------------------+
+
 .. _xml_deadline:
 
 Deadline
@@ -482,3 +498,33 @@ 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
+