Iox #482 add example for complex data types

doc/website/getting-started/examples/complexdata.md

@@ -0,0 +1,6 @@
+---
+title: Sending/receiving some of the iceoryx STL container surrogates
+---
+
+{! ./../iceoryx_examples/complexdata/README.md !}
+

iceoryx_examples/README.md

@@ -6,6 +6,7 @@
 |[icedelivery](./icedelivery/)               | Sending and receiving data using C++                                      | :star:             |
 |[icedelivery_in_c](./icedelivery_in_c/)     | Sending and receiving data using C                                        | :star:             |
 |[iceoptions](./iceoptions/)                 | Configuring pub/sub settings like history cache size or startup behaviour | :star:             |
+|[complexdata](./complexdata/)               | Sending/receiving some of the iceoryx STL container surrogates            | :star:             |
 |[callbacks](./callbacks/)                   | Implementing event triggered callbacks using C++                          | :star::star:       |
 |[callbacks_in_c](./callbacks_in_c/)         | Implementing event triggered callbacks using C                            | :star::star:       |
 |[waitset](./waitset/)                       | Waiting for events like arrival of data using C++                         | :star::star:       |

iceoryx_examples/complexdata/CMakeLists.txt

@@ -0,0 +1,66 @@
+# Copyright (c) 2021 by Apex.AI Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# Build complexdata example
+cmake_minimum_required(VERSION 3.5)
+project(example_complexdata)
+
+include(GNUInstallDirs)
+
+find_package(iceoryx_posh CONFIG REQUIRED)
+find_package(iceoryx_utils CONFIG REQUIRED)
+
+get_target_property(ICEORYX_CXX_STANDARD iceoryx_posh::iceoryx_posh CXX_STANDARD)
+include(IceoryxPlatform)
+
+add_executable(iox-cpp-publisher-vector ./iox_publisher_vector.cpp)
+target_link_libraries(iox-cpp-publisher-vector
+    iceoryx_posh::iceoryx_posh
+)
+target_compile_options(iox-cpp-publisher-vector PRIVATE ${ICEORYX_WARNINGS} ${ICEORYX_SANITIZER_FLAGS})
+
+add_executable(iox-cpp-subscriber-vector ./iox_subscriber_vector.cpp)
+target_link_libraries(iox-cpp-subscriber-vector
+    iceoryx_posh::iceoryx_posh
+)
+target_compile_options(iox-cpp-subscriber-vector PRIVATE ${ICEORYX_WARNINGS} ${ICEORYX_SANITIZER_FLAGS})
+
+add_executable(iox-cpp-publisher-complexdata ./iox_publisher_complexdata.cpp)
+target_link_libraries(iox-cpp-publisher-complexdata
+    iceoryx_posh::iceoryx_posh
+)
+target_compile_options(iox-cpp-publisher-complexdata PRIVATE ${ICEORYX_WARNINGS} ${ICEORYX_SANITIZER_FLAGS})
+
+add_executable(iox-cpp-subscriber-complexdata ./iox_subscriber_complexdata.cpp)
+target_link_libraries(iox-cpp-subscriber-complexdata
+    iceoryx_posh::iceoryx_posh
+)
+target_compile_options(iox-cpp-subscriber-complexdata PRIVATE ${ICEORYX_WARNINGS} ${ICEORYX_SANITIZER_FLAGS})
+
+set_target_properties(iox-cpp-subscriber-complexdata iox-cpp-subscriber-vector
+                      iox-cpp-publisher-complexdata iox-cpp-publisher-vector
+                      PROPERTIES
+    CXX_STANDARD_REQUIRED ON
+    CXX_STANDARD ${ICEORYX_CXX_STANDARD}
+    POSITION_INDEPENDENT_CODE ON
+)
+
+# ========================================================== //
+
+install(TARGETS iox-cpp-publisher-complexdata iox-cpp-publisher-vector
+        iox-cpp-subscriber-complexdata iox-cpp-subscriber-vector
+        RUNTIME DESTINATION bin)
+

iceoryx_examples/complexdata/README.md

