Skip to content

Commit

Permalink
Methods to configure transport scenarios Documentation (#619)
Browse files Browse the repository at this point in the history 
* Refs #20021: New TCP w/ Disc.Server example

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20021: fix XML example

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20021: Correct tests

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20021: Apply Revision's changes

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20021: Update use case and CLI

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add RTPS Attributes docs

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add XML builtin transports docs

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add new function reference

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add new environment variable docs

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add note in TrasnportConfigQos

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add new method of enabling TCP

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Modify UDP+TCP use case

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Minor fixes

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Apply revision's changes and format table

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Fix v6 missing

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Remove v6 from builtin transports table

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Apply revision's changes

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

* Refs #20020: Add Dedent

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>

---------

Signed-off-by: cferreiragonz <carlosferreira@eprosima.com>
  • Loading branch information
@cferreiragonz
cferreiragonz committed Dec 19, 2023
1 parent e1f4d65 commit b3bf26c
Show file tree
Hide file tree
Showing 12 changed files with 257 additions and 8 deletions.
11 changes: 10 additions & 1 deletion code/CodeTester.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -854,6 +854,15 @@ class MyReaderListener : public ReaderListener
};
//!--

void rtps_setup_transports_example()
{
//RTPS_SETUP_TRANSPORTS_EXAMPLE
RTPSParticipantAttributes participant_attr;
participant_attr.setup_transports(eprosima::fastdds::rtps::BuiltinTransports::LARGE_DATA);
RTPSParticipant* participant = RTPSDomain::createParticipant(0, participant_attr);
//!--
}

void rtps_api_example_create_entities()
{
//RTPS_API_CREATE_PARTICIPANT
Expand Down Expand Up @@ -942,7 +951,7 @@ void rtps_api_example_create_entities_with_custom_pool()

// Copy the data
memcpy(payload, data.data, data.length);

// Tell the CacheChange who needs to release its payload
cache_change.payload_owner(this);

Expand Down
21 changes: 21 additions & 0 deletions code/DDSCodeTester.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4622,6 +4622,13 @@ void dds_transport_examples ()
//!--
}

{
//CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
eprosima::fastdds::dds::DomainParticipantQos qos;
qos.setup_transports(eprosima::fastdds::rtps::BuiltinTransports::LARGE_DATA);
//!--
}

