Merge pull request eclipse-iceoryx#375 from elfenpiff/iox2-370-domain…

…-separation-cpp-example

[eclipse-iceoryx#370] domain separation cpp example

examples/README.md

@@ -48,7 +48,7 @@ they interact and exchange data.
 | complex data types                   | [Rust](rust/complex_data_types) | Send zero-copy compatible versions of `Vec` and `String`. Introduces `PlacementDefault` trait for large data types to perform an in place initialization where otherwise a stack overflow would be encountered.|
 | discovery                            | [C](c/discovery) [C++](cxx/discovery) [Rust](rust/discovery) | List all available services in a system. |
 | docker                               | [all](rust/docker) | Communicate between different docker containers and the host. |
-| domains                              | [Rust](rust/domains) | Establish separate domains that operate independently from one another. |
+| domains                              | [C++](cxx/domains) [Rust](rust/domains) | Establish separate domains that operate independently from one another. |
 | event                                | [C](c/event) [C++](cxx/event) [Rust](rust/event) | Push notifications - send event signals to wakeup processes that are waiting for them.|
 | publish subscribe                    | [C](c/publish_subscribe) [C++](cxx/publish_subscribe) [Rust](rust/publish_subscribe) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern). |
 | publish subscribe dynamic data       | [Rust](rust/publish_subscribe_dynamic_data) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern) and payload data that has a dynamic size. |

examples/cxx/CMakeLists.txt

@@ -18,6 +18,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
 add_subdirectory(complex_data_types)
 add_subdirectory(discovery)
+add_subdirectory(domains)
 add_subdirectory(event)
 add_subdirectory(publish_subscribe)
 add_subdirectory(publish_subscribe_dynamic_data)

examples/cxx/domains/BUILD.bazel

@@ -0,0 +1,48 @@
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache Software License 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+# which is available at https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+load("@rules_cc//cc:defs.bzl", "cc_binary", "cc_library")
+
+cc_binary(
+    name = "example_cxx_domains_publisher",
+    srcs = [
+        "src/publisher.cpp",
+        "src/transmission_data.hpp",
+    ],
+    deps = [
+        "@iceoryx//:iceoryx_hoofs",
+        "//:iceoryx2-cxx",
+    ],
+)
+
+cc_binary(
+    name = "example_cxx_domains_subscriber",
+    srcs = [
+        "src/subscriber.cpp",
+        "src/transmission_data.hpp",
+    ],
+    deps = [
+        "@iceoryx//:iceoryx_hoofs",
+        "//:iceoryx2-cxx",
+    ],
+)
+
+cc_binary(
+    name = "example_cxx_domains_discovery",
+    srcs = [
+        "src/discovery.cpp",
+    ],
+    deps = [
+        "@iceoryx//:iceoryx_hoofs",
+        "//:iceoryx2-cxx",
+    ],
+)

examples/cxx/domains/CMakeLists.txt

@@ -0,0 +1,25 @@
+# Copyright (c) 2024 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache Software License 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+# which is available at https://opensource.org/licenses/MIT.
+#
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+
+cmake_minimum_required(VERSION 3.22)
+project(example_cxx_domains LANGUAGES CXX)
+
+find_package(iceoryx2-cxx 0.3.0 REQUIRED)
+
+add_executable(example_cxx_domains_publisher src/publisher.cpp)
+target_link_libraries(example_cxx_domains_publisher iceoryx2-cxx::static-lib-cxx)
+
+add_executable(example_cxx_domains_subscriber src/subscriber.cpp)
+target_link_libraries(example_cxx_domains_subscriber iceoryx2-cxx::static-lib-cxx)
+
+add_executable(example_cxx_domains_discovery src/discovery.cpp)
+target_link_libraries(example_cxx_domains_discovery iceoryx2-cxx::static-lib-cxx)

examples/cxx/domains/README.md

