diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index 60fd8567a..1800f6480 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 diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index f2d60191d..fa2b48ae8 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -4527,6 +4527,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; @@ -5885,6 +5892,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 94941388e..8f39ed712 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -3409,6 +3409,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 1706bcd91..de2b309ac 100644 --- a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst +++ b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst @@ -29,23 +29,34 @@ DomainParticipantQos |DomainParticipantQos-api| controls the behavior of the DomainParticipant. Internally it contains the following |QosPolicy-api| objects: -+--------------------------------+----------------------------------------------+----------+ -| 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 + + * - 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 .. 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 21ba86554..48567dee5 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,56 @@ 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. + .. _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 619a61f69..ac1864b23 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,65 @@ 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. + 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 8deedfd89..78d01c952 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 4dd36b572..d813f7ac2 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`.