From 1c18d887067e52f205d75a71dc2bf4e0bbac873f Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Wed, 15 Sep 2021 16:21:18 +0200 Subject: [PATCH 1/5] 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 +``` From 953d7602c9db8aab8f9aa753a403550477dcb01f Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Wed, 15 Sep 2021 16:34:07 +0200 Subject: [PATCH 2/5] iox-#924 Exclude docker example from out of tree build Signed-off-by: Christian Eltzschig --- tools/iceoryx_build_test.sh | 1 + 1 file changed, 1 insertion(+) diff --git a/tools/iceoryx_build_test.sh b/tools/iceoryx_build_test.sh index 76a16f6a69..d851cadccc 100755 --- a/tools/iceoryx_build_test.sh +++ b/tools/iceoryx_build_test.sh @@ -304,6 +304,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 From 1fb9f8bff17dc250838dfd62808b90b690ec00bc Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Thu, 16 Sep 2021 14:27:29 +0200 Subject: [PATCH 3/5] iox-#924 Add docker-compose.yml file Signed-off-by: Christian Eltzschig --- iceoryx_examples/icedocker/README.md | 15 ++++++++++++- iceoryx_examples/icedocker/docker-compose.yml | 22 +++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 iceoryx_examples/icedocker/docker-compose.yml diff --git a/iceoryx_examples/icedocker/README.md b/iceoryx_examples/icedocker/README.md index c554521ad9..df3276a907 100644 --- a/iceoryx_examples/icedocker/README.md +++ b/iceoryx_examples/icedocker/README.md @@ -70,7 +70,7 @@ filesystem: into every docker container. -### Example +### 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. @@ -103,3 +103,16 @@ docker run --mount type=bind,source="/dev",target=/dev --mount type=bind,source= 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 new file mode 100644 index 0000000000..61cd8a3d6f --- /dev/null +++ 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 From ba2c37d6a418688c6e72cb411d3fcc863bb5a694 Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Thu, 16 Sep 2021 18:17:19 +0200 Subject: [PATCH 4/5] iox-#924 Add AVIN AP as iceoryx adopters - adjust iceoryx rust binding path - Add platform overview with supported features - Use unambiguous symbols in platform support matrix Signed-off-by: Christian Eltzschig --- README.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 705c15018f..4887a65c44 100644 --- 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 | ✅ | ✅ | +| QNX | ✅ | ✅ | +| MacOS | ❌, not planned for implementation | ✅ | +| Windows 10 | ❌, not planned for implementation | ✔, not yet 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 From 2b0aeaf668d716dfc5a269d5ddae4efaaf9f862b Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Wed, 22 Sep 2021 13:27:19 +0200 Subject: [PATCH 5/5] iox-#924 Fix typos, use ASCII text instead of unicode check marks in readme Signed-off-by: Christian Eltzschig --- README.md | 8 ++++---- iceoryx_examples/icedocker/README.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 4887a65c44..b3dd2d2505 100644 --- a/README.md +++ b/README.md @@ -51,10 +51,10 @@ You can find the full API documentation on 🌐 [https://iceoryx.io](https://ice |Operating System| supports access rights for shared memory | command line parsing | |----------------|:----------------------------------------:|:-----------------------:| -| Linux | ✅ | ✅ | -| QNX | ✅ | ✅ | -| MacOS | ❌, not planned for implementation | ✅ | -| Windows 10 | ❌, not planned for implementation | ✔, not yet implemented | +| 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? diff --git a/iceoryx_examples/icedocker/README.md b/iceoryx_examples/icedocker/README.md index df3276a907..b78cb9d652 100644 --- a/iceoryx_examples/icedocker/README.md +++ b/iceoryx_examples/icedocker/README.md @@ -34,7 +34,7 @@ by sending a message to the unix domain socket located at 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. +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`. @@ -74,8 +74,8 @@ into every docker container. 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 +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).