From 96c68ec9a600a83107f5bd7e3759d8f6255850bf 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 1/3] 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 (cherry picked from commit b3bf26c08e9f4afff813a6976e1a829d7b6e9f65) # Conflicts: # code/CodeTester.cpp # code/XMLTester.xml # code/XMLTesterExample.xml # docs/03-exports/aliases-api.include # docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst # docs/fastdds/xml_configuration/domainparticipant.rst Signed-off-by: EduPonz --- code/CodeTester.cpp | 15 + code/DDSCodeTester.cpp | 21 + code/XMLTester.xml | 463 ++++++++++++++++++ code/XMLTesterExample.xml | 39 ++ docs/03-exports/aliases-api.include | 8 + .../core/policy/eprosimaExtensions.rst | 5 + .../domainParticipant/domainParticipant.rst | 44 ++ 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 | 142 ++++++ 12 files changed, 924 insertions(+), 5 deletions(-) diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index 19da69a3d..1c3cb6690 100644 --- a/code/CodeTester.cpp +++ b/code/CodeTester.cpp @@ -868,6 +868,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 @@ -956,6 +965,12 @@ void rtps_api_example_create_entities_with_custom_pool() // Copy the data memcpy(payload, data.data, data.length); +<<<<<<< HEAD +======= + + // Tell the CacheChange who needs to release its payload + cache_change.payload_owner(this); +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) // Assign the payload buffer to the CacheChange and update sizes cache_change.serializedPayload.data = payload; diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 42138d8e3..0c4cd34ef 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -4426,6 +4426,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 DomainParticipantQos qos; @@ -5637,6 +5644,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 fb8c17172..d31210384 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -1387,7 +1387,22 @@ TransportId2 +<<<<<<< HEAD false +======= + DEFAULT + + + + + + Property1Name + Property1Value + false + + + +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) @@ -4596,3 +4611,451 @@ <--> +<<<<<<< HEAD +======= + + +CONF-SERVER-CLIENT-PREFIX<--> + + + + + + + + + + + +
192.168.10.57
+ 56542 + + + + + + + + + + +<--> + +LARGE_DATA_BUILTIN_TRANSPORTS<--> + + + + + LARGE_DATA + + + +<--> + +PDP-MULTICAST-DATA-TCP<--> + + + + + pdp_transport + UDPv4 + + + + data_transport + TCPv4 + + + 0 + + + + + + + + + pdp_transport + data_transport + + false + + + + + + +
239.255.0.1
+ + + + + + + +
0.0.0.0
+ 12345 + 12345 + + + + + + + + +
0.0.0.0
+ 12345 + 12345 + + + + + + +<--> + +TCP-AND-DISCOVERY-SERVER-SERVER<--> + + + + server_tcp_transport + TCPv4 + + + 12345 + + + + + + + + SERVER + + + + +
192.168.10.57
+ 12345 + 12345 + + + + + 44.53.00.5f.45.50.52.4f.53.49.4d.41 + false + + server_tcp_transport + + + + +<--> + +TCP-AND-DISCOVERY-SERVER-CLIENT<--> + + + + client_tcp_transport + TCPv4 + + + 0 + + + + + + + + CLIENT + + + + + + +
192.168.10.57
+ 12345 + 12345 + + + + + + + + false + + client_tcp_transport + + + + +<--> + + + +CONF-LIBRARY-SETTINGS<--> + + FULL + +<--> + +LOG-CONFIG<--> + + + + false + + + + StdoutConsumer + + + + + StdoutErrConsumer + + stderr_threshold + Log::Kind::Error + + + + + + FileConsumer + + filename + execution.log + + + append + true + + + + + + -1 + 0 + 0 + -1 + + + +<--> + + + +XML-DYN-ENUM<--> + + + + + +<--> + +XML-TYPEDEF<--> + + + + + + + + + + + + +<--> + +XML-STRUCT<--> + + + + +<--> + +XML-UNION<--> + + + + + + + + + + + + + + + + +<--> + +XML-GENERIC<--> + + + + + + + + + + + + + + + + + + + + +<--> + +XML-BOUNDEDSTRINGS<--> + + +<--> +XML-SEQUENCES<--> + +<--> +XML-ARRAYS<--> + +<--> +XML-MAPS<--> + +<--> + + +XML-COMPLEX<--> + + + +<--> + +XML-BITSET<--> + + + + + + + +<--> +XML-BITMASK<--> + + + + + + +<--> +XML-BITSET-INHERIT<--> + + + + + + + + + +<--> +XML-STRUCT-INHERIT<--> + + + + + + + + +<--> + + + +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml index d975bebb0..2568f889d 100644 --- a/code/XMLTesterExample.xml +++ b/code/XMLTesterExample.xml @@ -212,6 +212,45 @@ PREALLOCATED +<<<<<<< HEAD +======= + + 7400 + 200 + 10 + 0 + 1 + 2 + 3 + + + 99 + + + ExampleTransportId1 + ExampleTransportId2 + + + false + + DEFAULT + + + + + Property1Name + Property1Value + false + + + Property2Name + Property2Value + false + + + + +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) 4 diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include index 1bdfc691c..9c29c501d 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -171,6 +171,14 @@ .. |DomainParticipantQos::transport-api| replace:: :cpp:func:`transport()` .. |DomainParticipantQos::user_data-api| replace:: :cpp:func:`user_data()` .. |DomainParticipantQos::wire_protocol-api| replace:: :cpp:func:`wire_protocol()` +<<<<<<< HEAD +======= +.. |DomainParticipantQos::builtin_controllers_sender_thread-api| replace:: :cpp:func:`builtin_controllers_sender_thread()` +.. |DomainParticipantQos::timed_events_thread-api| replace:: :cpp:func:`timed_events_thread()` +.. |DomainParticipantQos::discovery_server_thread-api| replace:: :cpp:func:`discovery_server_thread()` +.. |DomainParticipantQos::security_log_thread-api| replace:: :cpp:func:`security_log_thread()` +.. |DomainParticipantQoS::setup_transports-api| replace:: :cpp:func:`setup_transports()` +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) .. |DomainParticipants-api| replace:: :cpp:class:`DomainParticipants ` .. |FlowControllerDescriptor-api| replace:: :cpp:class:`FlowControllerDescriptor` diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst index b6bd6d41f..789e742bc 100644 --- a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst +++ b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst @@ -919,6 +919,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 index 56926998a..bc0895900 100644 --- 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 index 2cd45cd7a..a21135974 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 3df0d5380..cb29d96b5 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 4de62b1dd..cf62063d7 100644 --- 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. 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 7edac494c..511d9406d 100644 --- a/docs/fastdds/xml_configuration/domainparticipant.rst +++ b/docs/fastdds/xml_configuration/domainparticipant.rst @@ -67,6 +67,7 @@ These elements allow the user to define the DomainParticipant configuration. .. |PolicyType| replace:: :ref:`PropertiesPolicyType ` +<<<<<<< HEAD +-----------------------------------+--------------------------------------------------+---------------------+---------+ | Name | Description | Values | Default | +===================================+==================================================+=====================+=========+ @@ -127,6 +128,143 @@ These elements allow the user to define the DomainParticipant configuration. | ```` | Configuration regarding allocation behavior. | |PartAlloc| | | | | |br| It expects a |br| |PartAlloc|. | | | +-----------------------------------+--------------------------------------------------+---------------------+---------+ +======= +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Values + - Default + * - ```` + - The DomainParticipant's name. + - ``string_255`` + - + * - ```` + - List of default reception unicast locators |br| + for user data traffic (see |br| + ```` |br| + defined in :ref:`builtin`). |br| + It expects a :ref:`LocatorListType`. + - ```` + - + * - ```` + - List of default reception multicast |br| + locators for user data traffic (see |br| + ```` |br| + defined in :ref:`builtin`). |br| + It expects a :ref:`LocatorListType`. + - ```` + - + * - ```` + - List of :ref:`external_locators` |br| + to announce for the default user traffic of |br| + this participant. + - :ref:`externalLocatorListType` + - + * - ```` + - Whether to ignore locators received on |br| + announcements from other participants when |br| + they don't match with any of the locators |br| + announced by this participant. + - ``bool`` + - false + * - ```` + - Size in bytes of the send socket buffer. |br| + If the value is zero then *Fast DDS* will |br| + use the system default socket size. + - ``uint32_t`` + - 0 + * - ```` + - Size in bytes of the reception socket |br| + buffer. If the value is zero then |br| + *Fast DDS* will use the system default |br| + socket size. + - ``uint32_t`` + - 0 + * - ```` + - |WireProtocolConfigQos::builtin-api| public data member of the |br| + |WireProtocolConfigQos-api| class. |br| + See the :ref:`builtin` section. + - :ref:`builtin` + - + * - ```` + - Allows defining the port and gains related |br| + to the RTPS protocol. See the `Port`_ section. + - `Port`_ + - + * - ```` + - DomainParticipant's identifier. Typically |br| + it will be automatically generated by the |br| + |DomainParticipantFactory|. + - ``int32_t`` + - 0 + * - ```` + - Transport descriptors to be used by the |br| + DomainParticipant. See |br| + :ref:`transportdescriptors`. + - ``List `` + - + * - ```` + - Boolean field to indicate the system |br| + whether the DomainParticipant will use the |br| + default |WireProtocolConfigQos::builtin-api| transports |br| + 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`. + - |PolicyType| + - + * - ```` + - Configuration regarding allocation behavior. |br| + It expects a |br| + |PartAlloc|. + - |PartAlloc| + - + * - ```` + - Additional information attached to the DomainParticipant |br| + and transmitted with the discovery information. |br| + See :ref:`userdataqospolicy`. + - ``List `` + - Empty + * - ```` + - |DomainParticipant|'s |GuidPrefix_t-api| identifies peers |br| + running in the same process. Two participants with identical |br| + 8 first bytes on the |GuidPrefix_t-api| are considered to be |br| + running in the same process, and therefore intra-process |br| + delivery is used. See :ref:`intraprocess-delivery`. + - ``string`` + - Empty + * - ```` + - |ThreadSettings| for the builtin flow controllers sender thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| participant's timed events thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the discovery server thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the builtin transports reception threads. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the security log thread. + - |ThreadSettings| + - +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) **Example** @@ -134,7 +272,11 @@ These elements allow the user to define the DomainParticipant configuration. :language: xml :start-after: XML-PARTICIPANT<--> :end-before: <--> +<<<<<<< HEAD :lines: 2-3, 5-76, 78 +======= + :lines: 2-4, 6-126, 128-129 +>>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) .. note:: From c8a0b6bc7f87c9c596348215b04f291d5b45e0fc Mon Sep 17 00:00:00 2001 From: cferreiragonz Date: Fri, 5 Jan 2024 12:00:09 +0100 Subject: [PATCH 2/3] Fix Conflicts Signed-off-by: cferreiragonz Signed-off-by: EduPonz --- code/CodeTester.cpp | 6 - code/XMLTester.xml | 483 +----------------- code/XMLTesterExample.xml | 41 +- docs/03-exports/aliases-api.include | 7 - .../domainParticipant/domainParticipant.rst | 33 -- .../xml_configuration/domainparticipant.rst | 150 +----- 6 files changed, 29 insertions(+), 691 deletions(-) diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index 1c3cb6690..75ba2ded9 100644 --- a/code/CodeTester.cpp +++ b/code/CodeTester.cpp @@ -965,12 +965,6 @@ void rtps_api_example_create_entities_with_custom_pool() // Copy the data memcpy(payload, data.data, data.length); -<<<<<<< HEAD -======= - - // Tell the CacheChange who needs to release its payload - cache_change.payload_owner(this); ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) // Assign the payload buffer to the CacheChange and update sizes cache_change.serializedPayload.data = payload; diff --git a/code/XMLTester.xml b/code/XMLTester.xml index d31210384..86e365534 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -1387,22 +1387,9 @@ TransportId2 -<<<<<<< HEAD false -======= - DEFAULT - - - - - Property1Name - Property1Value - false - - - ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) + DEFAULT @@ -3828,6 +3815,26 @@ --> <--> +LARGE_DATA_BUILTIN_TRANSPORTS<--> + + + + + LARGE_DATA + + + +<--> + PDP-MULTICAST-DATA-TCP<--> <--> -<<<<<<< HEAD -======= - - -CONF-SERVER-CLIENT-PREFIX<--> - - - - - - - - - - - -
192.168.10.57
- 56542 - - - - - - - - - - -<--> - -LARGE_DATA_BUILTIN_TRANSPORTS<--> - - - - - LARGE_DATA - - - -<--> - -PDP-MULTICAST-DATA-TCP<--> - - - - - pdp_transport - UDPv4 - - - - data_transport - TCPv4 - - - 0 - - - - - - - - - pdp_transport - data_transport - - false - - - - - - -
239.255.0.1
- - - - - - - -
0.0.0.0
- 12345 - 12345 - - - - - - - - -
0.0.0.0
- 12345 - 12345 - - - - - - -<--> - -TCP-AND-DISCOVERY-SERVER-SERVER<--> - - - - server_tcp_transport - TCPv4 - - - 12345 - - - - - - - - SERVER - - - - -
192.168.10.57
- 12345 - 12345 - - - - - 44.53.00.5f.45.50.52.4f.53.49.4d.41 - false - - server_tcp_transport - - - - -<--> - -TCP-AND-DISCOVERY-SERVER-CLIENT<--> - - - - client_tcp_transport - TCPv4 - - - 0 - - - - - - - - CLIENT - - - - - - -
192.168.10.57
- 12345 - 12345 - - - - - - - - false - - client_tcp_transport - - - - -<--> - - - -CONF-LIBRARY-SETTINGS<--> - - FULL - -<--> - -LOG-CONFIG<--> - - - - false - - - - StdoutConsumer - - - - - StdoutErrConsumer - - stderr_threshold - Log::Kind::Error - - - - - - FileConsumer - - filename - execution.log - - - append - true - - - - - - -1 - 0 - 0 - -1 - - - -<--> - - - -XML-DYN-ENUM<--> - - - - - -<--> - -XML-TYPEDEF<--> - - - - - - - - - - - - -<--> - -XML-STRUCT<--> - - - - -<--> - -XML-UNION<--> - - - - - - - - - - - - - - - - -<--> - -XML-GENERIC<--> - - - - - - - - - - - - - - - - - - - - -<--> - -XML-BOUNDEDSTRINGS<--> - - -<--> -XML-SEQUENCES<--> - -<--> -XML-ARRAYS<--> - -<--> -XML-MAPS<--> - -<--> - - -XML-COMPLEX<--> - - - -<--> - -XML-BITSET<--> - - - - - - - -<--> -XML-BITMASK<--> - - - - - - -<--> -XML-BITSET-INHERIT<--> - - - - - - - - - -<--> -XML-STRUCT-INHERIT<--> - - - - - - - - -<--> - - - ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) diff --git a/code/XMLTesterExample.xml b/code/XMLTesterExample.xml index 2568f889d..330bf72ce 100644 --- a/code/XMLTesterExample.xml +++ b/code/XMLTesterExample.xml @@ -212,45 +212,6 @@ PREALLOCATED -<<<<<<< HEAD -======= - - 7400 - 200 - 10 - 0 - 1 - 2 - 3 - - - 99 - - - ExampleTransportId1 - ExampleTransportId2 - - - false - - DEFAULT - - - - - Property1Name - Property1Value - false - - - Property2Name - Property2Value - false - - - - ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) 4 @@ -300,6 +261,8 @@ false + DEFAULT + diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include index 9c29c501d..abf828bd4 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -171,14 +171,7 @@ .. |DomainParticipantQos::transport-api| replace:: :cpp:func:`transport()` .. |DomainParticipantQos::user_data-api| replace:: :cpp:func:`user_data()` .. |DomainParticipantQos::wire_protocol-api| replace:: :cpp:func:`wire_protocol()` -<<<<<<< HEAD -======= -.. |DomainParticipantQos::builtin_controllers_sender_thread-api| replace:: :cpp:func:`builtin_controllers_sender_thread()` -.. |DomainParticipantQos::timed_events_thread-api| replace:: :cpp:func:`timed_events_thread()` -.. |DomainParticipantQos::discovery_server_thread-api| replace:: :cpp:func:`discovery_server_thread()` -.. |DomainParticipantQos::security_log_thread-api| replace:: :cpp:func:`security_log_thread()` .. |DomainParticipantQoS::setup_transports-api| replace:: :cpp:func:`setup_transports()` ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) .. |DomainParticipants-api| replace:: :cpp:class:`DomainParticipants ` .. |FlowControllerDescriptor-api| replace:: :cpp:class:`FlowControllerDescriptor` diff --git a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst index bc0895900..fc179dacc 100644 --- a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst +++ b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst @@ -29,26 +29,6 @@ DomainParticipantQos |DomainParticipantQos-api| controls the behavior of the DomainParticipant. Internally it contains the following |QosPolicy-api| objects: -<<<<<<< HEAD -+--------------------------------+----------------------------------------------+----------+ -| 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| | No | -+--------------------------------+----------------------------------------------+----------+ -| |FlowControllersQos| | |DomainParticipantQos::flow_controllers-api| | No | -+--------------------------------+----------------------------------------------+----------+ -======= - .. list-table:: :header-rows: 1 @@ -77,19 +57,6 @@ Internally it contains the following |QosPolicy-api| objects: * - |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/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst index 511d9406d..8fbc8d293 100644 --- a/docs/fastdds/xml_configuration/domainparticipant.rst +++ b/docs/fastdds/xml_configuration/domainparticipant.rst @@ -66,8 +66,6 @@ These elements allow the user to define the DomainParticipant configuration. .. |PartAlloc| replace:: :ref:`DomainParticipantAllocationType ` .. |PolicyType| replace:: :ref:`PropertiesPolicyType ` - -<<<<<<< HEAD +-----------------------------------+--------------------------------------------------+---------------------+---------+ | Name | Description | Values | Default | +===================================+==================================================+=====================+=========+ @@ -122,149 +120,17 @@ These elements allow the user to define the DomainParticipant configuration. | | transport instead |br| | | | | | of its ````. | | | +-----------------------------------+--------------------------------------------------+---------------------+---------+ +| ```` | Configuration option to determine which |br| | ``string_255`` | DEFAULT | +| | transports will be instantiated if the |br| | | | +| | ``useBuiltinTransports`` is set to true. |br| | | | +| | See :ref:`rtps_layer_builtin_transports`. |br| | | | ++-----------------------------------+--------------------------------------------------+---------------------+---------+ | ```` | Additional configuration properties. |br| | |PolicyType| | | | | It expects a |PolicyType|. | | | +-----------------------------------+--------------------------------------------------+---------------------+---------+ | ```` | Configuration regarding allocation behavior. | |PartAlloc| | | | | |br| It expects a |br| |PartAlloc|. | | | +-----------------------------------+--------------------------------------------------+---------------------+---------+ -======= -.. list-table:: - :header-rows: 1 - :align: left - - * - Name - - Description - - Values - - Default - * - ```` - - The DomainParticipant's name. - - ``string_255`` - - - * - ```` - - List of default reception unicast locators |br| - for user data traffic (see |br| - ```` |br| - defined in :ref:`builtin`). |br| - It expects a :ref:`LocatorListType`. - - ```` - - - * - ```` - - List of default reception multicast |br| - locators for user data traffic (see |br| - ```` |br| - defined in :ref:`builtin`). |br| - It expects a :ref:`LocatorListType`. - - ```` - - - * - ```` - - List of :ref:`external_locators` |br| - to announce for the default user traffic of |br| - this participant. - - :ref:`externalLocatorListType` - - - * - ```` - - Whether to ignore locators received on |br| - announcements from other participants when |br| - they don't match with any of the locators |br| - announced by this participant. - - ``bool`` - - false - * - ```` - - Size in bytes of the send socket buffer. |br| - If the value is zero then *Fast DDS* will |br| - use the system default socket size. - - ``uint32_t`` - - 0 - * - ```` - - Size in bytes of the reception socket |br| - buffer. If the value is zero then |br| - *Fast DDS* will use the system default |br| - socket size. - - ``uint32_t`` - - 0 - * - ```` - - |WireProtocolConfigQos::builtin-api| public data member of the |br| - |WireProtocolConfigQos-api| class. |br| - See the :ref:`builtin` section. - - :ref:`builtin` - - - * - ```` - - Allows defining the port and gains related |br| - to the RTPS protocol. See the `Port`_ section. - - `Port`_ - - - * - ```` - - DomainParticipant's identifier. Typically |br| - it will be automatically generated by the |br| - |DomainParticipantFactory|. - - ``int32_t`` - - 0 - * - ```` - - Transport descriptors to be used by the |br| - DomainParticipant. See |br| - :ref:`transportdescriptors`. - - ``List `` - - - * - ```` - - Boolean field to indicate the system |br| - whether the DomainParticipant will use the |br| - default |WireProtocolConfigQos::builtin-api| transports |br| - 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`. - - |PolicyType| - - - * - ```` - - Configuration regarding allocation behavior. |br| - It expects a |br| - |PartAlloc|. - - |PartAlloc| - - - * - ```` - - Additional information attached to the DomainParticipant |br| - and transmitted with the discovery information. |br| - See :ref:`userdataqospolicy`. - - ``List `` - - Empty - * - ```` - - |DomainParticipant|'s |GuidPrefix_t-api| identifies peers |br| - running in the same process. Two participants with identical |br| - 8 first bytes on the |GuidPrefix_t-api| are considered to be |br| - running in the same process, and therefore intra-process |br| - delivery is used. See :ref:`intraprocess-delivery`. - - ``string`` - - Empty - * - ```` - - |ThreadSettings| for the builtin flow controllers sender thread. - - |ThreadSettings| - - - * - ```` - - |ThreadSettings| participant's timed events thread. - - |ThreadSettings| - - - * - ```` - - |ThreadSettings| for the discovery server thread. - - |ThreadSettings| - - - * - ```` - - |ThreadSettings| for the builtin transports reception threads. - - |ThreadSettings| - - - * - ```` - - |ThreadSettings| for the security log thread. - - |ThreadSettings| - - ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) **Example** @@ -272,11 +138,7 @@ These elements allow the user to define the DomainParticipant configuration. :language: xml :start-after: XML-PARTICIPANT<--> :end-before: <--> -<<<<<<< HEAD - :lines: 2-3, 5-76, 78 -======= - :lines: 2-4, 6-126, 128-129 ->>>>>>> b3bf26c (Methods to configure transport scenarios Documentation (#619)) + :lines: 2-3, 5-78, 80 .. note:: From a98d99635b72dc159b2429f33ae958aad6ac315b Mon Sep 17 00:00:00 2001 From: EduPonz Date: Tue, 16 Jan 2024 11:59:56 +0100 Subject: [PATCH 3/3] Remove reference to unexisting APIs Signed-off-by: EduPonz --- docs/fastdds/env_vars/env_vars.rst | 2 -- docs/fastdds/rtps_layer/rtps_layer.rst | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/fastdds/env_vars/env_vars.rst b/docs/fastdds/env_vars/env_vars.rst index a21135974..1f68d0e18 100644 --- a/docs/fastdds/env_vars/env_vars.rst +++ b/docs/fastdds/env_vars/env_vars.rst @@ -105,8 +105,6 @@ All existing values, along with a brief description, are shown below: * |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: diff --git a/docs/fastdds/rtps_layer/rtps_layer.rst b/docs/fastdds/rtps_layer/rtps_layer.rst index cb29d96b5..334efff45 100644 --- a/docs/fastdds/rtps_layer/rtps_layer.rst +++ b/docs/fastdds/rtps_layer/rtps_layer.rst @@ -184,8 +184,6 @@ function of the :ref:`dds_layer_domainParticipantQos`, XML profiles (see :ref:`R * |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 -------------------------------