Merge pull request #925 from ApexAI/iox-#924-docker-example

iox-#924 Add icedocker example readme
eclipse-iceoryx · Sep 22, 2021 · 72a5cf7 · 72a5cf7
2 parents 78541c4 + 2b0aeaf
commit 72a5cf7
Show file tree

Hide file tree

Showing 7 changed files with 161 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -18,7 +18,7 @@ tour, introducing the project scope and all you need for installation and a firs
 
 So first off: What is iceoryx?
 
-iceoryx is an inter-process-communication (IPC) middleware for various operating systems (currently we support Linux, MacOS and QNX).
+iceoryx is an inter-process-communication (IPC) middleware for various operating systems (currently we support Linux, MacOS, QNX and Windows 10).
 It has its origins in the automotive industry, where large amounts of data have to be transferred between different processes
 when it comes to driver assistance or automated driving systems. However, the efficient communication mechanisms can also be applied
 to a wider range of use cases, e.g. in the field of robotics or game development. 
@@ -47,6 +47,15 @@ An example for such a "porcelain" API would be [ROS 2](https://www.ros.org/). Ot
 
 You can find the full API documentation on 🌐 [https://iceoryx.io](https://iceoryx.io).
 
+### Supported Platforms
+
+|Operating System| supports access rights for shared memory | command line parsing    |
+|----------------|:----------------------------------------:|:-----------------------:|
+| Linux          | yes                                      | yes                     |
+| QNX            | yes                                      | yes                     |
+| MacOS          | no, not planned for implementation       | yes                     |
+| Windows 10     | no, not planned for implementation       | will be implemented     |
+
 ### Where is Eclipse iceoryx used?
 
 |Framework | Description |
@@ -56,6 +65,7 @@ You can find the full API documentation on 🌐 [https://iceoryx.io](https://ice
 | [RTA-VRTE](https://www.etas.com/en/products/rta-vrte.php) | [Adaptive AUTOSAR](https://www.autosar.org/standards/adaptive-platform/) platform software framework for vehicle computer from [ETAS GmbH](https://www.etas.com) |
 | [Cyclone DDS](https://github.com/eclipse-cyclonedds/cyclonedds) | Performant and robust open-source DDS implementation maintained by [ADLINK Technology Inc.](https://www.adlinktech.com/) |
 | [Apex.OS](https://www.apex.ai/apex-os) | Safe and certified software framework for autonomous mobility systems from Apex.AI |
+| [AVIN AP](https://www.avinsystems.com/products/autosar_ap_solutions/) | AUTOSAR Adaptive Platform Product from AVIN Systems |
 
 ## Build and install
 
@@ -107,7 +117,7 @@ Get to know the upcoming features and the project scope in [PLANNED_FEATURES.md]
 |Name | Description | Technologies |
 |---|---|---|
 | [Larry.Robotics](https://gitlab.com/larry.robotics) | An iceoryx demonstrator for tinker, thinker and toddler | Demonstrator |
-| [iceoryx-rs](https://github.com/elBoberido/iceoryx-rs) | Experimental Rust wrapper for iceoryx | Rust |
+| [iceoryx-rs](https://github.com/eclipse-iceoryx/iceoryx-rs) | Experimental Rust wrapper for iceoryx | Rust |
 | [IceRay](https://github.com/elBoberido/iceray) | An iceoryx introspection client written in Rust | Rust |
 
 ## Governance & maintainers

diff --git a/doc/website/getting-started/examples/icedocker.md b/doc/website/getting-started/examples/icedocker.md
@@ -0,0 +1,5 @@
+---
+title: Sending and receiving data across multiple docker instances
+---
+
+{! ../iceoryx/iceoryx_examples/icedocker/README.md !}
diff --git a/iceoryx_examples/README.md b/iceoryx_examples/README.md
@@ -5,6 +5,7 @@
 |[icehello](./icehello/)                     | Sending data to another process                                           | :star:             |
 |[icedelivery](./icedelivery/)               | Sending and receiving data using C++                                      | :star:             |
 |[icedelivery_in_c](./icedelivery_in_c/)     | Sending and receiving data using C                                        | :star:             |
+|[icedocker](./icedocker/)                   | Sending and receiving data across multiple docker instances               | :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:       |

diff --git a/iceoryx_examples/icedelivery_in_c/README.md b/iceoryx_examples/icedelivery_in_c/README.md
@@ -34,7 +34,7 @@ Let's take a look at the `receiving` function that comes with the
 
     ```c
     const char APP_NAME[] = "iox-c-subscriber";
-    iox_runtime_init("APP_NAME");
+    iox_runtime_init(APP_NAME);
     ```
 
  2. We create a subscriber port and subscribe to the service
@@ -109,7 +109,7 @@ Let's take a look at the `sending` function that comes with the
 
     ```c
     const char APP_NAME[] = "iox-c-publisher";
-    iox_runtime_init("APP_NAME");
+    iox_runtime_init(APP_NAME);
     ```
 
  2. We create a publisher with the service

diff --git a/iceoryx_examples/icedocker/README.md b/iceoryx_examples/icedocker/README.md
@@ -0,0 +1,118 @@
+# Use Iceoryx In A Docker Environment
+
+## Introduction
+
+Let's assume we are working on a system in which `iox-roudi` runs in a docker
+environment and it should orchestrate two applications which are running again
+in two different docker containers so that we end up with a system of 3
+different docker containers.
+
+To demonstrate the setup we use the 
+[icedelivery C++ example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery).
+
+```
+                         +-----------+
+                         | docker 1  |
+                         |           |
+                         | iox-roudi |
+                         +-----------+
+
+       +-------------------+        +--------------------+
+       | docker 2          | send   | docker 3           |
+       |                   |------->|                    |
+       | iox-cpp-publisher | data   | iox-cpp-subscriber |
+       +-------------------+        +--------------------+
+```
+
+## Requirements
+
+### Shared Access to Unix Domain Sockets
+
+Every iceoryx application is registering itself at our central broker RouDi
+by sending a message to the unix domain socket located at
+`IOX_UDS_SOCKET_PATH_PREFIX/roudi` which is defined in the corresponding
+platform settings file `platform_settings.hpp`. In linux the socket file handle
+can be found at `/tmp/roudi`. While registering it announces its unix
+domain socket to roudi for the responses of application requests which were
+sent to roudi.
+This socket is stored as well in `/tmp/IOX_RUNTIME_NAME`. The `iox-cpp-publisher`
+runtime has the same name as the binary which leads to the socket
+`/tmp/iox-cpp-publisher`.
+
+### Shared Access to File Locks
+
+Iceoryx applications ensure that every runtime name is unique in the system
+by creating a file lock before creating the runtime. This is stored in 
+`IOX_LOCK_FILE_PATH_PREFIX/IOX_RUNTIME_NAME.lock` whereby 
+`IOX_LOCK_FILE_PATH_PREFIX` is defined in the platform settings file
+`platform_settings.hpp`. When running the icedelivery example in a linux
+environment one can observe
+the lock files `/tmp/roudi.lock`, `/tmp/iox-cpp-subscriber.lock` and
+`/tmp/iox-cpp-publisher.lock`.
+
+### Shared Access to Semaphores and Shared Memory
+
+One of the tasks of the central broker RouDi is to create and distribute shared
+memory. When the `iox-cpp-publisher` would like to send data it acquires a
+pointer to this shared memory, writes the data into it and sends the
+pointer to the `iox-cpp-subscriber` which reads the memory at the received
+memory position.
+Additionally, it is possible to signal events across process boundaries via
+semaphores. For instance to signal a subscriber that data has arrived.
+
+## Implementation
+
+To have shared access to the required resources we have to bind the host 
+filesystem:
+
+ * `/tmp`
+ * `/dev`
+
+into every docker container.
+
+### Terminal Example
+
+We start in 3 separate terminals 3 docker instances. In this example we
+use `archlinux:latest` but one is free to choose any other linux distribution.
+The iceoryx repository which contains an already built iceoryx can be found at
+`/home/user/iceoryx` which is bound to `/iceoryx`. The usage is 
+explained in detail in the 
+[icedelivery C++ example](https://github.com/eclipse-iceoryx/iceoryx/tree/master/iceoryx_examples/icedelivery).
+
+#### Terminal 1 (iox-roudi)
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iox-roudi
+```
+
+#### Terminal 2 (iox-cpp-publisher)
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iceoryx_examples/icedelivery/iox-cpp-publisher
+```
+
+#### Terminal 3 (iox-cpp-subscriber)
+
+```
+docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source=/home/user/iceoryx,target=/iceoryx --mount type=bind,source=/tmp,target=/tmp -it archlinux:latest
+
+cd /iceoryx
+./build/iceoryx_examples/icedelivery/iox-cpp-subscriber
+```
+
+### docker-compose Example
+
+We can also use `docker-compose` to start our test setup. Our example is coming
+with a configuration file `docker-compose.yml` which can be used from the
+iceoryx root path with the following command:
+
+```
+docker-compose -f iceoryx_examples/icedocker/docker-compose.yml --project-directory . up
+```
+
+We have to set the project directory explicitly so that the mapping of the
+iceoryx root path is working as intended.
diff --git a/iceoryx_examples/icedocker/docker-compose.yml b/iceoryx_examples/icedocker/docker-compose.yml
@@ -0,0 +1,22 @@
+services:
+  roudi:
+    image: archlinux:latest
+    command: /iceoryx/build/iox-roudi
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp
+  publisher:
+    image: archlinux:latest
+    command: /iceoryx/build/iceoryx_examples/icedelivery/iox-cpp-publisher
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp
+  subscriber:
+    image: archlinux:latest
+    command: /iceoryx/build/iceoryx_examples/icedelivery/iox-cpp-subscriber
+    volumes:
+      - .:/iceoryx
+      - /dev:/dev
+      - /tmp:/tmp
diff --git a/tools/iceoryx_build_test.sh b/tools/iceoryx_build_test.sh
@@ -311,6 +311,7 @@ if [ "$OUT_OF_TREE_FLAG" == "ON" ]; then
     # Exclude directories without CMake file from the out-of-tree build
     EXAMPLES=${EXAMPLES/iceensemble/""}
     EXAMPLES=${EXAMPLES/icecrystal/""}
+    EXAMPLES=${EXAMPLES/icedocker/""}
     echo ">>>>>> Start Out-of-tree build <<<<<<"
     echo ${EXAMPLES}
     mkdir -p build_out_of_tree && cd build_out_of_tree