From b80d724b903a476892d931fa946f27b310268c9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Ferreira=20Gonz=C3=A1lez?= Date: Tue, 20 Feb 2024 14:05:06 +0100 Subject: [PATCH 1/2] Improve LARGE_DATA documentation (#671) * Add sockets recommendation to LARGE_DATA mode Signed-off-by: cferreiragonz * Add environment variable to LARGE_DATA examples Signed-off-by: cferreiragonz * Add LARGE_DATA to troubleshooting Signed-off-by: cferreiragonz * Apply suggestions Signed-off-by: cferreiragonz --------- Signed-off-by: cferreiragonz (cherry picked from commit 2010219fbd1920b86c7bc00b7cea5034d5c30438) # Conflicts: # docs/fastdds/rtps_layer/rtps_layer.rst --- code/XMLTester.xml | 2 +- docs/fastdds/rtps_layer/rtps_layer.rst | 17 +++++- docs/fastdds/transport/tcp/tcp.rst | 22 ++++--- .../troubleshooting/troubleshooting.rst | 32 ++++++++++ .../use_cases/large_data/large_data.rst | 2 + .../tcp/tcp_with_multicast_discovery.rst | 61 +++++++++++-------- 6 files changed, 100 insertions(+), 36 deletions(-) diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 25f2079ec..a60da0d09 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -3890,7 +3890,7 @@ --> diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst index 334efff45..89dfe4e6e 100644 --- a/docs/fastdds/rtps_layer/rtps_layer.rst +++ b/docs/fastdds/rtps_layer/rtps_layer.rst @@ -179,11 +179,26 @@ 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: +<<<<<<< HEAD * |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. +======= + 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. +>>>>>>> 2010219 (Improve LARGE_DATA documentation (#671)) Configuring Readers and Writers ------------------------------- diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst index cf62063d7..59a48b365 100644 --- a/docs/fastdds/transport/tcp/tcp.rst +++ b/docs/fastdds/transport/tcp/tcp.rst @@ -177,18 +177,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 @@ -198,6 +196,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 index 3437527ad..3b7f45a2c 100644 --- 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` 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 index 438c4093d..e2fa33909 100644 --- 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: | +-------------------------------------------------------+ +.. _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 index 7052451f6..3ede52db7 100644 --- 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` 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 From e619bf0cc173d0d3180a929d26bfc0626ef94aed Mon Sep 17 00:00:00 2001 From: cferreiragonz Date: Mon, 4 Mar 2024 08:14:01 +0100 Subject: [PATCH 2/2] Fix conflicts Signed-off-by: cferreiragonz --- docs/fastdds/rtps_layer/rtps_layer.rst | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst index 89dfe4e6e..a66713dd6 100644 --- a/docs/fastdds/rtps_layer/rtps_layer.rst +++ b/docs/fastdds/rtps_layer/rtps_layer.rst @@ -180,25 +180,17 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R .. note:: -<<<<<<< HEAD - * |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. -======= 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. ->>>>>>> 2010219 (Improve LARGE_DATA documentation (#671)) Configuring Readers and Writers -------------------------------