Skip to content

Commit 970931c

Browse files
cferreiragonzcferreiragonz
authored
Update TCP keep alive docs (#1187)
* Refs #24015: Update keep alive docs Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com> * Refs #24015: Fix doc8 tests Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com> * Refs #24015: Downgrade title section level Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com> --------- Signed-off-by: Carlos Ferreira González <carlosferreira@eprosima.com>
1 parent 1379cbd commit 970931c

6 files changed

Lines changed: 92 additions & 8 deletions

File tree

‎code/DDSCodeTester.cpp‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6521,6 +6521,23 @@ void dds_transport_examples ()
65216521
//!--
65226522
}
65236523

6524+
{
6525+
//CONF-TCP-KEEP-ALIVE
6526+
DomainParticipantQos qos;
6527+
6528+
// Create a descriptor for the new transport.
6529+
auto tcp_transport = std::make_shared<TCPv4TransportDescriptor>();
6530+
6531+
// Configure keep alive options
6532+
tcp_transport->keep_alive_frequency_ms = 5000; // Send a keep-alive message every 5 seconds when connection is idle
6533+
tcp_transport->keep_alive_timeout_ms = 2000; // Consider connection lost if no response is received within 2 seconds
6534+
tcp_transport->keep_alive_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; // Configure thread settings
6535+
6536+
// Link the Transport Layer to the Participant.
6537+
qos.transport().user_transports.push_back(tcp_transport);
6538+
//!--
6539+
}
6540+
65246541
{
65256542
//TRANSPORT-DESCRIPTORS
65266543
DomainParticipantQos qos;

‎code/XMLTester.xml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,21 @@
796796
</participant>
797797
<!--><-->
798798

799+
<!-->CONF-TCP-KEEP-ALIVE<-->
800+
<!--
801+
<?xml version="1.0" encoding="UTF-8" ?>
802+
<profiles xmlns="http://www.eprosima.com">
803+
-->
804+
<transport_descriptors>
805+
<transport_descriptor>
806+
<transport_id>keep_alive_transport</transport_id>
807+
<type>TCPv4</type>
808+
<keep_alive_frequency_ms>5000</keep_alive_frequency_ms>
809+
<keep_alive_timeout_ms>25000</keep_alive_timeout_ms>
810+
</transport_descriptor>
811+
</transport_descriptors>
812+
<!--><-->
813+
799814
<!-->CONF-DISABLE-MULTICAST<-->
800815
<!--
801816
<?xml version="1.0" encoding="UTF-8" ?>

‎docs/fastdds/transport/tcp/tcp.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,12 +93,12 @@ The following table describes the common data members for both TCPv4 and TCPv6.
9393
- List of ports to listen as *server*. If a port is set to 0, an available port will be automatically assigned.
9494
* - |TCPTransportDescriptor::keep_alive_frequency_ms-api|
9595
- ``uint32_t``
96-
- 5000
97-
- Frequency of RTCP keep alive requests (in ms).
96+
- 0
97+
- |Pro| Frequency of RTCP keep alive requests (in ms).
9898
* - |TCPTransportDescriptor::keep_alive_timeout_ms-api|
9999
- ``uint32_t``
100-
- 15000
101-
- Time since sending the last keep alive request to consider a connection as broken (in ms).
100+
- 0
101+
- |Pro| Time since sending the last keep alive request to consider a connection as broken (in ms).
102102
* - |TCPTransportDescriptor::max_logical_port-api|
103103
- ``uint16_t``
104104
- 100

‎docs/fastdds/use_cases/ip_mobility/ip_mobility.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,49 @@ Please refer to :ref:`dds_layer_domainParticipantQos` for more information about
4848
(please refer to :ref:`remotelocatorsallocationattributes`).
4949
It is recommended to use the highest number of local addresses found on all the systems belonging to the same
5050
domain.
51+
52+
.. _tcp-keep-alive:
53+
54+
TCP Keep Alive |Pro|
55+
--------------------
56+
57+
Fast DDS Pro additionally provides a TCP keep-alive mechanism to detect stalled TCP connections and recover
58+
from link failures more reliably.
59+
When enabled, the TCP transport periodically sends keep-alive requests on established TCP channels, and monitors
60+
activity to determine whether a connection is still responsive.
61+
Keep alive requests are sent only when no incoming data has been received for a specified interval.
62+
63+
If the configured timeout is reached without observing activity after a keep-alive request, the channel is
64+
considered broken and is closed, allowing Fast DDS to reconnect and restore communication.
65+
66+
Note that this feature operates at the application level, independently of any TCP keep-alive settings at the OS level.
67+
This allows for more fine-grained control over connection monitoring and recovery within Fast DDS.
68+
It also ensures consistent behavior across different operating systems and increases portability.
69+
70+
Keep alive is disabled by default and can be configured through the following parameters in
71+
|TCPTransportDescriptor-api|:
72+
73+
.. tab-set::
74+
75+
.. tab-item:: XML
76+
:sync: xml
77+
78+
.. literalinclude:: /../code/XMLTester.xml
79+
:language: xml
80+
:start-after: <!-->CONF-TCP-KEEP-ALIVE<-->
81+
:end-before: <!--><-->
82+
:lines: 2-3, 6-
83+
:append: </profiles>
84+
85+
.. tab-item:: C++
86+
:sync: cpp
87+
88+
.. literalinclude:: ../../../../code/DDSCodeTester.cpp
89+
:language: c++
90+
:dedent: 8
91+
:start-after: //CONF-TCP-KEEP-ALIVE
92+
:end-before: //!
93+
94+
.. note::
95+
96+
This feature is intended for TCP transports and only applies to connected TCP channels.

‎docs/fastdds/use_cases/use_cases.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@ with distributed systems:
2121
If the network interfaces are expected to change while the application is running, *Fast DDS Pro* provides an
2222
automatic way of re-scanning the available interfaces and including them.
2323

24+
+ :ref:`TCP Keep Alive <tcp-keep-alive>` |Pro|.
25+
In the same line as :ref:`IP mobility <ip-mobility>`, TCP Keep Alive feature allows to automatically detect
26+
broken TCP connections by sending periodic keep-alive messages at application level when the connection is idle.
27+
This feature is essential in TCP scenarios with dynamic IP changes or unstable network conditions,
28+
ensuring that stale connections are identified and re-established promptly.
29+
2430
+ :ref:`use-case-tcp`.
2531
Describes how to configure *Fast DDS* to use the ``LARGE_DATA`` builtin transports mode.
2632
This mode enables efficient utilization of TCP transport without the need for constant reconfiguration

‎docs/fastdds/xml_configuration/transports.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -84,13 +84,13 @@ A more detailed explanation of each of these elements can be found in :ref:`comm
8484
- ``string``
8585
-
8686
* - ``<keep_alive_frequency_ms>``
87-
- Frequency in milliseconds for sending :ref:`RTCP <rtcpdefinition>` keep-alive requests (TCP only).
87+
- |Pro| Frequency in milliseconds for sending :ref:`RTCP <rtcpdefinition>` keep-alive requests (TCP only).
8888
- ``uint32_t``
89-
- ``50000``
89+
- ``0``
9090
* - ``<keep_alive_timeout_ms>``
91-
- Time in milliseconds since the last keep-alive request was sent to consider a connection as broken (TCP only).
91+
- |Pro| Time in milliseconds since the last keep-alive request was sent to consider a connection as broken (TCP only).
9292
- ``uint32_t``
93-
- ``10000``
93+
- ``0``
9494
* - ``<max_logical_port>``
9595
- The maximum number of logical ports to try during :ref:`RTCP <rtcpdefinition>` negotiations (TCP only).
9696
- ``uint16_t``

0 commit comments

Comments
 (0)