Methods to configure transport scenarios Documentation (#619)

* Refs #20021: New TCP w/ Disc.Server example Signed-off-by: cferreiragonz <[email protected]> * Refs #20021: fix XML example Signed-off-by: cferreiragonz <[email protected]> * Refs #20021: Correct tests Signed-off-by: cferreiragonz <[email protected]> * Refs #20021: Apply Revision's changes Signed-off-by: cferreiragonz <[email protected]> * Refs #20021: Update use case and CLI Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add RTPS Attributes docs Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add XML builtin transports docs Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add new function reference Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add new environment variable docs Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add note in TrasnportConfigQos Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add new method of enabling TCP Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Modify UDP+TCP use case Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Minor fixes Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Apply revision's changes and format table Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Fix v6 missing Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Remove v6 from builtin transports table Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Apply revision's changes Signed-off-by: cferreiragonz <[email protected]> * Refs #20020: Add Dedent Signed-off-by: cferreiragonz <[email protected]> --------- Signed-off-by: cferreiragonz <[email protected]>
eProsima · Dec 19, 2023 · b3bf26c · b3bf26c
1 parent e1f4d65
commit b3bf26c
Show file tree

Hide file tree

Showing 12 changed files with 257 additions and 8 deletions.
diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp
@@ -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
@@ -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);
 

diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp
@@ -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;
@@ -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;

diff --git a/code/XMLTester.xml b/code/XMLTester.xml
@@ -1143,6 +1143,8 @@
 
                 <useBuiltinTransports>false</useBuiltinTransports>
 
+                <builtinTransports>DEFAULT</builtinTransports>
+
                 <propertiesPolicy>
                     <!-- PROPERTIES_POLICY -->
                     <properties>
@@ -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" ?>

diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml
@@ -399,6 +399,8 @@
 
                 <useBuiltinTransports>false</useBuiltinTransports>
 
+                <builtinTransports>DEFAULT</builtinTransports>
+
                 <propertiesPolicy>
                     <properties>
                         <property>

diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include
@@ -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>`

diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst
@@ -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

diff --git a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst
@@ -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|

diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst
@@ -1,5 +1,6 @@
 .. include:: ../../03-exports/aliases.include
 .. include:: ../../03-exports/aliases-api.include
+.. include:: ../../03-exports/roles.include
 
 .. _env_vars:
 
@@ -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``

diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst
@@ -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
 
@@ -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

diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst
@@ -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.

diff --git a/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst b/docs/fastdds/use_cases/tcp/tcp_with_multicast_discovery.rst
@@ -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::
 

diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst
@@ -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`.
@@ -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::