@@ -0,0 +1,67 @@
+# Domains
+
+Please install all dependencies first, as described in the [C++ Examples Readme](../README.md).
+
+Let's assume you want to create multiple iceoryx2 groups of processes where the
+processes inside a group can communicate and interact with each other. However,
+the groups themselves should remain isolated, meaning a process from one group
+cannot interact with a process from another group.
+
+In other words, we aim to create different iceoryx2 domains on a local machine
+that are strictly separated.
+
+This strict separation can be achieved by using the iceoryx2 configuration.
+Within the configuration, a wide range of parameters can be adjusted, such as
+the directory used for files containing static service information (a detailed
+description of the service) or static node information (a detailed description
+of a node). Additionally, the prefix of all files, which is by default `iox2_`,
+can be modified.
+
+In this example, we use the prefix to separate the iceoryx2 groups. For all
+examples, the user can set the iceoryx2 domain using `-d $DOMAIN_NAME$`. The
+domain name must be a valid file name. The example will only operate within
+this domain and cannot interact with any services in other domains with
+different names.
+
+The `domains_discovery` binary illustrates this by listing all services
+available in a given domain. Similarly, the `domains_publisher` will send data
+only to subscribers within the same domain. Subscribers in other domains will
+not receive any data.
+
+## Implementation
+
+To achieve this, we create a copy of the global configuration, modify the
+setting `config.global.prefix` using the user-provided CLI argument, and then
+set up the example accordingly.
+
+## Running The Example
+
+You can experiment with this setup by creating multiple publishers and
+subscribers with different service names using `-s $SERVICE_NAME`. Only
+publisher-subscriber pairs within the same domain will be able to communicate,
+and the discovery tool will only detect services from within the same domain.
+
+First you have to build the C++ examples:
+
+```sh
+cmake -S . -B target/ffi/build -DBUILD_EXAMPLES=ON
+cmake --build target/ffi/build
+```
+
+**Terminal 1:** Subscriber in domain "fuu" subscribing to service "bar"
+
+```sh
+./target/ffi/build/examples/cxx/domains/example_cxx_domains_subscriber -d "fuu" -s "bar"
+```
+
+**Terminal 2** Publisher in domain "fuu" publishing on service "bar"
+
+```sh
+./target/ffi/build/examples/cxx/domains/example_cxx_domains_publisher -d "fuu" -s "bar"
+```
+
+**Terminal 3** List all services of domain "fuu"
+
+```sh
+./target/ffi/build/examples/cxx/domains/example_cxx_domains_discovery -d "fuu"
+```

examples/cxx/domains/src/discovery.cpp

@@ -0,0 +1,47 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#include "iox/cli_definition.hpp"
+#include "iox2/callback_progression.hpp"
+#include "iox2/config.hpp"
+#include "iox2/service.hpp"
+#include "iox2/service_type.hpp"
+
+#include <iostream>
+
+// NOLINTBEGIN
+struct Args {
+    IOX_CLI_DEFINITION(Args);
+    IOX_CLI_OPTIONAL(
+        iox::string<32>, domain, { "iox2_" }, 'd', "domain", "The name of the domain. Must be a valid file name.");
+    IOX_CLI_SWITCH(debug, 'e', "debug", "Enable full debug log output");
+};
+// NOLINTEND
+
+auto main(int argc, char** argv) -> int {
+    using namespace iox2;
+    auto args = Args::parse(argc, argv, "Discovery of the domain example.");
+
+    // create a new config based on the global config
+    auto config = Config::global_config().to_owned();
+
+    // The domain name becomes the prefix for all resources.
+    // Therefore, different domain names never share the same resources.
+    config.global().set_prefix(iox::FileName::create(args.domain()).expect("valid domain name"));
+
+    Service<ServiceType::Ipc>::list(config.view(), [](auto service) {
+        std::cout << service.static_details << std::endl;
+        return CallbackProgression::Continue;
+    }).expect("discover all available services");
+
+    return 0;
+}

examples/cxx/domains/src/publisher.cpp

@@ -0,0 +1,80 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#include "iox/cli_definition.hpp"
+#include "iox/duration.hpp"
+#include "iox/string.hpp"
+#include "iox2/config.hpp"
+#include "iox2/node.hpp"
+#include "iox2/sample_mut.hpp"
+#include "iox2/service_name.hpp"
+#include "iox2/service_type.hpp"
+#include "transmission_data.hpp"
+
+#include <iostream>
+#include <utility>
+
+// NOLINTBEGIN
+struct Args {
+    IOX_CLI_DEFINITION(Args);
+    IOX_CLI_OPTIONAL(
+        iox::string<32>, domain, { "iox2_" }, 'd', "domain", "The name of the domain. Must be a valid file name.");
+    IOX_CLI_OPTIONAL(iox::string<256>, service, { "my_funky_service" }, 's', "service", "The name of the service.");
+    IOX_CLI_SWITCH(debug, 'e', "debug", "Enable full debug log output");
+};
+// NOLINTEND
+
+constexpr iox::units::Duration CYCLE_TIME = iox::units::Duration::fromSeconds(1);
+
+auto main(int argc, char** argv) -> int {
+    using namespace iox2;
+    auto args = Args::parse(argc, argv, "Publisher of the domain example.");
+
+    // create a new config based on the global config
+    auto config = Config::global_config().to_owned();
+
+    // The domain name becomes the prefix for all resources.
+    // Therefore, different domain names never share the same resources.
+    config.global().set_prefix(iox::FileName::create(args.domain()).expect("valid domain name"));
+
+    auto node = NodeBuilder()
+                    // use the custom config when creating the custom node
+                    // every service constructed by the node will use this config
+                    .config(config)
+                    .create<ServiceType::Ipc>()
+                    .expect("successful node creation");
+
+    auto service = node.service_builder(ServiceName::create(args.service().c_str()).expect("valid service name"))
+                       .publish_subscribe<TransmissionData>()
+                       .open_or_create()
+                       .expect("successful service creation/opening");
+
+    auto publisher = service.publisher_builder().create().expect("successful publisher creation");
+
+    auto counter = 0;
+    while (node.wait(CYCLE_TIME) == NodeEvent::Tick) {
+        counter += 1;
+
+        auto sample = publisher.loan_uninit().expect("acquire sample");
+
+        sample.write_payload(TransmissionData { counter, counter * 3, counter * 812.12 }); // NOLINT
+
+        send_sample(std::move(sample)).expect("send successful");
+
+        std::cout << "[domain: \"" << args.domain() << "\", service: \"" << args.service() << "] Send sample "
+                  << counter << "..." << std::endl;
+    }
+
+    std::cout << "exit" << std::endl;
+
+    return 0;
+}

