From 4a827b77f270611f7556f4bee37ec707a3bd6b21 Mon Sep 17 00:00:00 2001 From: AdolfoMartinez <49362510+adolfomarver@users.noreply.github.com> Date: Thu, 26 Mar 2020 08:12:29 +0100 Subject: [PATCH] Shared memory doc [8054] (#103) * Refs #8044 SHM Transport documentation. * Refs #8044. Fix namespace & text issues. * Refs #8044. Apply suggestions from code review. Co-Authored-By: Eduardo Ponz Segrelles * Refs #8044. Fix suggestions test errors. * Refs #8044. SHM Parameters explanation. * Apply suggestions from code review Refs #8044. Suggestions. Co-Authored-By: Eduardo Ponz Segrelles * Refs #8044. Added tcpdump to dictionary & XML comments. * Refs #8044. Added Wireshark to dictionary. Co-authored-by: Eduardo Ponz Segrelles --- code/CodeTester.cpp | 13 +++++++ code/XMLTester.xml | 21 +++++++++++ docs/advanced.rst | 77 +++++++++++++++++++++++++++++++++++++- docs/fullxmloptions.xml | 14 +++++++ docs/spelling_wordlist.txt | 3 ++ docs/xmlprofiles.rst | 33 +++++++++++++++- 6 files changed, 159 insertions(+), 2 deletions(-) diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp index 44a612dfc..0c94a741c 100644 --- a/code/CodeTester.cpp +++ b/code/CodeTester.cpp @@ -14,6 +14,7 @@ #include #include #include +#include #include #include #include @@ -30,6 +31,7 @@ using namespace ::rtps; using namespace ::xmlparser; using namespace ::security; using namespace ::types; +using SharedMemTransportDescriptor = eprosima::fastdds::rtps::SharedMemTransportDescriptor; class HelloWorld { @@ -169,6 +171,17 @@ participant_attr.rtps.useBuiltinTransports = false; participant_attr.rtps.userTransports.push_back(tcp_transport); //!-- +//CONF-SHM-TRANSPORT-SETTING +// Create a descriptor for the new transport. +std::shared_ptr shm_transport = std::make_shared(); + +// Disable the built-in Transport Layer. +participant_attr.rtps.useBuiltinTransports = false; + +// Link the Transport Layer to the Participant. +participant_attr.rtps.userTransports.push_back(shm_transport); +//!-- + //CONF-TCP2-TRANSPORT-SETTING auto tcp2_transport = std::make_shared(); diff --git a/code/XMLTester.xml b/code/XMLTester.xml index a551ddad1..1a97892d9 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -440,6 +440,27 @@ <--> +CONF-SHM-TRANSPORT-SETTING<--> + + + + shm_transport + SHM + + + + + + + + shm_transport + + + false + + +<--> + CONF-TCP2-TRANSPORT-SETTING<--> diff --git a/docs/advanced.rst b/docs/advanced.rst index 201336c5e..b49b7ab5d 100644 --- a/docs/advanced.rst +++ b/docs/advanced.rst @@ -224,7 +224,7 @@ Transports ********** *eProsima Fast RTPS* implements an architecture of pluggable transports. -Current version implements four transports: UDPv4, UDPv6, TCPv4 and TCPv6. +Current version implements five transports: UDPv4, UDPv6, TCPv4, TCPv6 and SHM. By default, when a :class:`Participant` is created, one built-in UDPv4 transport is configured. You can add custom transports using the attribute ``rtps.userTransports``. @@ -594,6 +594,81 @@ For UDP transport, it is possible to configure whether to use non-blocking write | :end-before: <--> | +-----------------------------------------------+ +.. _comm-transports-shm: + +Shared memory Transport (SHM) +============================= + +The shared memory transport enables fast communications between entities running in the same processing unit/machine, +relying on the shared memory mechanisms provided by the host operating system. + +SHM transport provides better performance than other transports like UDP / TCP, even when these transports use loopback +interface. This is mainly due to the following reasons: + + * Large message support: Network protocols need to fragment data in order to comply with the specific protocol and + network stacks requirements. + SHM transport allows the copy of full messages where the only size limit is the machine's memory capacity. + + * Reduce the number of memory copies: When sending the same message to different endpoints, SHM transport can + directly share the same memory buffer with all the destination endpoints. + Other protocols require to perform one copy of the message per endpoint. + + * Less operating system overhead: Once initial setup is completed, shared memory transfers require much less system + calls than the other protocols. + Therefore there is a performance/time consume gain by using SHM. + +When two participants on the same machine have SHM transport enabled, all communications between them are automatically +performed by SHM transport only. +The rest of the enabled transports are not used between those two participants. + +To enable SHM transport in a Participant, you need to add the SharedMemTransportDescriptor to the +``rtps.userTransports`` attribute (C++ code) or define a transport_descriptor of type SHM in the +XML file (see below examples). + ++--------------------------------------------------+ +| **C++** | ++--------------------------------------------------+ +| .. literalinclude:: ../code/CodeTester.cpp | +| :language: c++ | +| :start-after: //CONF-SHM-TRANSPORT-SETTING | +| :end-before: //!-- | ++--------------------------------------------------+ +| **XML** | ++--------------------------------------------------+ +| .. literalinclude:: ../code/XMLTester.xml | +| :language: xml | +| :start-after: CONF-SHM-TRANSPORT-SETTING | +| :end-before: <--> | ++--------------------------------------------------+ + +SHM configuration parameters: + + * ``segment_size``: The size of the shared memory segment in bytes. + A shared memory segment is created by each participant. + Participant's writers copy their messages into the segment and send a message reference to the destination readers. + + * ``port_queue_capacity``: Each participant with SHM transport enabled listens on a queue (port) for incoming SHM + message references. + This parameter specifies the queue size (in messages). + + * ``port_overflow_policy``: Possible values are either :class:`DISCARD` or :class:`FAIL`. + Indicates what to do when the Listener queue is full. + :class:`DISCARD` drops the message without notifying any error, :class:`FAIL` drops the message but throws an error. + + * ``segment_overflow_policy``: Possible values are either :class:`DISCARD` or :class:`FAIL`. + Indicates what to do when there is no available space for messages in the shared memory segment. + + * ``healthy_check_timeout_ms``: With SHM, Readers and writers use a queue to exchange messages (called Port). + If one of the processes involved crashes while using the port, the structure can be left inoperative. + For this reason, every time a port is opened, a healthy check is performed. + If the attached processes doesn't respond in ``healthy_check_timeout_ms`` milliseconds, the port is destroyed and + created again. + + * ``rtps_dump_file``: Full path, including the file name, of the protocol dump_file. + When this string parameter is not empty, all the participant's SHM traffic (sent and received) is traced to a file. + The file format is *tcpdump* test hex, and can be read with protocol analyzer applications such as Wireshark. + + **XML Configuration** The :ref:`xml-profiles` section contains the full information about how to setup *Fast RTPS* through an diff --git a/docs/fullxmloptions.xml b/docs/fullxmloptions.xml index 7db3d1bc8..d4d352577 100644 --- a/docs/fullxmloptions.xml +++ b/docs/fullxmloptions.xml @@ -24,6 +24,20 @@ 5200 + + + + SHM_SAMPLE_DESCRIPTOR + SHM + 524288 + 1048576 + 1024 + DISCARD + FAIL + 250 + test_file.dump + + diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 983fc339c..e1385e526 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -67,6 +67,7 @@ hostid interoperability libs lroundl +loopback mandatorily metatraffic middleware @@ -100,6 +101,7 @@ submessage submessages submodules takeNextData +tcpdump tinyxml topologies typeobject @@ -111,3 +113,4 @@ unmatch vcstool whitelist whitelists +Wireshark diff --git a/docs/xmlprofiles.rst b/docs/xmlprofiles.rst index 5209d6ab7..75a224f5f 100644 --- a/docs/xmlprofiles.rst +++ b/docs/xmlprofiles.rst @@ -96,7 +96,8 @@ The XML label ```` can hold any number of ```` | Type of the transport descriptor. | :class:`UDPv4`, :class:`UDPv6`, | :class:`UDPv4` | -| | | :class:`TCPv4`, :class:`TCPv6` | | +| | | :class:`TCPv4`, :class:`TCPv6`, | | +| | | :class:`SHM` | | +-------------------------------+-----------------------------------+---------------------------------+----------------+ | ```` | Size in bytes of the socket | ``uint32`` | 0 | | | send buffer. | | | @@ -178,6 +179,36 @@ The XML label ```` can hold any number of ```` | Size (in bytes) of the | ``uint32`` | 262144 | +| | shared-memory segment. | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ +| ```` | Capacity (in number of messages) | ``uint32`` | 512 | +| | available to every Listener | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ +| ```` | Error policy when a messages | :class:`OverflowPolicy` | DISCARD | +| | Listener overflows | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ +| ```` | Error policy when the | :class:`OverflowPolicy` | DISCARD | +| | shared-memory segment overflows | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ +| ````| Maximum time-out (in milliseconds)| ``uint32`` | 1000 | +| | used when checking whether a | | | +| | Listener is alive & OK | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ +| ```` | Complete path (including file) | ``string`` | empty | +| | where RTPS messages will be | | | +| | stored for debugging purposes. | | | +| | An empty string indicates no | | | +| | trace will be performed | | | +| | (OPTIONAL, SHM **only**). | | | ++-------------------------------+-----------------------------------+---------------------------------+----------------+ + + .. _rtcpdefinition: