From 1c18d887067e52f205d75a71dc2bf4e0bbac873f Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Wed, 15 Sep 2021 16:21:18 +0200 Subject: [PATCH] iox-#924 Add icedocker example readme Signed-off-by: Christian Eltzschig --- .../getting-started/examples/icedocker.md | 5 + iceoryx_examples/README.md | 1 + iceoryx_examples/icedelivery_in_c/README.md | 4 +- iceoryx_examples/icedocker/README.md | 105 ++++++++++++++++++ 4 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 doc/website/getting-started/examples/icedocker.md create mode 100644 iceoryx_examples/icedocker/README.md diff --git a/doc/website/getting-started/examples/icedocker.md b/doc/website/getting-started/examples/icedocker.md new file mode 100644 index 0000000000..944fd3bbea --- /dev/null +++ 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 index 3956d2ee35..180a5e53f2 100644 --- 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 index 6a77f487ec..a27c0ce649 100644 --- 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 new file mode 100644 index 0000000000..c554521ad9 --- /dev/null +++ b/iceoryx_examples/icedocker/README.md @@ -0,0 +1,105 @@ +# 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 +send 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. + +### 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 build iceoryx can be found at +`/home/user/iceoryx` which is bound to `/iceoryx`. The usage and building 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 +```