Skip to content

Commit 48d5770

Browse files
cferreiragonzcferreiragonz
authored
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>
1 parent 195733c commit 48d5770

11 files changed

Lines changed: 262 additions & 7 deletions

File tree

‎code/DDSCodeTester.cpp‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6152,6 +6152,26 @@ void tcp_use_cases()
61526152
//!
61536153
}
61546154

6155+
{
6156+
//LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS
6157+
eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;
6158+
6159+
/* Transports configuration */
6160+
// UDPv4 transport for PDP over multicast and SHM / TCPv4 transport for EDP and application data
6161+
// Message Size and Sockets sizes of 200 KB + Non-blocking send + 50ms negotiation timeout
6162+
eprosima::fastdds::rtps::BuiltinTransportsOptions large_data_options;
6163+
large_data_options.maxMessageSize = 200000;
6164+
large_data_options.sockets_buffer_size = 200000;
6165+
large_data_options.non_blocking_send = true;
6166+
large_data_options.tcp_negotiation_timeout = 50;
6167+
pqos.setup_transports(eprosima::fastdds::rtps::BuiltinTransports::LARGE_DATA, large_data_options);
6168+
6169+
/* Create participant as usual */
6170+
eprosima::fastdds::dds::DomainParticipant* participant =
6171+
eprosima::fastdds::dds::DomainParticipantFactory::get_instance()->create_participant(0, pqos);
6172+
//!
6173+
}
6174+
61556175
{
61566176
//PDP-MULTICAST-DATA-TCP
61576177
eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;

‎code/XMLTester.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3905,6 +3905,23 @@
39053905
-->
39063906
<!--><-->
39073907

3908+
<!-->LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS<-->
3909+
<!--
3910+
<?xml version="1.0" encoding="UTF-8" ?>
3911+
<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
3912+
<profiles>
3913+
-->
3914+
<participant profile_name="large_data_builtin_transports_options" is_default_profile="true">
3915+
<rtps>
3916+
<builtinTransports max_msg_size="200KB" sockets_size="200KB" non_blocking="true" tcp_negotiation_timeout="50">LARGE_DATA</builtinTransports>
3917+
</rtps>
3918+
</participant>
3919+
<!--
3920+
</profiles>
3921+
</dds>
3922+
-->
3923+
<!--><-->
3924+
39083925
<!-->PDP-MULTICAST-DATA-TCP<-->
39093926
<!--
39103927
<?xml version="1.0" encoding="UTF-8" ?>

‎code/XMLTesterExample.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -399,7 +399,7 @@
399399

400400
<useBuiltinTransports>false</useBuiltinTransports>
401401

402-
<builtinTransports>DEFAULT</builtinTransports>
402+
<builtinTransports max_msg_size="50KB" sockets_size="50KB" non_blocking="false">DEFAULT</builtinTransports>
403403

404404
<propertiesPolicy>
405405
<properties>

‎docs/fastdds/env_vars/env_vars.rst‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,72 @@ All existing values, along with a brief description, are shown below:
108108
* |TCPTransportDescriptor::keep_alive_thread-api| and
109109
|TCPTransportDescriptor::accept_thread-api| use the default configuration.
110110

111+
.. _env_vars_large_data_options:
112+
113+
Configuring builtin transports options
114+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
115+
116+
Fast DDS offers a straightforward method to configure three main parameters of every builtin transport via the
117+
environment variable.
118+
However, this feature proves particularly valuable when employing the ``LARGE_DATA`` builtin
119+
transports option.
120+
The ``LARGE_DATA`` mode has been designed to improve performance when working with large data.
121+
However, according to each specific use case, the user might want to configure several options to better fit their
122+
needs.
123+
This mode can also be configured with the ``tcp_negotiation_timeout`` parameter:
124+
125+
+----------------------------+--------------------------------------------------------------------+-------------------+
126+
| Builtin Transports Options | Description | Type |
127+
+============================+====================================================================+===================+
128+
| ``max_msg_size`` | It determines the maximum message size that will be specified |br| | uint32_t |
129+
| | in the transport layer. Selecting a message size large |br| | |
130+
| | enough to accommodate the largest data message will |br| | |
131+
| | prevent fragmentation, which can significantly enhance |br| | |
132+
| | the overall sending rate. | |
133+
+----------------------------+--------------------------------------------------------------------+-------------------+
134+
| ``sockets_size`` | It determines the size of the send and receive socket buffers. |br|| uint32_t |
135+
| | This parameter needs to be higher or equal to the maximum |br| | |
136+
| | message size specified in order to be valid. | |
137+
+----------------------------+--------------------------------------------------------------------+-------------------+
138+
| ``non_blocking`` | It determines whether to use non-blocking send calls or not. |br| | bool |
139+
| | When activated, the transport will discard messages if the |br| | |
140+
| | socket buffers are full. | |
141+
+----------------------------+--------------------------------------------------------------------+-------------------+
142+
| ``tcp_negotiation_timeout``| It determines the time to wait for logical port negotiation. |br| | uint32_t |
143+
| | Only valid if the ``LARGE_DATA`` mode is being used. |br| | |
144+
| | It only accepts milliseconds. | |
145+
+----------------------------+--------------------------------------------------------------------+-------------------+
146+
147+
The environment variable accepts several types of units to specify the values of the parameters.
148+
Also, both lowercase and uppercase letters are valid.
149+
The following list shows the available units and their corresponding symbols:
150+
151+
+ ``B``: Bytes. This is the default unit, so it is not necessary to specify it.
152+
+ ``KB``: Kilobytes.
153+
+ ``MB``: Megabytes.
154+
+ ``GB``: Gigabytes.
155+
+ ``KIB``: Kibibyte.
156+
+ ``MIB``: Mebibyte.
157+
+ ``GIB``: Gibibyte.
158+
159+
.. code-block:: bash
160+
161+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=200KB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50
162+
163+
.. note::
164+
When working with ``LARGE_DATA``, it is recommended to set the ``max_msg_size`` and ``sockets_size`` to a value
165+
large enough to accommodate the largest data message and to set the ``non_blocking`` to ``TRUE``.
166+
Note that activating the ``non_blocking`` option with a small message size (with fragmentation)
167+
can lead to an increase of messages drop rate and produce undesired results.
168+
For more information, please refer to :ref:`use-case-large-data-options`.
169+
170+
.. warning::
171+
Setting a ``max_msg_size`` higher than 65500 KB is only possible when using the ``LARGE_DATA`` builtin transports
172+
option.
173+
Trying to set it with any other builtin transports will result in an error and the creation of the participant
174+
will fail.
175+
176+
111177
.. _env_vars_ros_discovery_server:
112178

113179
``ROS_DISCOVERY_SERVER``

‎docs/fastdds/rtps_layer/rtps_layer.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -190,9 +190,9 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R
190190

191191
.. warning::
192192

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.
193+
To obtain a better performance when working with large data messages it is extremely recommended to use the
194+
builtin transports configuration options to adjust the transport to the specific needs of the application.
195+
Please refer to :ref:`use-case-large-data-options` for more information about how to configure it.
196196

197197
Configuring Readers and Writers
198198
-------------------------------

‎docs/fastdds/troubleshooting/troubleshooting.rst‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,5 +38,9 @@ issues.
3838
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
3939
:end-before: //!
4040

41-
* Problems with transmitting **large samples such as video or point clouds**? Please refer to
41+
* If having problems with transmitting **large samples** when using the ``LARGE_DATA`` mode, try to use the builtin
42+
transports configuration options to adjust ``LARGE_DATA`` to your specific use case.
43+
Please refer to :ref:`use-case-large-data-options` for more information.
44+
45+
* If having problems with transmitting **large samples such as video or point clouds**, please refer to
4246
:ref:`use-case-largeData`.

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

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
.. include:: ../../../03-exports/aliases.include
2+
.. include:: ../../../03-exports/aliases-api.include
3+
4+
.. _use-case-large-data-options:
5+
6+
Large Data with configuration options
7+
=====================================
8+
9+
As it has been observed in :ref:`use-case-tcp-multicast`, ``LARGE_DATA`` builtin transports option offers an easy
10+
and efficient way to improve performance when working with large data.
11+
Nonetheless, custom configuration can help to enhance the performance even further.
12+
13+
Fast DDS provides configuration options to adjust the behavior of the builtin transports.
14+
This becomes particularly relevant when using the ``LARGE_DATA`` mode, as it enables increasing the maximum message
15+
size beyond 65500 KB and prevents fragmentation, leveraging the TCP and SHM transports.
16+
17+
All builtin transports can be configured by adjusting the following parameters:
18+
19+
+ ``max_msg_size``: Message maximum size that can be sent over the transport.
20+
Sending messages larger than this size will result in fragmentation.
21+
Its maximum value is (2^32)-1 B for TCP and SHM and 65500 KB for UDP.
22+
+ ``sockets_size``: Size of the send and receive socket buffers.
23+
This value must be higher or equal than the ``max_msg_size`` to obtain a valid configuration.
24+
Its maximum value is (2^32)-1 B.
25+
+ ``non_blocking``: If set to true, the transport will use non-blocking sockets.
26+
This can be useful to avoid blocking the application if the socket buffers are full.
27+
However, some messages will be lost. Its default value is false.
28+
+ ``tcp_negotiation_timeout``: It specifies the timeout duration for logical port negotiation.
29+
This parameter is useful for ensuring the availability of the logical port before data transmission,
30+
thus preventing message loss during the negotiation process.
31+
Conversely, it can delay the discovery process.
32+
The default value is 0, implying that discovery will occur as soon as possible, but the initial messages
33+
might be lost if reliability is set to |BEST_EFFORT_RELIABILITY_QOS-api|.
34+
This parameter is only valid for the ``LARGE_DATA`` mode.
35+
36+
Adjusting the maximum message size and the socket buffer sizes to a large enough value to accommodate the data to be
37+
sent can help improve the performance with large messages, as well as setting the transport to non-blocking mode.
38+
39+
In this way, it is possible to take advantage of the TCP transport to avoid fragmentation and use the non-blocking
40+
mode to avoid blocking the application when the socket buffers are full.
41+
This configuration can be used, for example, when streaming video, which will result in a significant increase
42+
in fluidity.
43+
44+
Note that even when using the ``LARGE_DATA`` mode within the same machine, the configuration options
45+
can prove useful for improving performance, as they affect the SHM transport.
46+
It is highly recommended to set a shared memory segment size large enough to accommodate the data to be sent.
47+
To achieve this, the ``sockets_size`` parameter must be set to a value at least half of the message size.
48+
49+
The following snippets show how to configure the ``LARGE_DATA`` mode:
50+
51+
.. tabs::
52+
53+
.. tab:: Environment Variable
54+
55+
.. code-block:: bash
56+
57+
export FASTDDS_BUILTIN_TRANSPORTS=LARGE_DATA?max_msg_size=1MB&sockets_size=1MB&non_blocking=true&tcp_negotiation_timeout=50
58+
59+
.. tab:: XML
60+
61+
.. literalinclude:: /../code/XMLTester.xml
62+
:language: xml
63+
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS<-->
64+
:end-before: <!--><-->
65+
:lines: 2-4, 6-10, 12-13
66+
67+
.. tab:: C++
68+
69+
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
70+
:language: c++
71+
:dedent: 8
72+
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS_OPTIONS
73+
:end-before: //!
74+
75+
.. note::
76+
77+
To learn how to check and modify the default maximum system value for the socket buffers size, please refer to
78+
:ref:`finding-out-maximum-socket-values`.
79+
80+
.. warning::
81+
82+
Setting a ``max_msg_size`` value higher than 65500 KB with the ``DEFAULT`` or ``UDP`` modes will result in an error
83+
and the participant creation will fail.
84+

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ when the deployment changes over time.
2424
networks. When configured, UDP transport will exclusively be used during the :ref:`PDP discovery<disc_phases>` phase,
2525
taking advantage of the more reliable TCP/SHM for the remainder of the communication process. Fast DDS offers
2626
an extremely straightforward implementation for this mode through an environment variable, XML profiles or via code.
27+
Additionally, it is possible to use the builtin transports configuration options to customize the ``LARGE_DATA`` mode
28+
to better suit the specific requirements of each user.
2729

2830
For a video demonstration showcasing a practical example of this configuration, please refer to:
2931
`Large Data communication with ROS 2
@@ -36,4 +38,5 @@ Also, it is possible to enable TCP communication while using
3638
:maxdepth: 2
3739

3840
/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
41+
/fastdds/use_cases/tcp/tcp_large_data_with_options.rst
3942
/fastdds/use_cases/tcp/tcp_with_discovery_server.rst

‎docs/fastdds/xml_configuration/common.rst‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This section aims to explain these common elements.
2020
- :ref:`rLsQos`
2121

2222
* :ref:`ThreadSettingsType`
23+
* :ref:`BuiltinTransportType`
2324

2425
* :ref:`CommonQOS`
2526

@@ -351,6 +352,62 @@ Please refer to :ref:`threadsettingsqos` for further information on ResourceLimi
351352
- ``int32_t``
352353
- -1
353354

355+
.. _BuiltinTransportType:
356+
357+
BuiltinTransports
358+
^^^^^^^^^^^^^^^^^
359+
360+
It controls the builtin transports that will be used during the initialization of the DomainParticipant.
361+
Please refer to :ref:`rtps_layer_builtin_transports` for further information on builtin transports.
362+
363+
This type must follow this configuration:
364+
365+
.. list-table::
366+
:header-rows: 1
367+
368+
* - Name
369+
- Description
370+
- Values
371+
- Default
372+
* - ``<builtinTransport>``
373+
- Defines the builtin transport mode.
374+
- ``NONE`` |br| ``DEFAULT`` |br| ``DEFAULTv6`` |br| ``SHM`` |br| ``UDPv4`` |br| ``UDPv6``
375+
|br| ``LARGE_DATA``
376+
- ``DEFAULT``
377+
378+
The ``<builtinTransport>`` tag can be configured with the following attributes:
379+
380+
.. list-table::
381+
:header-rows: 1
382+
:align: left
383+
384+
* - Name
385+
- Description
386+
- Values
387+
- Default
388+
* - ``max_msg_size``
389+
- Maximum message size that will be specified in
390+
the transport layer. |br|
391+
Valid values: from 1 to (2^32)-1.
392+
- ``uint32_t``
393+
- 65500
394+
* - ``sockets_size``
395+
- Size of the send and receive socket buffers.
396+
Valid values: from 0 to (2^32)-1.
397+
- ``uint32_t``
398+
- OS default
399+
* - ``non_blocking``
400+
- Whether to use non-blocking send calls or not.
401+
Valid values: ``true`` or ``false``.
402+
- ``bool``
403+
- ``false``
404+
* - ``tcp_negotiation_timeout``
405+
- Timeout duration for logical port negotiation.
406+
Valid values: from 1 to (2^32)-1. |br|
407+
Only valid for ``LARGE_DATA`` mode.
408+
- ``uint32_t``
409+
- 0
410+
354411
.. _CommonQOS:
355412

356413
QoS

‎docs/fastdds/xml_configuration/domainparticipant.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ These elements allow the user to define the DomainParticipant configuration.
6666

6767
.. |PartAlloc| replace:: :ref:`DomainParticipantAllocationType <ParticipantAllocationType>`
6868
.. |PolicyType| replace:: :ref:`PropertiesPolicyType <PropertiesPolicyType>`
69+
.. |BuiltinTransportType| replace:: :ref:`BuiltinTransportType <BuiltinTransportType>`
6970

7071

7172
.. list-table::
@@ -156,8 +157,8 @@ These elements allow the user to define the DomainParticipant configuration.
156157
- Configuration option to determine which transports |br|
157158
will be instantiated if the ``useBuiltinTransports`` is |br|
158159
set to true. See :ref:`rtps_layer_builtin_transports`.
159-
- ``string_255``
160-
- DEFAULT
160+
- |BuiltinTransportType|
161+
-
161162
* - ``<propertiesPolicy>``
162163
- Additional configuration properties. |br|
163164
See :ref:`propertypolicyqos`.

0 commit comments

Comments
 (0)