Skip to content

Commit 2010219

Browse files
cferreiragonzcferreiragonz
authored
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]>
1 parent ce44681 commit 2010219

File tree

6 files changed

+97
-41
lines changed

6 files changed

+97
-41
lines changed

‎code/XMLTester.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3884,7 +3884,7 @@
38843884
<profiles>
38853885
-->
38863886
<!--
3887-
UDP transport for PDP and TCP transport for both EDP and application data
3887+
UDP transport for PDP and SHM/TCPv4 transport for both EDP and application data
38883888
-->
38893889
<participant profile_name="large_data_builtin_transports" is_default_profile="true">
38903890
<rtps>

‎docs/fastdds/rtps_layer/rtps_layer.rst

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -179,13 +179,20 @@ 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.
187-
* |TCPTransportDescriptor::keep_alive_thread-api| and
188-
|TCPTransportDescriptor::accept_thread-api| use the default configuration.
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+
* |TCPTransportDescriptor::keep_alive_thread-api| and
189+
|TCPTransportDescriptor::accept_thread-api| use the default configuration.
190+
191+
.. warning::
192+
193+
To obtain a better performance when working with large data messages it is extremely recommended to set through
194+
:ref:`dds_layer_domainParticipantQos` the send and receive buffer sizes of the TCP transport to the maximum default
195+
system value. See :ref:`finding-out-maximum-socket-values` to learn how to check it.
189196

190197
Configuring Readers and Writers
191198
-------------------------------

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

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

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

200200
.. tabs::
201201

202-
.. tab:: C++
202+
.. tab:: Environment Variable
203203

204-
.. literalinclude:: /../code/DDSCodeTester.cpp
205-
:language: c++
206-
:start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
207-
:end-before: //!--
208-
:dedent: 8
204+
.. code-block:: bash
205+
206+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA
209207
210208
.. tab:: XML
211209

@@ -215,6 +213,14 @@ environment variable (see :ref:`env_vars_builtin_transports`).
215213
:end-before: <!--><-->
216214
:lines: 2-4, 6-13, 15-16
217215

216+
.. tab:: C++
217+
218+
.. literalinclude:: /../code/DDSCodeTester.cpp
219+
:language: c++
220+
:start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
221+
:end-before: //!--
222+
:dedent: 8
223+
218224
.. note::
219225
Note that ``LARGE_DATA`` configuration of the builtin transports will also create a SHM transport along the UDP
220226
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)