Doc: Added documentation for 5.12 release (#1182)

Co-authored-by: Kerstin Keller <KerstinKeller@users.noreply.github.com>
Co-authored-by: Rex Schilasky <49162693+rex-schilasky@users.noreply.github.com>

doc/rst/advanced/layers/shm.rst

@@ -40,7 +40,7 @@ Communication phase (default configuration):
 * The subscribers close the memory file and release the access-mutex.
 
 
-To support one to many publisher/subscriber connections the publisher creates in fact one named update event per connection.
+To support one to many publisher/subscriber connections, the publisher creates one named update event per connection.
 
 .. note::
 
@@ -92,73 +92,41 @@ Finally that means the publishers ``CPublisher::Send`` API function call is now
 Zero Copy mode (optional)
 -------------------------
 
-*Zero-copy has been added in eCAL 5.10. It is turned off by default. When turned on, old eCAL Version can still receive the data but will not use zero-copy.**
-
-The “normal” eCAL Shared memory communication results in the payload being copied at least twice:
-
-1. Into the SHM file by the publisher
-
-2. From the SHM file the private memory of each subscriber
-
-Usually there is no issue with that.
-Copying the payload from the memory file before executing the subscriber callback results in better decoupling, so the publisher can update the memory file with the next message while the subscriber is still processing the last one.
-Small messages will be transmitted in a few microseconds and will not benefit from zero-copy.
-
-If it comes to very large messages (e.g. high resolution images) however, copying really matters and it can make sense to activate eCAL's zero-copy mode.
-With zero-copy, the communication would look like this:
-
-1. The publisher still has to copy the data into the memory file.
-
-2. The subscriber executes its callback directly on the memory file.
-   The memory file is blocked, while being used.
-
-   .. warning::
-
-      The memory file is blocked for new publications as long as the user’s callback is processing its content.
-      It will also block other subscribers from reading the same SHM file.
-
-3. The subscriber releases the memory file, so the publisher can update it again.
-
 .. note::
 
-   Even though it is called zero-copy, only the subscribers are zero-copy.
-   Publishers still have to copy the data into the memory file, as they have to also support other layers like UDP or TCP and therefore cannot directly work on the memory file.
+   Zero-copy has been added in eCAL 5.10 for subscription and in 5.12 for publishing.
+   It is turned off by default.
+   When turned on, old eCAL Versions can still receive the data but will not use zero-copy.
 
-Zero-copy can be enabled in the following ways:
+The "normal" eCAL Shared memory communication results in the payload being copied at least twice:
 
-- **Use zero-copy as system-default (not recommended!):**
-
-  Activating zero copy system-wide is not recommended because of the mentioned disadvantages for small payloads.
-  But if this is wanted for reasons it can be done by adapting your :file:`ecal.ini` like this.
-
-  .. code-block:: ini
-
-     [publisher]
-     memfile_zero_copy = 1
+1. Into the SHM file by the publisher
 
-- **Use zero-copy for a single publisher (from your code):**
+2. From the SHM file the private memory of each subscriber
 
-  Zero copy could be activated either per connection or for a complete system using the eCAL configuration file.
-  To activate it for a specific publisher this ``CPublisher`` `API function <https://eclipse-ecal.github.io/ecal/_api/classeCAL_1_1CPublisher.html#_CPPv4N4eCAL10CPublisher17ShmEnableZeroCopyEb>`_ needs to be called.
+Copying the payload from the memory file before executing the subscriber callback results in **better decoupling**, so the publisher can update the memory file with the next message while the subscriber is still processing the last one.
+**Small messages** will be transmitted in a few microseconds and will not benefit from zero-copy.
 
-  .. code-block:: cpp
+If it comes to very **large messages** (e.g. high resolution images) however, copying really matters and it can make sense to activate eCAL's **zero-copy mode**.
 
-     // Create a publisher (topic name "person")
-     eCAL::protobuf::CPublisher<pb::People::Person> pub("person");
+.. seealso:: 
 
-     // Enable zero-copy for this publisher
-     pub.ShmEnableZeroCopy(true);
+   Check out the following Chapter to learn how to enable zero-copy.
+   The chapter will also teach you about advantages and disadvantages of zero-copy:
 
-.. note::
+   .. toctree:: 
+      :maxdepth: 1
 
-   In general, it is advisable to combine zero-copy with multi-buffering to reduce the impact on the publisher.
+      shm_zerocopy.rst
 
 Multi-buffering mode (optional)
 -------------------------------
 
-*Multi-buffering has been added in eCAL 5.10.
-Multi-buffered topics cannot be received by older eCAL versions.
-The feature is turned off by default.*
+.. note:: 
+
+   Multi-buffering has been added in eCAL 5.10.
+   Multi-buffered topics cannot be received by older eCAL versions.
+   The feature is turned off by default.
 
 As described in the previous sections, eCAL uses one shared memory file per publisher. This can lead to performance reduction if
 
@@ -199,3 +167,4 @@ You can activate the feature in the following ways.
      pub.ShmSetBufferCount(3);
 
 Combining the zero-copy feature with an increased number of memory buffer files (like 2 or 3) could be a nice setup allowing the subscriber to work on the memory file content without copying its content and nevertheless not blocking the publisher to write new data.
+Using Multibuffering however will force each Send operation to re-write the entire memory file and disable partial updates.