{
//CONF-TCP-TRANSPORT-SETTING-SERVER
eprosima::fastdds::dds::DomainParticipantQos qos;
Expand Down Expand Up @@ -6041,6 +6048,20 @@ void dds_waitset_example()

void tcp_use_cases()
{
{
//LARGE_DATA_BUILTIN_TRANSPORTS
eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;

/* Transports configuration */
// UDPv4 transport for PDP over multicast and SHM / TCPv4 transport for EDP and application data
pqos.setup_transports(eprosima::fastdds::rtps::BuiltinTransports::LARGE_DATA);

/* Create participant as usual */
eprosima::fastdds::dds::DomainParticipant* participant =
eprosima::fastdds::dds::DomainParticipantFactory::get_instance()->create_participant(0, pqos);
//!
}

{
//PDP-MULTICAST-DATA-TCP
eprosima::fastdds::dds::DomainParticipantQos pqos = PARTICIPANT_QOS_DEFAULT;
Expand Down
22 changes: 22 additions & 0 deletions code/XMLTester.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1143,6 +1143,8 @@

<useBuiltinTransports>false</useBuiltinTransports>

<builtinTransports>DEFAULT</builtinTransports>

<propertiesPolicy>
<!-- PROPERTIES_POLICY -->
<properties>
Expand Down Expand Up @@ -3701,6 +3703,26 @@
-->
<!--><-->

<!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
<dds xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
<profiles>
-->
<!--
UDP transport for PDP and TCP transport for both EDP and application data
-->
<participant profile_name="large_data_builtin_transports" is_default_profile="true">
<rtps>
<builtinTransports>LARGE_DATA</builtinTransports>
</rtps>
</participant>
<!--
</profiles>
</dds>
-->
<!--><-->

<!-->PDP-MULTICAST-DATA-TCP<-->
<!--
<?xml version="1.0" encoding="UTF-8" ?>
Expand Down
2 changes: 2 additions & 0 deletions code/XMLTesterExample.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -399,6 +399,8 @@

<useBuiltinTransports>false</useBuiltinTransports>

<builtinTransports>DEFAULT</builtinTransports>

<propertiesPolicy>
<properties>
<property>
Expand Down
1 change: 1 addition & 0 deletions docs/03-exports/aliases-api.include
View file
Original file line number Diff line number Diff line change
Expand Up @@ -189,6 +189,7 @@
.. |DomainParticipantQos::timed_events_thread-api| replace:: :cpp:func:`timed_events_thread()<eprosima::fastdds::dds::DomainParticipantQos::timed_events_thread>`
.. |DomainParticipantQos::discovery_server_thread-api| replace:: :cpp:func:`discovery_server_thread()<eprosima::fastdds::dds::DomainParticipantQos::discovery_server_thread>`
.. |DomainParticipantQos::security_log_thread-api| replace:: :cpp:func:`security_log_thread()<eprosima::fastdds::dds::DomainParticipantQos::security_log_thread>`
.. |DomainParticipantQoS::setup_transports-api| replace:: :cpp:func:`setup_transports()<eprosima::fastdds::dds::DomainParticipantQos::setup_transports>`
.. |DomainParticipants-api| replace:: :cpp:class:`DomainParticipants <eprosima::fastdds::dds::DomainParticipant>`

.. |FlowControllerDescriptor-api| replace:: :cpp:class:`FlowControllerDescriptor<eprosima::fastdds::rtps::FlowControllerDescriptor>`
Expand Down
5 changes: 5 additions & 0 deletions docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1042,6 +1042,11 @@ XML
:start-after: <!-->CONF-COMMON-TRANSPORT-SETTING<-->
:end-before: <!--><-->

.. note::
:ref:`transportconfigqos` can also be configured modifying the builtin
transports configuration by selecting one of the available builtin transports options.
See :ref:`rtps_layer_builtin_transports` or |DomainParticipantQoS::setup_transports-api|.

.. _typeconsistencyqos:

TypeConsistencyQos
Expand Down
3 changes: 2 additions & 1 deletion docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,8 @@ Internally it contains the following |QosPolicy-api| objects:
- |DomainParticipantQos::wire_protocol-api|
- No*
* - |TransportConfigQos|
- |DomainParticipantQos::transport-api|
- |DomainParticipantQos::transport-api| and
|DomainParticipantQos::setup_transports-api|
- No
* - |FlowControllersQos|
- |DomainParticipantQos::flow_controllers-api|
Expand Down
53 changes: 53 additions & 0 deletions docs/fastdds/env_vars/env_vars.rst
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
.. include:: ../../03-exports/aliases.include
.. include:: ../../03-exports/aliases-api.include
.. include:: ../../03-exports/roles.include

.. _env_vars:

Expand Down Expand Up @@ -55,6 +56,58 @@ For more information about XML profiles, please refer to :ref:`xml_profiles`.
| set SKIP_DEFAULT_XML=1 |
+------------------------------------------------------------------+

.. _env_vars_builtin_transports:

``FASTDDS_BUILTIN_TRANSPORTS``
----------------------------------

Setting this variable allows to modify the builtin transports that are initialized during the |DomainParticipant|
creation. It is a simple way of changing the default configuration of the :ref:`comm-transports-configuration`
and it directly affects how DDS entities communicate between them.

All existing values, along with a brief description, are shown below:

+----------------------------+------------------------------------------------------------------------------+
| Builtin Transports Options | Description |
+============================+==============================================================================+
| ``NONE`` | No transport will be instantiated. Hence, the user must manually add |
| | the desired |br| transports. Otherwise, the participant creation will fail. |
+----------------------------+------------------------------------------------------------------------------+
| ``DEFAULT`` | UDPv4 and SHM transports will be instantiated. SHM transport has priority |
| | over the UDPv4 |br| transport. Meaning that SHM will always be used |
| | when possible. |
+----------------------------+------------------------------------------------------------------------------+
| ``DEFAULTv6`` | UDPv6 and SHM transports will be instantiated. SHM transport has priority |
| | over the UDPv4 |br| transport. Meaning that SHM will always be used |
| | when possible. |
+----------------------------+------------------------------------------------------------------------------+
| ``SHM`` | Only a SHM transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``UDPv4`` | Only a UDPv4 transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``UDPv6`` | Only a UDPv6 transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``LARGE_DATA`` | UDPv4, TCPv4, and SHM transports will be instantiated. However, UDP will |
| | only be used |br| for multicast announcements during the participant |
| | discovery phase (see :ref:`disc_phases`) |br| while the participant |
| | liveliness and the application data delivery occurs over TCP or SHM. |br| |
| | This configuration is useful when working with large data.(See |
| | :ref:`use-case-tcp`). |
+----------------------------+------------------------------------------------------------------------------+

.. note::
The environment variable is only used in the case where |TransportConfigQos::use_builtin_transports-api| is set
to ``TRUE``. In any other case, the environment variable has no effect.

.. 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.
* |TCPTransportDescriptor::keep_alive_thread-api| and
|TCPTransportDescriptor::accept_thread-api| use the default configuration.

.. _env_vars_ros_discovery_server:

``ROS_DISCOVERY_SERVER``
Expand Down
62 changes: 62 additions & 0 deletions docs/fastdds/rtps_layer/rtps_layer.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.. include:: ../../03-exports/aliases-api.include
.. include:: ../../03-exports/roles.include

.. _RTPS standard: https://www.omg.org/spec/DDSI-RTPS/2.2

Expand Down Expand Up @@ -125,6 +126,67 @@ as we did in the :ref:`dds_layer`:
:start-after: //RTPS_API_READER_LISTENER
:end-before: //!--

.. _rtps_layer_builtin_transports:

Managing the Builtin Transports
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

DDS uses the :ref:`comm-transports-configuration` to allow communication between DDS entities. *eProsima Fast DDS* comes
with five transports already implemented. However, these transports are not always exclusive between them
and in some cases they can be used simultaneously.

You can choose what transports you want to use by disabling the use of builtin transports and manually
adding them (see :ref:`transportconfigqos`) or using the default builtin transports behavior and selecting
one of the configuration options listed below. Each option modifies the kind of transports that will be
instantiated.

+----------------------------+------------------------------------------------------------------------------+
| Builtin Transports Options | Description |
+============================+==============================================================================+
| ``NONE`` | No transport will be instantiated. Hence, the user must manually add |
| | the desired |br| transports. Otherwise, the participant creation will fail. |
+----------------------------+------------------------------------------------------------------------------+
| ``DEFAULT`` | UDPv4 and SHM transports will be instantiated. SHM transport has priority |
| | over the UDPv4 |br| transport. Meaning that SHM will always be used |
| | when possible. |
+----------------------------+------------------------------------------------------------------------------+
| ``DEFAULTv6`` | UDPv6 and SHM transports will be instantiated. SHM transport has priority |
| | over the UDPv4 |br| transport. Meaning that SHM will always be used |
| | when possible. |
+----------------------------+------------------------------------------------------------------------------+
| ``SHM`` | Only a SHM transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``UDPv4`` | Only a UDPv4 transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``UDPv6`` | Only a UDPv6 transport will be instantiated. |
+----------------------------+------------------------------------------------------------------------------+
| ``LARGE_DATA`` | UDPv4, TCPv4, and SHM transports will be instantiated. However, UDP will |
| | only be used |br| for multicast announcements during the participant |
| | discovery phase (see :ref:`disc_phases`) |br| while the participant |
| | liveliness and the application data delivery occurs over TCP or SHM. |br| |
| | This configuration is useful when working with large data.(See |
| | :ref:`use-case-tcp`). |
+----------------------------+------------------------------------------------------------------------------+

.. literalinclude:: ../../../code/CodeTester.cpp
:language: c++
:start-after: //RTPS_SETUP_TRANSPORTS_EXAMPLE
:end-before: //!--
:dedent: 4

The same result can also be obtained using the |DomainParticipantQoS::setup_transports-api| wrapper
function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`RTPS`) or the
``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.
* |TCPTransportDescriptor::keep_alive_thread-api| and
|TCPTransportDescriptor::accept_thread-api| use the default configuration.

Configuring Readers and Writers
-------------------------------
One of the benefits of using the :ref:`rtps_layer` is that it provides new configuration possibilities while
Expand Down
46 changes: 45 additions & 1 deletion docs/fastdds/transport/tcp/tcp.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -180,7 +180,51 @@ TCPv6TransportDescriptor
Enabling TCP Transport
----------------------

To enable TCP transport in a DomainParticipant, you need to
There are several ways of enabling TCP transport in *eprosima Fast DDS*. According to the facet of each
scenario, one method might suit better than the others.

Configuration of Builtin Transports
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The first option is to modify the builtin transports that are responsible of the creation of the DomainParticipant
transports. The existing configuration that enables TCP transports is ``LARGE_DATA``.
This option instantiates a UDPv4, a TCPv4 and a SHM transport, respectively. UDP protocol will be used for multicast
announcements during the participant discovery phase (see :ref:`disc_phases`) while the participant liveliness and
the application data delivery occurs over TCP or SHM. This configuration enables auto discovery and does not
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`).

.. tabs::

.. tab:: C++

.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:start-after: //CONF-TCP-TRANSPORT-BUILTIN-TRANSPORT
:end-before: //!--
:dedent: 8

.. tab:: XML

.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
:end-before: <!--><-->
:lines: 2-4, 6-13, 15-16

.. 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
if a TCP communication is required when SHM is feasible. (See :ref:`use-case-tcp-multicast`).


Server-Client Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To set up a Server-Client configuration you need to
create an instance of :ref:`transport_tcp_v4transportDescriptor` (for TCPv4) or
:ref:`transport_tcp_v6transportDescriptor` (for TCPv6), and add it to the user transport list of the
DomainParticipant.
Expand Down
31 changes: 27 additions & 4 deletions docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,37 @@

.. _use-case-tcp-multicast:

TCP Communication with Multicast Discovery
==========================================
TCP / SHM Communication with Multicast Discovery
================================================

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.
With this approach, applications managing large samples can benefit from transmitting their data over TCP, while
at the same time have the flexibility of automatic discovery.
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.

.. tabs::

.. tab:: C++

.. literalinclude:: ../../../../code/DDSCodeTester.cpp
:language: c++
:dedent: 8
:start-after: //LARGE_DATA_BUILTIN_TRANSPORTS
:end-before: //!

.. tab:: XML

.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->LARGE_DATA_BUILTIN_TRANSPORTS<-->
:end-before: <!--><-->
:lines: 2-4, 6-13, 15-16

.. 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::

Expand Down
8 changes: 7 additions & 1 deletion docs/fastdds/xml_configuration/domainparticipant.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,12 @@ These elements allow the user to define the DomainParticipant configuration.
in addition to its ``<userTransports>``.
- ``bool``
- true
* - ``<builtinTransports>``
- Configuration option to determine which transports |br|
will be instantiated if the ``useBuiltinTransports`` is |br|
set to true. See :ref:`rtps_layer_builtin_transports`.
- ``string_255``
- DEFAULT
* - ``<propertiesPolicy>``
- Additional configuration properties. |br|
See :ref:`propertypolicyqos`.
Expand Down Expand Up @@ -204,7 +210,7 @@ These elements allow the user to define the DomainParticipant configuration.
:language: xml
:start-after: <!-->XML-PARTICIPANT<-->
:end-before: <!--><-->
:lines: 2-4, 6-124, 126-127
:lines: 2-4, 6-126, 128-129

.. note::

Expand Down

0 comments on commit b3bf26c

Please sign in to comment.