examples/cxx/domains/src/subscriber.cpp

@@ -0,0 +1,72 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#include <iostream>
+
+#include "iox/cli_definition.hpp"
+#include "iox/duration.hpp"
+#include "iox2/node.hpp"
+#include "iox2/service_name.hpp"
+#include "iox2/service_type.hpp"
+#include "transmission_data.hpp"
+
+// NOLINTBEGIN
+struct Args {
+    IOX_CLI_DEFINITION(Args);
+    IOX_CLI_OPTIONAL(
+        iox::string<32>, domain, { "iox2_" }, 'd', "domain", "The name of the domain. Must be a valid file name.");
+    IOX_CLI_OPTIONAL(iox::string<256>, service, { "my_funky_service" }, 's', "service", "The name of the service.");
+    IOX_CLI_SWITCH(debug, 'e', "debug", "Enable full debug log output");
+};
+// NOLINTEND
+
+constexpr iox::units::Duration CYCLE_TIME = iox::units::Duration::fromSeconds(1);
+
+auto main(int argc, char** argv) -> int {
+    using namespace iox2;
+    auto args = Args::parse(argc, argv, "Subscriber of the domain example.");
+
+    // create a new config based on the global config
+    auto config = Config::global_config().to_owned();
+
+    // The domain name becomes the prefix for all resources.
+    // Therefore, different domain names never share the same resources.
+    config.global().set_prefix(iox::FileName::create(args.domain()).expect("valid domain name"));
+
+    auto node = NodeBuilder()
+                    // use the custom config when creating the custom node
+                    // every service constructed by the node will use this config
+                    .config(config)
+                    .create<ServiceType::Ipc>()
+                    .expect("successful node creation");
+
+    auto service = node.service_builder(ServiceName::create(args.service().c_str()).expect("valid service name"))
+                       .publish_subscribe<TransmissionData>()
+                       .open_or_create()
+                       .expect("successful service creation/opening");
+
+    auto subscriber = service.subscriber_builder().create().expect("successful subscriber creation");
+
+    std::cout << "subscribed to: [domain: \"" << args.domain() << "\", service: \"" << args.service() << "\"]"
+              << std::endl;
+    while (node.wait(CYCLE_TIME) == NodeEvent::Tick) {
+        auto sample = subscriber.receive().expect("receive succeeds");
+        while (sample.has_value()) {
+            std::cout << "received: " << sample->payload() << std::endl;
+            sample = subscriber.receive().expect("receive succeeds");
+        }
+    }
+
+    std::cout << "exit" << std::endl;
+
+    return 0;
+}

examples/cxx/domains/src/transmission_data.hpp

@@ -0,0 +1,30 @@
+// Copyright (c) 2024 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Apache Software License 2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
+// which is available at https://opensource.org/licenses/MIT.
+//
+// SPDX-License-Identifier: Apache-2.0 OR MIT
+
+#ifndef IOX2_EXAMPLES_TRANSMISSION_DATA_HPP
+#define IOX2_EXAMPLES_TRANSMISSION_DATA_HPP
+
+#include <cstdint>
+#include <iostream>
+
+struct TransmissionData {
+    std::int32_t x;
+    std::int32_t y;
+    double funky;
+};
+
+inline auto operator<<(std::ostream& stream, const TransmissionData& value) -> std::ostream& {
+    stream << "TransmissionData { x: " << value.x << ", y: " << value.y << ", funky: " << value.funky << " }";
+    return stream;
+}
+
+#endif