Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[20501] Improve LARGE_DATA documentation (backport #671) #708

Merged
merged 2 commits into from
Mar 4, 2024
Merged

[20501] Improve LARGE_DATA documentation (backport #671) #708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b80d724
Improve LARGE_DATA documentation (#671)
cferreiragonz Feb 20, 2024
e619bf0
Fix conflicts
cferreiragonz Mar 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion code/XMLTester.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3890,7 +3890,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>
Expand Down
15 changes: 11 additions & 4 deletions docs/fastdds/rtps_layer/rtps_layer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,11 +179,18 @@ 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.
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.

.. 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
-------------------------------
Expand Down
22 changes: 14 additions & 8 deletions docs/fastdds/transport/tcp/tcp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
32 changes: 32 additions & 0 deletions docs/fastdds/troubleshooting/troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
2 changes: 2 additions & 0 deletions docs/fastdds/use_cases/large_data/large_data.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,6 +88,8 @@ as shown in the example below.
| :append: </profiles> |
+-------------------------------------------------------+

.. _finding-out-maximum-socket-values:

Finding out system maximum values
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
61 changes: 35 additions & 26 deletions docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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