Skip to content

Commit 791aab4

Browse files
mergify[bot]cferreiragonz
mergify[bot]
and
cferreiragonz
authored
Improve LARGE_DATA documentation (#671) (#708)
* Improve LARGE_DATA documentation (#671) * Add sockets recommendation to LARGE_DATA mode Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Add environment variable to LARGE_DATA examples Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Add LARGE_DATA to troubleshooting Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> * Apply suggestions Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> --------- Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> (cherry picked from commit 2010219) # Conflicts: # docs/fastdds/rtps_layer/rtps_layer.rst * Fix conflicts Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> --------- Signed-off-by: cferreiragonz <carlosferreira@eprosima.com> Co-authored-by: Carlos Ferreira González <carlosferreira@eprosima.com>
1 parent 175f7d3 commit 791aab4

6 files changed

Lines changed: 95 additions & 39 deletions

File tree

‎code/XMLTester.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3890,7 +3890,7 @@
38903890
<profiles>
38913891
-->
38923892
<!--
3893-
UDP transport for PDP and TCP transport for both EDP and application data
3893+
UDP transport for PDP and SHM/TCPv4 transport for both EDP and application data
38943894
-->
38953895
<participant profile_name="large_data_builtin_transports" is_default_profile="true">
38963896
<rtps>

‎docs/fastdds/rtps_layer/rtps_layer.rst‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -179,11 +179,18 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R
179179
``FASTDDS_BUILTIN_TRANSPORTS`` environment variable (see :ref:`env_vars_builtin_transports`).
180180

181181
.. note::
182-
TCPv4 transport is initialized with the following configuration:
183182

184-
* |TCPTransportDescriptor::calculate_crc-api|, |TCPTransportDescriptor::check_crc-api| and
185-
|TCPTransportDescriptor::apply_security-api| are set to false.
186-
* |TCPTransportDescriptor::enable_tcp_nodelay-api| is set to true.
183+
TCPv4 transport is initialized with the following configuration:
184+
185+
* |TCPTransportDescriptor::calculate_crc-api|, |TCPTransportDescriptor::check_crc-api| and
186+
|TCPTransportDescriptor::apply_security-api| are set to false.
187+
* |TCPTransportDescriptor::enable_tcp_nodelay-api| is set to true.
188+
189+
.. warning::
190+
191+
To obtain a better performance when working with large data messages it is extremely recommended to set through
192+
:ref:`dds_layer_domainParticipantQos` the send and receive buffer sizes of the TCP transport to the maximum default
193+
system value. See :ref:`finding-out-maximum-socket-values` to learn how to check it.
187194

188195
Configuring Readers and Writers
189196
-------------------------------

‎docs/fastdds/transport/tcp/tcp.rst‎

Lines changed: 14 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -177,18 +177,16 @@ the application data delivery occurs over TCP or SHM. This configuration enables
177177
require to manually set up each participant IP and listening port. Hence, avoiding the typical Server-Client
178178
configuration.
179179

180-
Builtin Transports can be configured via code, XML (see :ref:`RTPS`) or using the ``FASTDDS_BUILTIN_TRANSPORTS``
181-
environment variable (see :ref:`env_vars_builtin_transports`).
180+
Builtin Transports can be configured using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable (see
181+
:ref:`env_vars_builtin_transports`), XML profiles (see :ref:`RTPS`) or via code.
182182

183183
.. tabs::
184184

185-
.. tab:: C++
185+
.. tab:: Environment Variable
186186

187-
.. literalinclude:: /../code/DDSCodeTester.cpp
188-
:language: c++
189-
:start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
190-
:end-before: //!--
191-
:dedent: 8
187+
.. code-block:: bash
188+
189+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
192190
193191
.. tab:: XML
194192

@@ -198,6 +196,14 @@ environment variable (see :ref:`env_vars_builtin_transports`).
198196
:end-before: <!--><-->
199197
:lines: 2-4, 6-13, 15-16
200198

199+
.. tab:: C++
200+
201+
.. literalinclude:: /../code/DDSCodeTester.cpp
202+
:language: c++
203+
:start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
204+
:end-before: //!--
205+
:dedent: 8
206+
201207
.. note::
202208
Note that ``LARGE_DATA`` configuration of the builtin transports will also create a SHM transport along the UDP
203209
and TCP transports. Shared Memory will be used whenever it is possible. Manual configuration will be required

‎docs/fastdds/troubleshooting/troubleshooting.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,37 @@ Troubleshooting
66
This section offers hints and pointers to help users with navigating through the documentation while troubleshooting
77
issues.
88

9+
* Although UDP/SHM default transports of Fast DDS are designed to work in most network environments, they may encounter
10+
certain limitations when operating over WiFi or within lossy network conditions. In these cases, it is advisable to
11+
set up the ``LARGE_DATA`` configuration, which has been specifically optimized for these scenarios. The
12+
``LARGE_DATA`` profile limits the use of UDP solely to the :ref:`PDP discovery<disc_phases>` phase, employing the more
13+
reliable TCP/SHM for the remainder of the communication process. Its implementation can be accomplished by simply
14+
configuring the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable, or alternatively through XML profiles
15+
or via code. For more information, please refer to :ref:`use-case-tcp-multicast`.
16+
17+
.. tabs::
18+
19+
.. tab:: Environment Variable
20+
21+
.. code-block:: bash
22+
23+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
24+
25+
.. tab:: XML
26+
27+
.. literalinclude:: /../code/XMLTester.xml
28+
:language: xml
29+
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
30+
:end-before: <!--><-->
31+
:lines: 2-4, 6-13, 15-16
32+
33+
.. tab:: C++
34+
35+
.. literalinclude:: ../../../code/DDSCodeTester.cpp
36+
:language: c++
37+
:dedent: 8
38+
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
39+
:end-before: //!
40+
941
* Problems with transmitting **large samples such as video or point clouds**? Please refer to
1042
:ref:`use-case-largeData`.

‎docs/fastdds/use_cases/large_data/large_data.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ as shown in the example below.
8888
| :append: </profiles> |
8989
+-------------------------------------------------------+
9090

91+
.. _finding-out-maximum-socket-values:
92+
9193
Finding out system maximum values
9294
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
9395

‎docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst‎

Lines changed: 35 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,52 +3,61 @@
33

44
.. _use-case-tcp-multicast:
55

6-
TCP / SHM Communication with Multicast Discovery
7-
================================================
6+
TCP / SHM Communication with Multicast Discovery (LARGE_DATA)
7+
=============================================================
88

99
The following snippets show how to configure *Fast DDS* |DomainParticipants| to run the
1010
:ref:`PDP discovery<disc_phases>` phase over UDP multicast and communicate application data over a
11-
:ref:`transport_tcp_tcp` transport.
11+
:ref:`transport_tcp_tcp` or :ref:`transport_sharedMemory_sharedMemory`, which is called the ``LARGE_DATA``
12+
configuration (See :ref:`rtps_layer_builtin_transports`).
1213
With this approach, applications managing large samples can benefit from transmitting their data over TCP or SHM,
1314
while at the same time have the flexibility of automatic discovery.
15+
The ``LARGE_DATA`` mode can be set using the ``FASTDDS_BUILTIN_TRANSPORTS`` environment variable
16+
(see :ref:`env_vars_builtin_transports`), XML profiles or via code.
1417

1518
.. tabs::
1619

17-
.. tab:: C++
20+
.. tab:: Environment Variable
1821

19-
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
20-
:language: c++
21-
:dedent: 8
22-
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
23-
:end-before: //!
22+
.. code-block:: bash
23+
24+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
2425
2526
.. tab:: XML
2627

2728
.. literalinclude:: /../code/XMLTester.xml
28-
:language: xml
29-
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
30-
:end-before: <!--><-->
31-
:lines: 2-4, 6-13, 15-16
29+
:language: xml
30+
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
31+
:end-before: <!--><-->
32+
:lines: 2-4, 6-13, 15-16
33+
34+
.. tab:: C++
35+
36+
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
37+
:language: c++
38+
:dedent: 8
39+
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
40+
:end-before: //!
3241

3342
.. note::
3443
``LARGE_DATA`` configuration of the builtin transports will also create a SHM transport along the UDP and TCP
3544
transports. Shared Memory will be used whenever it is possible. Manual configuration will be required if a TCP
3645
communication is required when SHM is feasible.
3746

38-
.. tabs::
47+
.. tabs::
3948

40-
.. tab:: C++
49+
.. tab:: C++
4150

42-
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
43-
:language: c++
44-
:dedent: 8
45-
:start-after: //PDP-MULTICAST-DATA-TCP
46-
:end-before: //!
51+
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
52+
:language: c++
53+
:dedent: 8
54+
:start-after: //PDP-MULTICAST-DATA-TCP
55+
:end-before: //!
4756

48-
.. tab:: XML
57+
.. tab:: XML
4958

50-
.. literalinclude:: /../code/XMLTester.xml
51-
:language: xml
52-
:start-after: <!-->PDP-MULTICAST-DATA-TCP<-->
53-
:end-before: <!--><-->
54-
:lines: 2-4, 6-80, 82-83
59+
.. literalinclude:: /../code/XMLTester.xml
60+
:language: xml
61+
:start-after: <!-->PDP-MULTICAST-DATA-TCP<-->
62+
:end-before: <!--><-->
63+
:lines: 2-4, 6-80, 82-83

0 commit comments

Comments
 (0)