Merge pull request #903 from ekxide/iox2-817-blackboard-examples

[#817] blackboard examples + e2e tests

Author: FerdinandSpitzschnueffler

examples/README.md

@@ -0,0 +1,35 @@
+# Copyright (c) 2025 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_rust//rust:defs.bzl", "rust_binary")
+
+rust_binary(
+    name = "creator",
+    srcs = [
+        "creator.rs",
+    ],
+    deps = [
+        "//iceoryx2:iceoryx2",
+        "//iceoryx2-bb/container:iceoryx2-bb-container",
+    ],
+)
+
+rust_binary(
+    name = "opener",
+    srcs = [
+        "opener.rs",
+    ],
+    deps = [
+        "//iceoryx2:iceoryx2",
+        "//iceoryx2-bb/container:iceoryx2-bb-container",
+    ],
+)

examples/rust/blackboard/BUILD.bazel

@@ -0,0 +1,53 @@
+# Blackboard
+
+> [!CAUTION]
+> Every payload you transmit with iceoryx2 must implement [`ZeroCopySend`] to
+> be compatible with shared memory.
+> Usually, you can use the derive-macro `#[derive(ZeroCopySend)]` for most
+> types. If you implement it manually you must ensure that the payload type:
+>
+> * is self contained, no heap, no pointers to external sources
+> * has a uniform memory representation -> `#[repr(C)]`
+> * does not use pointers to manage their internal structure
+> * and its members don't implement `Drop` explicitly
+> * has a `'static` lifetime
+>
+> Data types like `String` or `Vec` will cause undefined behavior and may
+> result in segmentation faults. We provide alternative data types that are
+> compatible with shared memory. See the
+> [complex data type example](../complex_data_types) for guidance on how to
+> use them.
+
+This example illustrates the blackboard messaging pattern. A writer updates the
+values in the blackboard every second and a reader reads and prints them to the
+console. The key-value pairs must be defined via the the service builder:
+
+```rust
+node.service_builder(&service_name)
+    .blackboard_creator::<u32>()
+    .add_with_default::<u64>(0)
+    .add::<FixedSizeByteString<30>>(5, "Groovy".try_into()?)
+    .add_with_default::<f32>(9)
+    .create()?;
+```
+
+## How to Run
+
+To observe the blackboard messaging pattern in action, open two separate
+terminals and execute the following commands:
+
+### Terminal 1
+
+```sh
+cargo run --example blackboard_creator
+```
+
+### Terminal 2
+
+```sh
+cargo run --example blackboard_opener
+```
+
+Feel free to run multiple instances of reader processes simultaneously but note
+that the `blackboard_creator` must run first to create the blackboard service
+with the key-value pairs and that there can be only one writer.

examples/rust/blackboard/README.md

@@ -24,15 +24,17 @@ fn main() -> Result<(), Box<dyn core::error::Error>> {
     let service = node
         .service_builder(&"My/Funk/ServiceName".try_into()?)
         .blackboard_creator::<KeyType>()
-        .add::<u64>(0, 0)
-        .add::<FixedSizeByteString<100>>(5, "Groovy".try_into()?)
-        .add::<f32>(9, 0.0)
+        .add_with_default::<u64>(0)
+        .add::<FixedSizeByteString<30>>(5, "Groovy".try_into()?)
+        .add_with_default::<f32>(9)
         .create()?;
 
+    println!("Blackboard created.\n");
+
     let writer = service.writer_builder().create()?;
 
     let writer_handle_0 = writer.entry::<u64>(&0)?;
-    let mut writer_handle_5 = writer.entry::<FixedSizeByteString<100>>(&5)?;
+    let mut writer_handle_5 = writer.entry::<FixedSizeByteString<30>>(&5)?;
     let writer_handle_9 = writer.entry::<f32>(&9)?;
 
     let mut counter = 0;
@@ -46,13 +48,13 @@ fn main() -> Result<(), Box<dyn core::error::Error>> {
         let entry_value_uninit = writer_handle_5.loan_uninit();
         let value = format!("Funky {}", counter);
         let entry_value =
-            entry_value_uninit.write(FixedSizeByteString::<100>::from_bytes(value.as_bytes())?);
+            entry_value_uninit.write(FixedSizeByteString::<30>::from_bytes(value.as_bytes())?);
         writer_handle_5 = entry_value.update();
         println!("Write new value for key 5: {}", value);
 
         let value = counter as f32 * 7.7;
         writer_handle_9.update_with_copy(value);
-        println!("Write new value for key 9: {value}");
+        println!("Write new value for key 9: {value}\n");
     }
 
     println!("exit");

examples/rust/blackboard/creator.rs

@@ -29,15 +29,15 @@ fn main() -> Result<(), Box<dyn core::error::Error>> {
     let reader = service.reader_builder().create()?;
 
     let reader_handle_0 = reader.entry::<u64>(&0)?;
-    let reader_handle_5 = reader.entry::<FixedSizeByteString<100>>(&5)?;
+    let reader_handle_5 = reader.entry::<FixedSizeByteString<30>>(&5)?;
     let reader_handle_9 = reader.entry::<f32>(&9)?;
 
     while node.wait(CYCLE_TIME).is_ok() {
         println!("read values:");
 
-        println!("key: 0, {}", reader_handle_0.get());
-        println!("key: 5, {}", reader_handle_5.get());
-        println!("key: 9, {}\n", reader_handle_9.get());
+        println!("key: 0, value: {}", reader_handle_0.get());
+        println!("key: 5, value: {}", reader_handle_5.get());
+        println!("key: 9, value: {}\n", reader_handle_9.get());
     }
 
     println!("exit");

examples/rust/blackboard/opener.rs

@@ -0,0 +1,37 @@
+#!/usr/bin/expect
+# Copyright (c) 2025 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
+
+#### Common Setup
+
+set REPO_ROOT [exec git rev-parse --show-toplevel]
+cd ${REPO_ROOT}
+
+source examples/cross-language-end-to-end-tests/common.exp
+
+#### Test Setup
+
+set timeout 10
+
+spawn cargo run --example blackboard_creator
+set id_creator $spawn_id
+# wait until ready
+expect_output "Blackboard created."
+
+spawn cargo run --example blackboard_opener
+
+#### Test Assertion
+
+expect_output_from $id_creator "Write new value for key 0: 4"
+expect_output "key: 0, value: 4"
+
+show_test_passed

examples/rust/blackboard/test_e2e_blackboard.exp

@@ -0,0 +1,35 @@
+# Copyright (c) 2025 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_rust//rust:defs.bzl", "rust_binary")
+
+rust_binary(
+    name = "creator",
+    srcs = [
+        "creator.rs",
+    ],
+    deps = [
+        "//iceoryx2:iceoryx2",
+        "//iceoryx2-bb/container:iceoryx2-bb-container",
+    ],
+)
+
+rust_binary(
+    name = "opener",
+    srcs = [
+        "opener.rs",
+    ],
+    deps = [
+        "//iceoryx2:iceoryx2",
+        "//iceoryx2-bb/container:iceoryx2-bb-container",
+    ],
+)

examples/rust/blackboard_event_based_communication/BUILD.bazel

@@ -0,0 +1,43 @@
+# Blackboard with Notification on Value Update
+
+> [!CAUTION]
+> Every payload you transmit with iceoryx2 must implement [`ZeroCopySend`] to
+> be compatible with shared memory.
+> Usually, you can use the derive-macro `#[derive(ZeroCopySend)]` for most
+> types. If you implement it manually you must ensure that the payload type:
+>
+> * is self contained, no heap, no pointers to external sources
+> * has a uniform memory representation -> `#[repr(C)]`
+> * does not use pointers to manage their internal structure
+> * and its members don't implement `Drop` explicitly
+> * has a `'static` lifetime
+>
+> Data types like `String` or `Vec` will cause undefined behavior and may
+> result in segmentation faults. We provide alternative data types that are
+> compatible with shared memory. See the
+> [complex data type example](../complex_data_types) for guidance on how to
+> use them.
+
+This example demonstrates how to combine the blackboard with the event messaging
+pattern so that values can be read when updated instead of using a polling loop.
+Besides the [blackboard](../blackboard) service, an additional [event](../event)
+service is created. This is used to create a notifier that sends a notification
+whenever a value is updated, using the entry id, and a listener that waits for
+notifications with a certain entry id and reads the updated value.
+
+## How to Run
+
+To observe the blackboard messaging pattern with notifications on value update
+in action, open two separate terminals and execute the following commands:
+
+### Terminal 1
+
+```sh
+cargo run --example blackboard_event_based_creator
+```
+
+### Terminal 2
+
+```sh
+cargo run --example blackboard_event_based_opener
+```

examples/rust/blackboard_event_based_communication/README.md

@@ -16,33 +16,48 @@ use iceoryx2::prelude::*;
 const CYCLE_TIME: Duration = Duration::from_secs(1);
 
 fn main() -> Result<(), Box<dyn core::error::Error>> {
-    set_log_level_from_env_or(LogLevel::Trace);
+    set_log_level_from_env_or(LogLevel::Info);
     let node = NodeBuilder::new().create::<ipc::Service>()?;
     type KeyType = u32;
-    let key = 99;
+    const INTERESTING_KEY: u32 = 1;
 
     let service = node
         .service_builder(&"My/Funk/ServiceName".try_into()?)
         .blackboard_creator::<KeyType>()
-        .add::<u64>(key, 2023)
+        .add_with_default::<u64>(0)
+        .add_with_default::<u64>(INTERESTING_KEY)
         .create()?;
 
+    println!("Blackboard created.\n");
+
     let event_service = node
         .service_builder(&"My/Funk/ServiceName".try_into()?)
         .event()
         .open_or_create()?;
-    let listener = event_service.listener_builder().create()?;
-
-    let reader = service.reader_builder().create()?;
-    let reader_handle = reader.entry::<u64>(&key)?;
-
-    // wait for entry id
-    while node.wait(Duration::ZERO).is_ok() {
-        if let Ok(Some(id)) = listener.timed_wait_one(CYCLE_TIME) {
-            if id == reader_handle.entry_id() {
-                println!("read u64: {}", reader_handle.get());
-            }
-        }
+    let notifier = event_service.notifier_builder().create()?;
+
+    let writer = service.writer_builder().create()?;
+
+    let writer_handle = writer.entry::<u64>(&0)?;
+    let entry_id = writer_handle.entry_id();
+
+    let interesting_writer_handle = writer.entry::<u64>(&INTERESTING_KEY)?;
+    let interesting_entry_id = interesting_writer_handle.entry_id();
+
+    // notify with entry id
+    let mut counter: u64 = 0;
+    while node.wait(CYCLE_TIME).is_ok() {
+        counter += 1;
+        interesting_writer_handle.update_with_copy(counter);
+        notifier.notify_with_custom_event_id(interesting_entry_id)?;
+        println!(
+            "Trigger event with entry id {}",
+            interesting_entry_id.as_value()
+        );
+
+        writer_handle.update_with_copy(2 * counter);
+        notifier.notify_with_custom_event_id(entry_id)?;
+        println!("Trigger event with entry id {}", entry_id.as_value());
     }
 
     println!("exit");

examples/rust/blackboard_event_based_communication/creator.rs

@@ -16,10 +16,10 @@ use iceoryx2::prelude::*;
 const CYCLE_TIME: Duration = Duration::from_secs(1);
 
 fn main() -> Result<(), Box<dyn core::error::Error>> {
-    set_log_level_from_env_or(LogLevel::Trace);
+    set_log_level_from_env_or(LogLevel::Info);
     let node = NodeBuilder::new().create::<ipc::Service>()?;
     type KeyType = u32;
-    let key = 99;
+    const INTERESTING_KEY: u32 = 1;
 
     let service = node
         .service_builder(&"My/Funk/ServiceName".try_into()?)
@@ -30,19 +30,22 @@ fn main() -> Result<(), Box<dyn core::error::Error>> {
         .service_builder(&"My/Funk/ServiceName".try_into()?)
         .event()
         .open_or_create()?;
-    let notifier = event_service.notifier_builder().create()?;
-
-    let writer = service.writer_builder().create()?;
-    let writer_handle = writer.entry::<u64>(&key)?;
-
-    // notify with entry id
-    let mut counter: u64 = 0;
-    while node.wait(CYCLE_TIME).is_ok() {
-        counter += 1;
-        writer_handle.update_with_copy(counter);
-        notifier.notify_with_custom_event_id(writer_handle.entry_id())?;
-
-        println!("Trigger event with entry id...");
+    let listener = event_service.listener_builder().create()?;
+
+    let reader = service.reader_builder().create()?;
+    let reader_handle = reader.entry::<u64>(&INTERESTING_KEY)?;
+
+    // wait for entry id
+    while node.wait(Duration::ZERO).is_ok() {
+        if let Ok(Some(id)) = listener.timed_wait_one(CYCLE_TIME) {
+            if id == reader_handle.entry_id() {
+                println!(
+                    "read: {} for entry id {}",
+                    reader_handle.get(),
+                    id.as_value()
+                );
+            }
+        }
     }
 
     println!("exit");