Skip to content

Commit

Permalink
SHM Transport documentation update (#104)
Browse files Browse the repository at this point in the history 
* Refs #8044. SHM Transport documentation update.

* Apply suggestions from code review

Refs #8044. Apply suggestions.

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

* Refs #8044. Suggested changes.

Signed-off-by: AdolfoMartinez <[email protected]>

Co-authored-by: Eduardo Ponz Segrelles <[email protected]>
Co-authored-by: Miguel Company <[email protected]>
  • Loading branch information
@adolfomarver @EduPonz @MiguelCompany
3 people authored Apr 2, 2020
1 parent 6d7a346 commit c4de70e
Show file tree
Hide file tree
Showing 4 changed files with 84 additions and 87 deletions.
10 changes: 10 additions & 0 deletions code/XMLTester.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2181,6 +2181,16 @@
<transport_id>ExampleTransportId2</transport_id>
<type>UDPv6</type>
</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-->
<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
151 changes: 74 additions & 77 deletions docs/advanced.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -224,8 +224,12 @@ Transports
**********

*eProsima Fast RTPS* implements an architecture of pluggable transports.
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.
Current version implements five transports: UDPv4, UDPv6, TCPv4, TCPv6 and SHM (shared memory).
By default, when a :class:`Participant` is created, two built-in transports are configured:

* SHM transport will be used for all communications between participants in the same machine.
* UDPv4 will be used for inter machine communications.

You can add custom transports using the attribute ``rtps.userTransports``.

+-----------------------------------------------------+
Expand All @@ -246,6 +250,74 @@ You can add custom transports using the attribute ``rtps.userTransports``.

All Transport configuration options can be found in the section :ref:`transportdescriptors`.

.. _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.

In order to change the default parameters of SHM transport, 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. In both cases ``rtps.useBuiltinTransports`` must be disabled (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).

* ``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 listeners don'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 output file format is *tcpdump* text hex, and can be read with protocol analyzer applications such as Wireshark.

.. _comm-transports-tcp:

TCP Transport
Expand Down Expand Up @@ -629,81 +701,6 @@ 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
2 changes: 0 additions & 2 deletions docs/fullxmloptions.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,6 @@
<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>
Expand Down
8 changes: 0 additions & 8 deletions docs/xmlprofiles.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -187,14 +187,6 @@ The XML label ``<transport_descriptors>`` can hold any number of ``<transport_de
| | 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 | | |
Expand Down

0 comments on commit c4de70e

Please sign in to comment.