Extend LARGE_DATA configuration options (#696)

* Refs #20493: Update XML examples Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Add new XML type Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update API code example Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update Env.var. section with options Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: New TCP use case with LARGE_DATA options Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Fix XML files Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Add troubleshooting and SHM segment size info Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update RTPS recommendation Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update snippets with tcp_negotiation_timeout Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update env_var with tcp_negotiation_timeout Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update xml with tcp_negotiation_timeout Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update use_case with tcp_negotiation_timeout Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Update docs with new XML schema Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Apply suggestions Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Refs #20493: Apply suggestions Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> --------- Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>
eProsima · Mar 7, 2024 · 48d5770 · 48d5770
1 parent 195733c
commit 48d5770
Show file tree

Hide file tree

Showing 11 changed files with 262 additions and 7 deletions.
diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -6152,6 +6152,26 @@ void tcp_use_cases()
         //!
     }
 
+    {
+        //LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS
+        eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;
+
+        /* Transports configuration */
+        // UDPv4 transport for PDP over multicast and SHM / TCPv4 transport for EDP and application data
+        // Message Size and Sockets sizes of 200 KB + Non-blocking send + 50ms negotiation timeout
+        eprosima::fastdds::rtps::BuiltinTransportsOptions large_data_options;
+        large_data_options.maxMessageSize = 200000;
+        large_data_options.sockets_buffer_size = 200000;
+        large_data_options.non_blocking_send = true;
+        large_data_options.tcp_negotiation_timeout = 50;
+        pqos.setup_transports(eprosima::fastdds::rtps::BuiltinTransports::LARGE_DATA, large_data_options);
+
+        /* Create participant as usual */
+        eprosima::fastdds::dds::DomainParticipant* participant =
+                eprosima::fastdds::dds::DomainParticipantFactory::get_instance()->create_participant(0, pqos);
+        //!
+    }
+
     {
         //PDP-MULTICAST-DATA-TCP
         eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -3905,6 +3905,23 @@
 -->
 <!--><-->
 
+<!-->LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS<-->
+<!--
+<?xml version="1.0" encoding="UTF-8" ?>
+<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
+    <profiles>
+-->
+        <participant profile_name="large_data_builtin_transports_options" is_default_profile="true">
+            <rtps>
+                <builtinTransports max_msg_size="200KB" sockets_size="200KB" non_blocking="true" tcp_negotiation_timeout="50">LARGE_DATA</builtinTransports>
+            </rtps>
+        </participant>
+<!--
+    </profiles>
+</dds>
+-->
+<!--><-->
+
 <!-->PDP-MULTICAST-DATA-TCP<-->
 <!--
 <?xml version="1.0" encoding="UTF-8" ?>

diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml
@@ -399,7 +399,7 @@
 
                 <useBuiltinTransports>false</useBuiltinTransports>
 
-                <builtinTransports>DEFAULT</builtinTransports>
+                <builtinTransports max_msg_size="50KB" sockets_size="50KB" non_blocking="false">DEFAULT</builtinTransports>
 
                 <propertiesPolicy>
                     <properties>

diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst
@@ -108,6 +108,72 @@ All existing values, along with a brief description, are shown below:
      * |TCPTransportDescriptor::keep_alive_thread-api| and
        |TCPTransportDescriptor::accept_thread-api| use the default configuration.
 
+.. _env_vars_large_data_options:
+
+Configuring builtin transports options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fast DDS offers a straightforward method to configure three main parameters of every builtin transport via the
+environment variable.
+However, this feature proves particularly valuable when employing the ``LARGE_DATA`` builtin
+transports option.
+The ``LARGE_DATA`` mode has been designed to improve performance when working with large data.
+However, according to each specific use case, the user might want to configure several options to better fit their
+needs.
+This mode can also be configured with the ``tcp_negotiation_timeout`` parameter:
+
++----------------------------+--------------------------------------------------------------------+-------------------+
+| Builtin Transports Options | Description                                                        | Type              |
++============================+====================================================================+===================+
+| ``max_msg_size``           | It determines the maximum message size that will be specified |br| | uint32_t          |
+|                            | in the transport layer. Selecting a message size large |br|        |                   |
+|                            | enough to accommodate the largest data message will |br|           |                   |
+|                            | prevent fragmentation, which can significantly enhance |br|        |                   |
+|                            | the overall sending rate.                                          |                   |
++----------------------------+--------------------------------------------------------------------+-------------------+
+| ``sockets_size``           | It determines the size of the send and receive socket buffers. |br|| uint32_t          |
+|                            | This parameter needs to be higher or equal to the maximum |br|     |                   |
+|                            | message size specified in order to be valid.                       |                   |
++----------------------------+--------------------------------------------------------------------+-------------------+
+| ``non_blocking``           | It determines whether to use non-blocking send calls or not. |br|  | bool              |
+|                            | When activated, the transport will discard messages if the |br|    |                   |
+|                            | socket buffers are full.                                           |                   |
++----------------------------+--------------------------------------------------------------------+-------------------+
+| ``tcp_negotiation_timeout``| It determines the time to wait for logical port negotiation. |br|  | uint32_t          |
+|                            | Only valid if the ``LARGE_DATA`` mode is being used. |br|          |                   |
+|                            | It only accepts milliseconds.                                      |                   |
++----------------------------+--------------------------------------------------------------------+-------------------+
+
+The environment variable accepts several types of units to specify the values of the parameters.
+Also, both lowercase and uppercase letters are valid.
+The following list shows the available units and their corresponding symbols:
+
++ ``B``: Bytes. This is the default unit, so it is not necessary to specify it.
++ ``KB``: Kilobytes.
++ ``MB``: Megabytes.
++ ``GB``: Gigabytes.
++ ``KIB``: Kibibyte.
++ ``MIB``: Mebibyte.
++ ``GIB``: Gibibyte.
+
+.. code-block:: bash
+
+    export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=200KB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50
+
+.. note::
+    When working with ``LARGE_DATA``, it is recommended to set the ``max_msg_size`` and ``sockets_size`` to a value
+    large enough to accommodate the largest data message and to set the ``non_blocking`` to ``TRUE``.
+    Note that activating the ``non_blocking`` option with a small message size (with fragmentation)
+    can lead to an increase of messages drop rate and produce undesired results.
+    For more information, please refer to :ref:`use-case-large-data-options`.
+
+.. warning::
+    Setting a ``max_msg_size`` higher than 65500 KB is only possible when using the ``LARGE_DATA`` builtin transports
+    option.
+    Trying to set it with any other builtin transports will result in an error and the creation of the participant
+    will fail.
+
+
 .. _env_vars_ros_discovery_server:
 
 ``ROS_DISCOVERY_SERVER``

diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst
@@ -190,9 +190,9 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R
 
 .. warning::
 
-  To obtain a better performance when working with large data messages it is extremely recommended to set through
-  :ref:`dds_layer_domainParticipantQos` the send and receive buffer sizes of the TCP transport to the maximum default
-  system value. See :ref:`finding-out-maximum-socket-values` to learn how to check it.
+  To obtain a better performance when working with large data messages it is extremely recommended to use the
+  builtin transports configuration options to adjust the transport to the specific needs of the application.
+  Please refer to :ref:`use-case-large-data-options` for more information about how to configure it.
 
 Configuring Readers and Writers
 -------------------------------

diff --git a/docs/fastdds/troubleshooting/troubleshooting.rst b/docs/fastdds/troubleshooting/troubleshooting.rst
@@ -38,5 +38,9 @@ issues.
         :start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
         :end-before: //!
 
-* Problems with transmitting **large samples such as video or point clouds**? Please refer to
+* If having problems with transmitting **large samples** when using the ``LARGE_DATA`` mode, try to use the builtin
+  transports configuration options to adjust ``LARGE_DATA`` to your specific use case.
+  Please refer to :ref:`use-case-large-data-options` for more information.
+
+* If having problems with transmitting **large samples such as video or point clouds**, please refer to
   :ref:`use-case-largeData`.
diff --git a/docs/fastdds/use_cases/tcp/tcp_large_data_with_options.rst b/docs/fastdds/use_cases/tcp/tcp_large_data_with_options.rst
@@ -0,0 +1,84 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+
+.. _use-case-large-data-options:
+
+Large Data with configuration options
+=====================================
+
+As it has been observed in :ref:`use-case-tcp-multicast`, ``LARGE_DATA`` builtin transports option offers an easy
+and efficient way to improve performance when working with large data.
+Nonetheless, custom configuration can help to enhance the performance even further.
+
+Fast DDS provides configuration options to adjust the behavior of the builtin transports.
+This becomes particularly relevant when using the ``LARGE_DATA`` mode, as it enables increasing the maximum message
+size beyond 65500 KB and prevents fragmentation, leveraging the TCP and SHM transports.
+
+All builtin transports can be configured by adjusting the following parameters:
+
++ ``max_msg_size``: Message maximum size that can be sent over the transport.
+  Sending messages larger than this size will result in fragmentation.
+  Its maximum value is (2^32)-1 B for TCP and SHM and 65500 KB for UDP.
++ ``sockets_size``: Size of the send and receive socket buffers.
+  This value must be higher or equal than the ``max_msg_size`` to obtain a valid configuration.
+  Its maximum value is (2^32)-1 B.
++ ``non_blocking``: If set to true, the transport will use non-blocking sockets.
+  This can be useful to avoid blocking the application if the socket buffers are full.
+  However, some messages will be lost. Its default value is false.
++ ``tcp_negotiation_timeout``: It specifies the timeout duration for logical port negotiation.
+  This parameter is useful for ensuring the availability of the logical port before data transmission,
+  thus preventing message loss during the negotiation process.
+  Conversely, it can delay the discovery process.
+  The default value is 0, implying that discovery will occur as soon as possible, but the initial messages
+  might be lost if reliability is set to |BEST_EFFORT_RELIABILITY_QOS-api|.
+  This parameter is only valid for the ``LARGE_DATA`` mode.
+
+Adjusting the maximum message size and the socket buffer sizes to a large enough value to accommodate the data to be
+sent can help improve the performance with large messages, as well as setting the transport to non-blocking mode.
+
+In this way, it is possible to take advantage of the TCP transport to avoid fragmentation and use the non-blocking
+mode to avoid blocking the application when the socket buffers are full.
+This configuration can be used, for example, when streaming video, which will result in a significant increase
+in fluidity.
+
+Note that even when using the ``LARGE_DATA`` mode within the same machine, the configuration options
+can prove useful for improving performance, as they affect the SHM transport.
+It is highly recommended to set a shared memory segment size large enough to accommodate the data to be sent.
+To achieve this, the ``sockets_size`` parameter must be set to a value at least half of the message size.
+
+The following snippets show how to configure the ``LARGE_DATA`` mode:
+
+.. tabs::
+
+   .. tab:: Environment Variable
+
+      .. code-block:: bash
+
+         export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=1MB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50
+
+   .. tab:: XML
+
+      .. literalinclude:: /../code/XMLTester.xml
+         :language: xml
+         :start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS<-->
+         :end-before: <!--><-->
+         :lines: 2-4, 6-10, 12-13
+
+   .. tab:: C++
+
+      .. literalinclude:: ../../../../code/DDSCodeTester.cpp
+         :language: c++
+         :dedent: 8
+         :start-after: //LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS
+         :end-before: //!
+
+.. note::
+
+  To learn how to check and modify the default maximum system value for the socket buffers size, please refer to
+  :ref:`finding-out-maximum-socket-values`.
+
+.. warning::
+
+  Setting a ``max_msg_size`` value higher than 65500 KB with the ``DEFAULT`` or ``UDP`` modes will result in an error
+  and the participant creation will fail.
+
diff --git a/docs/fastdds/use_cases/tcp/tcp_use_case.rst b/docs/fastdds/use_cases/tcp/tcp_use_case.rst
@@ -24,6 +24,8 @@ when the deployment changes over time.
 networks. When configured, UDP transport will exclusively be used during the :ref:`PDP discovery<disc_phases>` phase,
 taking advantage of the more reliable TCP/SHM for the remainder of the communication process. Fast DDS offers
 an extremely straightforward implementation for this mode through an environment variable, XML profiles or via code.
+Additionally, it is possible to use the builtin transports configuration options to customize the ``LARGE_DATA`` mode
+to better suit the specific requirements of each user.
 
 For a video demonstration showcasing a practical example of this configuration, please refer to:
 `Large Data communication with ROS 2
@@ -36,4 +38,5 @@ Also, it is possible to enable TCP communication while using
     :maxdepth: 2
 
     /fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
+    /fastdds/use_cases/tcp/tcp_large_data_with_options.rst
     /fastdds/use_cases/tcp/tcp_with_discovery_server.rst
diff --git a/docs/fastdds/xml_configuration/common.rst b/docs/fastdds/xml_configuration/common.rst
@@ -20,6 +20,7 @@ This section aims to explain these common elements.
     -   :ref:`rLsQos`
 
 *   :ref:`ThreadSettingsType`
+*   :ref:`BuiltinTransportType`
 
 *   :ref:`CommonQOS`
 
@@ -351,6 +352,62 @@ Please refer to :ref:`threadsettingsqos` for further information on ResourceLimi
      - ``int32_t``
      - -1
 
+.. _BuiltinTransportType:
+
+BuiltinTransports
+^^^^^^^^^^^^^^^^^
+
+It controls the builtin transports that will be used during the initialization of the DomainParticipant.
+Please refer to :ref:`rtps_layer_builtin_transports` for further information on builtin transports.
+
+This type must follow this configuration:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+     - Values
+     - Default
+   * - ``<builtinTransport>``
+     - Defines the builtin transport mode.
+     - ``NONE`` |br| ``DEFAULT`` |br| ``DEFAULTv6`` |br| ``SHM`` |br| ``UDPv4`` |br| ``UDPv6``
+       |br| ``LARGE_DATA``
+     - ``DEFAULT``
+
+The ``<builtinTransport>`` tag can be configured with the following attributes:
+
+.. list-table::
+  :header-rows: 1
+  :align: left
+
+  * - Name
+    - Description
+    - Values
+    - Default
+  * - ``max_msg_size``
+    - Maximum message size that will be specified in
+      the transport layer. |br|
+      Valid values: from 1 to (2^32)-1.
+    - ``uint32_t``
+    - 65500
+  * - ``sockets_size``
+    - Size of the send and receive socket buffers.
+      Valid values: from 0 to (2^32)-1.
+    - ``uint32_t``
+    - OS default
+  * - ``non_blocking``
+    - Whether to use non-blocking send calls or not.
+      Valid values: ``true`` or ``false``.
+    - ``bool``
+    - ``false``
+  * - ``tcp_negotiation_timeout``
+    - Timeout duration for logical port negotiation.
+      Valid values: from 1 to (2^32)-1. |br|
+      Only valid for ``LARGE_DATA`` mode.
+    - ``uint32_t``
+    - 0
+
 .. _CommonQOS:
 
 QoS

diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst
@@ -66,6 +66,7 @@ These elements allow the user to define the DomainParticipant configuration.
 
 .. |PartAlloc| replace:: :ref:`DomainParticipantAllocationType <ParticipantAllocationType>`
 .. |PolicyType| replace:: :ref:`PropertiesPolicyType <PropertiesPolicyType>`
+.. |BuiltinTransportType| replace:: :ref:`BuiltinTransportType <BuiltinTransportType>`
 
 
 .. list-table::
@@ -156,8 +157,8 @@ These elements allow the user to define the DomainParticipant configuration.
      - Configuration option to determine which transports |br|
        will be instantiated if the ``useBuiltinTransports`` is |br|
        set to true. See :ref:`rtps_layer_builtin_transports`.
-     - ``string_255``
-     - DEFAULT
+     - |BuiltinTransportType|
+     -
    * - ``<propertiesPolicy>``
      - Additional configuration properties. |br|
        See :ref:`propertypolicyqos`.

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -119,6 +119,7 @@ GCC
 GCM
 getter
 getters
+gibibyte
 github
 Github
 GMAC
@@ -148,6 +149,7 @@ IPv
 json
 kB
 keyhash
+kibibyte
 latencies
 le
 Libp
@@ -163,6 +165,7 @@ LTS
 macOS
 mandatorily
 md
+mebibyte
 metatraffic
 middleware
 misconfigurations