Improve LARGE_DATA documentation (#671)

* Add sockets recommendation to LARGE_DATA mode Signed-off-by: cferreiragonz <[email protected]> * Add environment variable to LARGE_DATA examples Signed-off-by: cferreiragonz <[email protected]> * Add LARGE_DATA to troubleshooting Signed-off-by: cferreiragonz <[email protected]> * Apply suggestions Signed-off-by: cferreiragonz <[email protected]> --------- Signed-off-by: cferreiragonz <[email protected]>
eProsima · Feb 20, 2024 · 2010219 · 2010219
1 parent ce44681
commit 2010219
Show file tree

Hide file tree

Showing 6 changed files with 97 additions and 41 deletions.
diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -3884,7 +3884,7 @@
     <profiles>
 -->
         <!--
-            UDP transport for PDP and TCP transport for both EDP and application data
+            UDP transport for PDP and SHM/TCPv4 transport for both EDP and application data
         -->
         <participant profile_name="large_data_builtin_transports" is_default_profile="true">
             <rtps>

diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst
@@ -179,13 +179,20 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R
 ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable (see :ref:`env_vars_builtin_transports`).
 
 .. note::
-     TCPv4 transport is initialized with the following configuration:
 
-     * |TCPTransportDescriptor::calculate_crc-api|, |TCPTransportDescriptor::check_crc-api| and
-       |TCPTransportDescriptor::apply_security-api| are set to false.
-     * |TCPTransportDescriptor::enable_tcp_nodelay-api| is set to true.
-     * |TCPTransportDescriptor::keep_alive_thread-api| and
-       |TCPTransportDescriptor::accept_thread-api| use the default configuration.
+  TCPv4 transport is initialized with the following configuration:
+
+    * |TCPTransportDescriptor::calculate_crc-api|, |TCPTransportDescriptor::check_crc-api| and
+      |TCPTransportDescriptor::apply_security-api| are set to false.
+    * |TCPTransportDescriptor::enable_tcp_nodelay-api| is set to true.
+    * |TCPTransportDescriptor::keep_alive_thread-api| and
+      |TCPTransportDescriptor::accept_thread-api| use the default configuration.
+
+.. 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.
 
 Configuring Readers and Writers
 -------------------------------

diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst
@@ -194,18 +194,16 @@ the application data delivery occurs over TCP or SHM. This configuration enables
 require to manually set up each participant IP and listening port. Hence, avoiding the typical Server-Client
 configuration.
 
-Builtin Transports can be configured via code, XML (see :ref:`RTPS`) or using the ``FASTDDS_BUILTIN_TRANSPORTS``
-environment variable (see :ref:`env_vars_builtin_transports`).
+Builtin Transports can be configured using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable (see
+:ref:`env_vars_builtin_transports`), XML profiles (see :ref:`RTPS`) or via code.
 
 .. tabs::
 
-  .. tab:: C++
+  .. tab:: Environment Variable
 
-    .. literalinclude:: /../code/DDSCodeTester.cpp
-      :language: c++
-      :start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
-      :end-before: //!--
-      :dedent: 8
+      .. code-block:: bash
+
+          export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
 
   .. tab:: XML
 
@@ -215,6 +213,14 @@ environment variable (see :ref:`env_vars_builtin_transports`).
         :end-before: <!--><-->
         :lines: 2-4, 6-13, 15-16
 
+  .. tab:: C++
+
+    .. literalinclude:: /../code/DDSCodeTester.cpp
+      :language: c++
+      :start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
+      :end-before: //!--
+      :dedent: 8
+
 .. note::
    Note that ``LARGE_DATA`` configuration of the builtin transports will also create a SHM transport along the UDP
    and TCP transports. Shared Memory will be used whenever it is possible. Manual configuration will be required

diff --git a/docs/fastdds/troubleshooting/troubleshooting.rst b/docs/fastdds/troubleshooting/troubleshooting.rst
@@ -6,5 +6,37 @@ Troubleshooting
 This section offers hints and pointers to help users with navigating through the documentation while troubleshooting
 issues.
 
+* Although UDP/SHM default transports of Fast DDS are designed to work in most network environments, they may encounter
+  certain limitations when operating over WiFi or within lossy network conditions. In these cases, it is advisable to
+  set up the ``LARGE_DATA`` configuration, which has been specifically optimized for these scenarios. The
+  ``LARGE_DATA`` profile limits the use of UDP solely to the :ref:`PDP discovery<disc_phases>` phase, employing the more
+  reliable TCP/SHM for the remainder of the communication process. Its implementation can be accomplished by simply
+  configuring the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable, or alternatively through XML profiles
+  or via code. For more information, please refer to :ref:`use-case-tcp-multicast`.
+
+  .. tabs::
+
+   .. tab:: Environment Variable
+
+      .. code-block:: bash
+
+          export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
+
+   .. tab:: XML
+
+      .. literalinclude:: /../code/XMLTester.xml
+          :language: xml
+          :start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
+          :end-before: <!--><-->
+          :lines: 2-4, 6-13, 15-16
+
+   .. tab:: C++
+
+      .. literalinclude:: ../../../code/DDSCodeTester.cpp
+        :language: c++
+        :dedent: 8
+        :start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
+        :end-before: //!
+
 * 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/large_data/large_data.rst b/docs/fastdds/use_cases/large_data/large_data.rst
@@ -88,6 +88,8 @@ as shown in the example below.
 |    :append: </profiles>                               |
 +-------------------------------------------------------+
 
+.. _finding-out-maximum-socket-values:
+
 Finding out system maximum values
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst b/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
@@ -3,52 +3,61 @@
 
 .. _use-case-tcp-multicast:
 
-TCP / SHM Communication with Multicast Discovery
-================================================
+TCP / SHM Communication with Multicast Discovery (LARGE_DATA)
+=============================================================
 
 The following snippets show how to configure *Fast DDS* |DomainParticipants| to run the
 :ref:`PDP discovery<disc_phases>` phase over UDP multicast and communicate application data over a
-:ref:`transport_tcp_tcp` transport.
+:ref:`transport_tcp_tcp` or :ref:`transport_sharedMemory_sharedMemory`, which is called the ``LARGE_DATA``
+configuration (See :ref:`rtps_layer_builtin_transports`).
 With this approach, applications managing large samples can benefit from transmitting their data over TCP or SHM,
 while at the same time have the flexibility of automatic discovery.
+The ``LARGE_DATA`` mode can be set using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable
+(see :ref:`env_vars_builtin_transports`), XML profiles or via code.
 
 .. tabs::
 
-   .. tab:: C++
+   .. tab:: Environment Variable
 
-      .. literalinclude:: ../../../../code/DDSCodeTester.cpp
-        :language: c++
-        :dedent: 8
-        :start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
-        :end-before: //!
+      .. code-block:: bash
+
+         export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
 
    .. tab:: XML
 
       .. literalinclude:: /../code/XMLTester.xml
-          :language: xml
-          :start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
-          :end-before: <!--><-->
-          :lines: 2-4, 6-13, 15-16
+         :language: xml
+         :start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
+         :end-before: <!--><-->
+         :lines: 2-4, 6-13, 15-16
+
+   .. tab:: C++
+
+      .. literalinclude:: ../../../../code/DDSCodeTester.cpp
+         :language: c++
+         :dedent: 8
+         :start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
+         :end-before: //!
 
 .. note::
    ``LARGE_DATA`` configuration of the builtin transports will also create a SHM transport along the UDP and TCP
    transports. Shared Memory will be used whenever it is possible. Manual configuration will be required if a TCP
    communication is required when SHM is feasible.
 
-.. tabs::
+   .. tabs::
 
-   .. tab:: C++
+      .. tab:: C++
 
-      .. literalinclude:: ../../../../code/DDSCodeTester.cpp
-        :language: c++
-        :dedent: 8
-        :start-after: //PDP-MULTICAST-DATA-TCP
-        :end-before: //!
+         .. literalinclude:: ../../../../code/DDSCodeTester.cpp
+            :language: c++
+            :dedent: 8
+            :start-after: //PDP-MULTICAST-DATA-TCP
+            :end-before: //!
 
-   .. tab:: XML
+      .. tab:: XML
 
-      .. literalinclude:: /../code/XMLTester.xml
-          :language: xml
-          :start-after: <!-->PDP-MULTICAST-DATA-TCP<-->
-          :end-before: <!--><-->
-          :lines: 2-4, 6-80, 82-83
+         .. literalinclude:: /../code/XMLTester.xml
+            :language: xml
+            :start-after: <!-->PDP-MULTICAST-DATA-TCP<-->
+            :end-before: <!--><-->
+            :lines: 2-4, 6-80, 82-83