Methods to configure transport scenarios Documentation (#619)

* 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> (cherry picked from commit b3bf26c) # Conflicts: # code/XMLTester.xml # docs/03-exports/aliases-api.include # docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst # docs/fastdds/xml_configuration/domainparticipant.rst
eProsima · Dec 19, 2023 · 1ec7490 · 1ec7490
1 parent f78a0f5
commit 1ec7490
Show file tree

Hide file tree

Showing 12 changed files with 322 additions and 6 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
@@ -4564,6 +4564,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;
@@ -5945,6 +5952,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
@@ -928,10 +928,25 @@
 
             <participantID>99</participantID>
 
+<<<<<<< HEAD
             <userTransports>
                 <transport_id>TransportId1</transport_id>
                 <transport_id>TransportId2</transport_id>
             </userTransports>
+=======
+                <builtinTransports>DEFAULT</builtinTransports>
+
+                <propertiesPolicy>
+                    <!-- PROPERTIES_POLICY -->
+                    <properties>
+                        <property>
+                            <name>Property1Name</name>
+                            <value>Property1Value</value>
+                            <propagate>false</propagate>
+                        </property>
+                    </properties>
+                </propertiesPolicy>
+>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619))
 
             <useBuiltinTransports>false</useBuiltinTransports>
 
@@ -3432,6 +3447,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
@@ -331,6 +331,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
@@ -181,6 +181,14 @@
 .. |DomainParticipantQos::transport-api| replace:: :cpp:func:`transport()<eprosima::fastdds::dds::DomainParticipantQos::transport>`
 .. |DomainParticipantQos::user_data-api| replace:: :cpp:func:`user_data()<eprosima::fastdds::dds::DomainParticipantQos::user_data>`
 .. |DomainParticipantQos::wire_protocol-api| replace:: :cpp:func:`wire_protocol()<eprosima::fastdds::dds::DomainParticipantQos::wire_protocol>`
+<<<<<<< HEAD
+=======
+.. |DomainParticipantQos::builtin_controllers_sender_thread-api| replace:: :cpp:func:`builtin_controllers_sender_thread()<eprosima::fastdds::dds::DomainParticipantQos::builtin_controllers_sender_thread>`
+.. |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>`
+>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619))
 .. |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
@@ -942,6 +942,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
@@ -29,6 +29,7 @@ DomainParticipantQos
 |DomainParticipantQos-api| controls the behavior of the DomainParticipant.
 Internally it contains the following |QosPolicy-api| objects:
 
+<<<<<<< HEAD
 +--------------------------------+----------------------------------------------+----------+
 | QosPolicy class                | Accessor/Mutator                             | Mutable  |
 +================================+==============================================+==========+
@@ -46,6 +47,49 @@ Internally it contains the following |QosPolicy-api| objects:
 +--------------------------------+----------------------------------------------+----------+
 | |FlowControllersQos|           | |DomainParticipantQos::flow_controllers-api| | No       |
 +--------------------------------+----------------------------------------------+----------+
+=======
+
+.. list-table::
+   :header-rows: 1
+
+   * - QosPolicy class
+     - Accessor/Mutator
+     - Mutable
+   * - |UserDataQosPolicy|
+     - |DomainParticipantQos::user_data-api|
+     - Yes
+   * - |EntityFactoryQosPolicy|
+     - |DomainParticipantQos::entity_factory-api|
+     - Yes
+   * - |ParticipantResourceLimitsQos|
+     - |DomainParticipantQos::allocation-api|
+     - No
+   * - |PropertyPolicyQos|
+     - |DomainParticipantQos::properties-api|
+     - No
+   * - |WireProtocolConfigQos|
+     - |DomainParticipantQos::wire_protocol-api|
+     - No*
+   * - |TransportConfigQos|
+     - |DomainParticipantQos::transport-api| and
+       |DomainParticipantQos::setup_transports-api|
+     - No
+   * - |FlowControllersQos|
+     - |DomainParticipantQos::flow_controllers-api|
+     - No
+   * - |ThreadSettings|
+     - |DomainParticipantQos::builtin_controllers_sender_thread-api|
+     - No
+   * - |ThreadSettings|
+     - |DomainParticipantQos::timed_events_thread-api|
+     - No
+   * - |ThreadSettings|
+     - |DomainParticipantQos::discovery_server_thread-api|
+     - No
+   * - |ThreadSettings|
+     - |DomainParticipantQos::security_log_thread-api|
+     - No
+>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619))
 
 .. Important::
     The only mutable field in |WireProtocolConfigQos| is |m_DiscoveryServers|, which is contained in

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
@@ -163,7 +163,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.