Skip to content

Commit

Permalink
Shared memory doc <master> [8054] (#103)
Browse files Browse the repository at this point in the history 
* Refs #8044 SHM Transport documentation.

* Refs #8044. Fix namespace & text issues.

* Refs #8044. Apply suggestions from code review.

Co-Authored-By: Eduardo Ponz Segrelles <[email protected]>

* 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 <[email protected]>

* Refs #8044. Added tcpdump to dictionary & XML comments.

* Refs #8044. Added Wireshark to dictionary.

Co-authored-by: Eduardo Ponz Segrelles <[email protected]>
  • Loading branch information
@adolfomarver @EduPonz
adolfomarver and EduPonz authored Mar 26, 2020
1 parent 932d2e5 commit 4a827b7
Show file tree
Hide file tree
Showing 6 changed files with 159 additions and 2 deletions.
13 changes: 13 additions & 0 deletions code/CodeTester.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
#include <fastrtps/xmlparser/XMLEndpointParser.h>
#include <fastrtps/transport/UDPv4TransportDescriptor.h>
#include <fastrtps/transport/TCPv4TransportDescriptor.h>
#include <fastdds/rtps/transport/shared_mem/SharedMemTransportDescriptor.h>
#include <fastrtps/types/DynamicDataFactory.h>
#include <fastrtps/utils/IPLocator.h>
#include <fastrtps/log/Log.h>
Expand All @@ -30,6 +31,7 @@ using namespace ::rtps;
using namespace ::xmlparser;
using namespace ::security;
using namespace ::types;
using SharedMemTransportDescriptor = eprosima::fastdds::rtps::SharedMemTransportDescriptor;

class HelloWorld
{
Expand Down Expand Up @@ -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<SharedMemTransportDescriptor> shm_transport = std::make_shared<SharedMemTransportDescriptor>();

// 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<TCPv4TransportDescriptor>();

Expand Down
21 changes: 21 additions & 0 deletions code/XMLTester.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -440,6 +440,27 @@
</participant>
<!--><-->

<!-->CONF-SHM-TRANSPORT-SETTING<-->
<transport_descriptors>
<!-- Create a descriptor for the new transport -->
<transport_descriptor>
<transport_id>shm_transport</transport_id>
<type>SHM</type>
</transport_descriptor>
</transport_descriptors>

<participant profile_name="SHMParticipant">
<rtps>
<!-- Link the Transport Layer to the Participant -->
<userTransports>
<transport_id>shm_transport</transport_id>
</userTransports>
<!-- Disable the built-in Transport Layer -->
<useBuiltinTransports>false</useBuiltinTransports>
</rtps>
</participant>
<!--><-->

<!-->CONF-TCP2-TRANSPORT-SETTING<-->
<transport_descriptors>
<transport_descriptor>
Expand Down
77 changes: 76 additions & 1 deletion docs/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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``.

Expand Down Expand Up @@ -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
Expand Down
14 changes: 14 additions & 0 deletions docs/fullxmloptions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,20 @@
<port>5200</port> <!-- uint16 -->
</listening_ports>
</transport_descriptor>

<!-- SHM sample transport descriptor -->
<transport_descriptor>
<transport_id>SHM_SAMPLE_DESCRIPTOR</transport_id>
<type>SHM</type> <!-- REQUIRED -->
<maxMessageSize>524288</maxMessageSize> <!-- OPTIONAL uint32 valid of all transports-->
<segment_size>1048576</segment_size> <!-- OPTIONAL uint32 SHM only-->
<port_queue_capacity>1024</port_queue_capacity> <!-- OPTIONAL uint32 SHM only-->
<port_overflow_policy>DISCARD</port_overflow_policy> <!-- OPTIONAL OverflowPolicy (FAIL | DISCARD) -->
<segment_overflow_policy>FAIL</segment_overflow_policy> <!-- OPTIONAL OverflowPolicy (FAIL | DISCARD)-->
<healthy_check_timeout_ms>250</healthy_check_timeout_ms> <!-- OPTIONAL uint32 SHM only-->
<rtps_dump_file>test_file.dump</rtps_dump_file> <!-- OPTIONAL string SHM only-->
</transport_descriptor>

</transport_descriptors>

<types>
Expand Down
3 changes: 3 additions & 0 deletions docs/spelling_wordlist.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ hostid
interoperability
libs
lroundl
loopback
mandatorily
metatraffic
middleware
Expand Down Expand Up @@ -100,6 +101,7 @@ submessage
submessages
submodules
takeNextData
tcpdump
tinyxml
topologies
typeobject
Expand All @@ -111,3 +113,4 @@ unmatch
vcstool
whitelist
whitelists
Wireshark
33 changes: 32 additions & 1 deletion docs/xmlprofiles.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,8 @@ The XML label ``<transport_descriptors>`` can hold any number of ``<transport_de
| | transport descriptor. | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<type>`` | Type of the transport descriptor. | :class:`UDPv4`, :class:`UDPv6`, | :class:`UDPv4` |
| | | :class:`TCPv4`, :class:`TCPv6` | |
| | | :class:`TCPv4`, :class:`TCPv6`, | |
| | | :class:`SHM` | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<sendBufferSize>`` | Size in bytes of the socket | ``uint32`` | 0 |
| | send buffer. | | |
Expand Down Expand Up @@ -178,6 +179,36 @@ The XML label ``<transport_descriptors>`` can hold any number of ``<transport_de
| | parameters and options | | |
| | (TCP **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<segment_size>`` | Size (in bytes) of the | ``uint32`` | 262144 |
| | shared-memory segment. | | |
| | (OPTIONAL, SHM **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<port_queue_capacity>`` | Capacity (in number of messages) | ``uint32`` | 512 |
| | available to every Listener | | |
| | (OPTIONAL, SHM **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<port_overflow_policy>`` | Error policy when a messages | :class:`OverflowPolicy` | DISCARD |
| | Listener overflows | | |
| | (OPTIONAL, SHM **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<segment_overflow_policy>`` | Error policy when the | :class:`OverflowPolicy` | DISCARD |
| | shared-memory segment overflows | | |
| | (OPTIONAL, SHM **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<healthy_check_timeout_ms>``| Maximum time-out (in milliseconds)| ``uint32`` | 1000 |
| | used when checking whether a | | |
| | Listener is alive & OK | | |
| | (OPTIONAL, SHM **only**). | | |
+-------------------------------+-----------------------------------+---------------------------------+----------------+
| ``<rtps_dump_file>`` | 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:

Expand Down

0 comments on commit 4a827b7

Please sign in to comment.