Skip to content

Commit

Permalink
Document caveats with SHM and datasharing with dynamic network interf…
Browse files Browse the repository at this point in the history 
…aces (#487)

* Refs #18453: caveats with SHM and datasharing if network interfaces are modified at runtime

Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com>

* Refs #18453: apply review suggestion

Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com>

---------

Signed-off-by: JLBuenoLopez-eProsima <joseluisbueno@eprosima.com>
  • Loading branch information
@JLBuenoLopez
JLBuenoLopez committed May 11, 2023
1 parent a0e43ea commit 6f8a975
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 29 deletions.
4 changes: 3 additions & 1 deletion docs/03-exports/aliases-api.include
View file
Original file line number Diff line number Diff line change
Expand Up @@ -846,7 +846,9 @@
.. |FILTER_DIFFERENT_PROCESS| replace:: :cpp:enumerator:`FILTER_DIFFERENT_PROCESS<eprosima::fastrtps::rtps::ParticipantFilteringFlags::FILTER_DIFFERENT_PROCESS>`
.. |FILTER_SAME_PROCESS| replace:: :cpp:enumerator:`FILTER_SAME_PROCESS<eprosima::fastrtps::rtps::ParticipantFilteringFlags::FILTER_SAME_PROCESS>`

.. |Guid_t-api| replace:: :cpp:struct:`Guid_t<eprosima::fastrtps::rtps::Guid_t>`
.. |Guid_t-api| replace:: :cpp:struct:`Guid_t<eprosima::fastrtps::rtps::GUID_t>`
.. |is_on_same_host_as-api| replace:: :cpp:func:`is_on_same_host_as()<eprosima::fastrtps::rtps::GUID_t::is_on_same_host_as>`
.. |is_on_same_process_as-api| replace:: :cpp:func:`is_on_same_process_as()<eprosima::fastrtps::rtps::GUID_t::is_on_same_process_as>`
.. |GuidPrefix_t-api| replace:: :cpp:struct:`GuidPrefix_t<eprosima::fastrtps::rtps::GuidPrefix_t>`
.. |EntityId_t-api| replace:: :cpp:struct:`EntityId_t<eprosima::fastrtps::rtps::EntityId_t>`
.. |InitialAnnouncementConfig-api| replace:: :cpp:struct:`InitialAnnouncementConfig<eprosima::fastrtps::rtps::InitialAnnouncementConfig>`
Expand Down
8 changes: 8 additions & 0 deletions docs/fastdds/transport/datasharing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ by sharing the history of the |DataWriter| with the |DataReader| through shared
This prevents any of the overhead involved in the transport layer,
effectively avoiding any data copy between DataWriter and DataReader.

.. note::

Fast DDS utilizes the |DomainParticipant|'s |GuidPrefix_t-api| to identify peers running in the same host.
Two participants with identical 4 first bytes on the |GuidPrefix_t-api| are considered to be running in the same
host.
|is_on_same_host_as-api| API is provided to check this condition.
Please, take also into account the caveats included in :ref:`intraprocess_delivery_guids`.

Use of Data-sharing delivery does not prevent data copies between the application
and the DataReader and DataWriter.
These can be avoided in some cases using :ref:`use-case-zero-copy`.
Expand Down
64 changes: 36 additions & 28 deletions docs/fastdds/transport/intraprocess.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,33 +39,41 @@ GUID Prefix considerations for intra-process delivery
Fast DDS utilizes the |DomainParticipant|'s |GuidPrefix_t-api| to identify peers running in the same process.
Two participants with identical 8 first bytes on the |GuidPrefix_t-api| are considered to be running in the same
process, and therefore intra-process delivery is used.
|is_on_same_process_as-api| API is provided to check this condition.
This mechanism works out-of-the-box when letting Fast DDS set the GUID prefixes for the created DomainParticipants.
However, special consideration is required when setting the |GuidPrefix_t-api| manually, either programmatically or when
using XML

+----------------------------------------------------------------------------------------------------------------------+
| **C++** - Option 1: Manual setting of the ``unsigned char`` in ASCII format. |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/DDSCodeTester.cpp |
| :language: c++ |
| :start-after: //CONF_GUIDPREFIX_OPTION_1 |
| :end-before: //!-- |
| :dedent: 8 |
+----------------------------------------------------------------------------------------------------------------------+
| **C++** - Option 2: Using the ``>>`` operator and the ``std::istringstream`` type. |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/DDSCodeTester.cpp |
| :language: c++ |
| :start-after: //CONF_GUIDPREFIX_OPTION_2 |
| :end-before: //!-- |
| :dedent: 8 |
+----------------------------------------------------------------------------------------------------------------------+
| **XML** |
+----------------------------------------------------------------------------------------------------------------------+
| .. literalinclude:: /../code/XMLTester.xml |
| :language: xml |
| :start-after: <!-->CONF-GUID-PREFIX<--> |
| :end-before: <!--><--> |
| :lines: 2-3,5- |
| :append: </profiles> |
+----------------------------------------------------------------------------------------------------------------------+
using XML.

.. important::

Fast DDS assigns GUID prefixes considering several host parameters.
Among them, the network interfaces enabled.
Thus, if at runtime, the network interfaces change, any new DomainParticipant will have a different GUID prefix and
will be considered to be running on another host.

.. tabs::

.. tab:: **C++** - ASCII format.

.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:start-after: //CONF_GUIDPREFIX_OPTION_1
:end-before: //!--
:dedent: 8

.. tab:: **C++** - Extraction operator.

.. literalinclude:: /../code/DDSCodeTester.cpp
:language: c++
:start-after: //CONF_GUIDPREFIX_OPTION_2
:end-before: //!--
:dedent: 8

.. tab:: **XML**

.. literalinclude:: /../code/XMLTester.xml
:language: xml
:start-after: <!-->CONF-GUID-PREFIX<-->
:end-before: <!--><-->
:lines: 2-3,5-
:append: </profiles>
9 changes: 9 additions & 0 deletions docs/fastdds/transport/shared_memory/shared_memory.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
.. include:: ../../../03-exports/aliases.include
.. include:: ../../../03-exports/aliases-api.include
.. include:: ../includes/aliases.rst

Expand All @@ -9,6 +10,14 @@ Shared Memory Transport
The shared memory (SHM) 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.

.. note::

Fast DDS utilizes the |DomainParticipant|'s |GuidPrefix_t-api| to identify peers running in the same host.
Two participants with identical 4 first bytes on the |GuidPrefix_t-api| are considered to be running in the same
host.
|is_on_same_host_as-api| API is provided to check this condition.
Please, take also into account the caveats included in :ref:`intraprocess_delivery_guids`.

SHM transport provides better performance than other network transports like UDP / TCP,
even when these transports use loopback interface.
This is mainly due to the following reasons:
Expand Down

0 comments on commit 6f8a975

Please sign in to comment.