@@ -0,0 +1,213 @@
+# complexdata
+
+## Introduction
+
+To implement zero-copy data transfer we use a shared memory approach. This requires that every data structure needs to be entirely
+contained in the shared memory and must not internally use pointers or references. The complete list of restrictions can be found
+[here](https://iceoryx.io/latest/getting-started/overview/#restrictions). Therefore, most of the STL types cannot be used, but we
+reimplemented some [constructs](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_utils#cxx). This example shows how
+to send/receive a iox::cxx::vector and how to send/receive a complex data structure containing some of our STL container surrogates.
+
+## Expected Output
+
+[![asciicast](https://asciinema.org/a/410662.svg)](https://asciinema.org/a/410662)
+
+## Code Walkthrough
+
+The following examples demonstrate how to send/receive the STL containers that were reimplemented in iceoryx so that they meet
+our requirements.
+
+### Publisher application sending a `iox::cxx::vector`
+
+In this example we want our publisher to send a vector containing double. Since we cannot use dynamic memory, we use the 
+`iox::cxx::vector` with a capacity of 5.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_vector.cpp][create publisher]-->
+```cpp
+iox::popo::Publisher<iox::cxx::vector<double, 5>> publisher({"Radar", "FrontRight", "VectorData"});
+```
+
+We use a while-loop similar to the one described in the 
+[icedelivery example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery) to send the
+vector to the subscriber. After successfully loaning memory we append elements to the vector until it's full.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_vector.cpp][vector emplace_back]-->
+```cpp
+for (uint64_t i = 0U; i < sample->capacity(); ++i)
+{
+    // we can omit the check of the return value since the loop doesn't exceed the capacity of the
+    // vector
+    sample->emplace_back(static_cast<double>(ct + i));
+}
+```
+
+The only difference here to the `std::vector` is that `emplace_back` returns a bool - true if the appending was successful,
+false otherwise. `emplace_back` fails when the vector is already full. In our case, we can omit the check of the return value
+since the for-loop doesn't exceed the capacity of the vector.
+
+### Subscriber application receiving a `iox::cxx::vector`
+
+Our subscriber application iterates over the received vector to print its entries to the console. Note that the `separator` is only
+used for a easy to read output.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_subscriber_vector.cpp][vector output]-->
+```cpp
+for (const auto& entry : *sample)
+{
+    s << separator << entry;
+    separator = ", ";
+}
+```
+
+### Publisher application sending a complex data structure
+
+In this example our publisher will send a more complex data structure. It contains some of the STL containers that are reimplemented
+in iceoryx. A list of all reimplemented containers can be found
+[here](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_utils#cxx).
+
+<!--[geoffrey][iceoryx_examples/complexdata/topic_data.hpp][complexdata type]-->
+```cpp
+struct ComplexDataType
+{
+    forward_list<string<10>, 5> stringForwardList;
+    list<uint64_t, 10> integerList;
+    list<optional<int32_t>, 15> optionalList;
+    stack<float, 5> floatStack;
+    string<20> someString;
+    vector<double, 5> doubleVector;
+    vector<variant<string<10>, double>, 10> variantVector;
+};
+```
+
+Contrary to the STL containers, the iceoryx containers have a static size, i.e. you have to provide the capacity (= max. size).
+
+We use again a while-loop to loan memory, add data to our containers and send it to the subscriber. Since we must not throw exceptions
+all used insertion methods return a bool that indicates whether the insertion was successful. It will fail when a container is already
+full. To handle the return value we introduce a helper function.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_complexdata.cpp][handle return val]-->
+```cpp
+void handleInsertionReturnVal(const bool success)
+{
+    if (!success)
+    {
+        std::cerr << "Failed to insert element." << std::endl;
+        std::exit(EXIT_FAILURE);
+    }
+}
+```
+
+Now let's add some data to our containers. For the lists we use the `push_front` methods which can be used similar to the 
+corresponding STL methods.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_complexdata.cpp][fill lists]-->
+```cpp
+// forward_list<string<10>, 5>
+handleInsertionReturnVal(sample->stringForwardList.push_front("world"));
+handleInsertionReturnVal(sample->stringForwardList.push_front("hello"));
+// list<uint64_t, 10>;
+handleInsertionReturnVal(sample->integerList.push_front(ct));
+handleInsertionReturnVal(sample->integerList.push_front(ct * 2));
+handleInsertionReturnVal(sample->integerList.push_front(ct + 4));
+// list<optional<int32_t>, 15>
+handleInsertionReturnVal(sample->optionalList.push_front(42));
+handleInsertionReturnVal(sample->optionalList.push_front(nullopt));
+```
+
+!!! note
+    If you're not familiar with `optional`, please have a look at
+    [How optional and error values are returned in iceoryx](https://github.com/eclipse-iceoryx/iceoryx/blob/master/doc/website/advanced/how-optional-and-error-values-are-returned-in-iceoryx.md#optional).
+
+Now we fill the stack
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_complexdata.cpp][fill stack]-->
+```cpp
+for (uint64_t i = 0U; i < sample->floatStack.capacity(); ++i)
+{
+    handleInsertionReturnVal(sample->floatStack.push(static_cast<float>(ct * i)));
+}
+```
+
+and assign a greeting to the string.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_complexdata.cpp][assign string]-->
+```cpp
+sample->someString = "hello iceoryx";
+```
+
+For the vectors we use the `emplace_back` method, which can be used similar to corresponding `std::vector` method.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_publisher_complexdata.cpp][fill vectors]-->
+```cpp
+for (uint64_t i = 0U; i < sample->doubleVector.capacity(); ++i)
+{
+    handleInsertionReturnVal(sample->doubleVector.emplace_back(static_cast<double>(ct + i)));
+}
+// vector<variant<string<10>, double>, 10>;
+handleInsertionReturnVal(sample->variantVector.emplace_back(in_place_index<0>(), "seven"));
+handleInsertionReturnVal(sample->variantVector.emplace_back(in_place_index<1>(), 8.0));
+handleInsertionReturnVal(sample->variantVector.emplace_back(in_place_index<0>(), "nine"));
+```
+
+With `in_place_index` the passed object is constructed in-place at the given index.
+
+### Subscriber application receiving a complex data structure
+
+The subscriber application just prints the received data to the console. For the `optionalList` we have to check whether the
+`optional` contains a value. As in the first example, the `separator` is used for a clear output.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_subscriber_complexdata.cpp][read optional list]-->
+```cpp
+for (const auto& entry : sample->optionalList)
+{
+    (entry.has_value()) ? s << separator << entry.value() : s << separator << "optional is empty";
+    separator = ", ";
+}
+```
+
+To print the elements of the `floatStack`, we pop elements until the stack is empty.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_subscriber_complexdata.cpp][read stack]-->
+```cpp
+auto stackCopy = sample->floatStack;
+while (stackCopy.size() > 0U)
+{
+    auto result = stackCopy.pop();
+    s << separator << result.value();
+    separator = ", ";
+}
+```
+
+Please note that `pop` returns a `iox::cxx::optional` which contains the last pushed element or a `nullopt` if the stack is
+empty. Here, we don't have to check whether the `optional` contains a value since the loop ensures that we only pop elements
+when the stack contains some.
+
+To print the elements of the `variantVector` we iterate over the vector entries and access the alternative that is held by the
+variant via its index. We use the not STL compliant `get_at_index` method which returns a pointer to the type stored at the
+index. If the variant does not contain any type, `index()` will return an `INVALID_VARIANT_INDEX`.
+
+<!--[geoffrey][iceoryx_examples/complexdata/iox_subscriber_complexdata.cpp][read variant vector]-->
+```cpp
+for (const auto& i : sample->variantVector)
+{
+    switch (i.index())
+    {
+    case 0:
+        s << separator << *i.template get_at_index<0>();
+        break;
+    case 1:
+        s << separator << *i.template get_at_index<1>();
+        break;
+    case INVALID_VARIANT_INDEX:
+        s << separator << "variant does not contain a type";
+        break;
+    default:
+        s << separator << "this is a new type";
+    }
+    separator = ", ";
+}
+```
+
+<center>
+[Check out complexdata on GitHub :fontawesome-brands-github:](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/complexdata){ .md-button }
+</center>