From b3bf26c08e9f4afff813a6976e1a829d7b6e9f65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20Ferreira=20Gonz=C3=A1lez?= Date: Tue, 19 Dec 2023 16:18:39 +0100 Subject: [PATCH] Methods to configure transport scenarios Documentation (#619) * Refs #20021: New TCP w/ Disc.Server example Signed-off-by: cferreiragonz * Refs #20021: fix XML example Signed-off-by: cferreiragonz * Refs #20021: Correct tests Signed-off-by: cferreiragonz * Refs #20021: Apply Revision's changes Signed-off-by: cferreiragonz * Refs #20021: Update use case and CLI Signed-off-by: cferreiragonz * Refs #20020: Add RTPS Attributes docs Signed-off-by: cferreiragonz * Refs #20020: Add XML builtin transports docs Signed-off-by: cferreiragonz * Refs #20020: Add new function reference Signed-off-by: cferreiragonz * Refs #20020: Add new environment variable docs Signed-off-by: cferreiragonz * Refs #20020: Add note in TrasnportConfigQos Signed-off-by: cferreiragonz * Refs #20020: Add new method of enabling TCP Signed-off-by: cferreiragonz * Refs #20020: Modify UDP+TCP use case Signed-off-by: cferreiragonz * Refs #20020: Minor fixes Signed-off-by: cferreiragonz * Refs #20020: Apply revision's changes and format table Signed-off-by: cferreiragonz * Refs #20020: Fix v6 missing Signed-off-by: cferreiragonz * Refs #20020: Remove v6 from builtin transports table Signed-off-by: cferreiragonz * Refs #20020: Apply revision's changes Signed-off-by: cferreiragonz * Refs #20020: Add Dedent Signed-off-by: cferreiragonz --------- Signed-off-by: cferreiragonz --- code/CodeTester.cpp | 11 +++- code/DDSCodeTester.cpp | 21 +++++++ code/XMLTester.xml | 22 +++++++ code/XMLTesterExample.xml | 2 + docs/03-exports/aliases-api.include | 1 + .../core/policy/eprosimaExtensions.rst | 5 ++ .../domainParticipant/domainParticipant.rst | 3 +- docs/fastdds/env_vars/env_vars.rst | 53 ++++++++++++++++ docs/fastdds/rtps_layer/rtps_layer.rst | 62 +++++++++++++++++++ docs/fastdds/transport/tcp/tcp.rst | 46 +++++++++++++- .../tcp/tcp_with_multicast_discovery.rst | 31 ++++++++-- .../xml_configuration/domainparticipant.rst | 8 ++- 12 files changed, 257 insertions(+), 8 deletions(-) diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index 0fd699e4d..67917655b 100644 --- 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 index 8ae1e0b90..2071f19a6 100644 --- 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 index 804097799..7222c1b3c 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -1143,6 +1143,8 @@ false + DEFAULT + @@ -3701,6 +3703,26 @@ --> <--> +LARGE_DATA_BUILTIN_TRANSPORTS<--> + + + + + LARGE_DATA + + + +<--> + PDP-MULTICAST-DATA-TCP<--> 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 index bbb8673a3..cb4d36df8 100644 --- 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 index 21ba86554..555e33bb6 100644 --- 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 index 143644d1f..99b6744d4 100644 --- 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 index 97e9b60ad..5baa4fbbd 100644 --- 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 index 91e808eaf..7052451f6 100644 --- 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` 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 index 9f14a6856..a6d13b61d 100644 --- 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 ````. - ``bool`` - true + * - ```` + - 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 * - ```` - 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::