[#264] pubsub

.clang-tidy

@@ -52,7 +52,7 @@ CheckOptions:
   - { key: readability-identifier-naming.MemberCase,              value: lower_case }
   - { key: readability-identifier-naming.ParameterCase,           value: lower_case }
   - { key: readability-identifier-naming.VariableCase,            value: lower_case }
-  - { key: readability-identifier-naming.PublicMemberPrefix,      value:  }
+  - { key: readability-identifier-naming.PublicMemberPrefix,      value: "" }
   - { key: readability-identifier-naming.PrivateMemberPrefix,     value: m_ }
   - { key: readability-identifier-naming.ProtectedMemberPrefix,   value: m_ }
   - { key: readability-identifier-naming.MacroDefinitionPrefix,   value: IOX2_ }

examples/README.md

@@ -48,8 +48,8 @@ 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                            | [Rust](rust/discovery) | List all available services in a system. |
 | docker                               | [all](rust/docker) | Communicate between different docker containers and the host. |
-| event                                | [C++](cxx/event) [Rust](rust/event) | Push notifications - send event signals to wakeup processes that are waiting for them.|
-| publish subscribe                    | [Rust](rust/publish_subscribe) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern). |
+| 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. |
 | publish subscribe with user header   | [Rust](rust/publish_subscribe_with_user_header) | Add a user header to the payload (samples) to transfer additional information. |
 | service attributes                   | [Rust](rust/service_attributes) | Creates a service with custom attributes that are available to every endpoint. If the attributes are not compatible the service will not open. |

examples/c/CMakeLists.txt

@@ -14,4 +14,5 @@ cmake_minimum_required(VERSION 3.22)
 project(examples_c LANGUAGES C)
 
 add_subdirectory(discovery)
+add_subdirectory(event)
 add_subdirectory(publish_subscribe)

examples/c/event/CMakeLists.txt

@@ -0,0 +1,22 @@
+# 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_c_event LANGUAGES C)
+
+find_package(iceoryx2-c 0.3.0 REQUIRED)
+
+add_executable(example_c_event_listener src/listener.c)
+target_link_libraries(example_c_event_listener iceoryx2-c::static-lib)
+
+add_executable(example_c_event_notifier src/notifier.c)
+target_link_libraries(example_c_event_notifier iceoryx2-c::static-lib)

examples/c/event/README.md

@@ -0,0 +1,43 @@
+# Event
+
+## Running The Example
+
+This example offers a practical demonstration of inter-process event signaling
+in iceoryx2. It showcases how one process can signal an event to another
+process, allowing for efficient communication.
+
+In this scenario, the 'listener' process waits for incoming events. When an
+event arrives, it promptly awakens and reports the [`EventId`] of the received
+event. On the other end, the 'notifier' process periodically sends notifications
+with an incrementing `EventId` every second.
+
+First you have to build the C examples:
+
+```sh
+cmake -S . -B target/ffi/build -DBUILD_EXAMPLES=ON
+cmake --build target/ffi/build
+```
+
+To see this in action, open two separate terminals and run the following
+commands:
+
+**Terminal 1**
+
+```sh
+./target/ffi/build/examples/c/event/example_c_event_listener
+```
+
+**Terminal 2**
+
+```sh
+./target/ffi/build/examples/c/event/example_c_event_notifier
+```
+
+Feel free to run multiple listeners or notifiers concurrently to observe how
+iceoryx2 efficiently handles event signaling across processes.
+
+You may hit the maximum supported number of ports when too many listener or
+notifier processes run. Take a look at the [iceoryx2 config](../../../config) to set the
+limits globally or at the
+[API of the Service builder](https://docs.rs/iceoryx2/latest/iceoryx2/service/index.html)
+to set them for a single service.

examples/c/event/src/listener.c

@@ -0,0 +1,81 @@
+// 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 "iox2/iceoryx2.h"
+
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+int main(void) {
+    // create new node
+    iox2_node_builder_h node_builder_handle = iox2_node_builder_new(NULL);
+    iox2_node_h node_handle = NULL;
+    if (iox2_node_builder_create(node_builder_handle, NULL, iox2_service_type_e_IPC, &node_handle) != IOX2_OK) {
+        printf("Could not create node!\n");
+        goto end;
+    }
+
+    // create service name
+    const char* service_name_value = "MyEventName";
+    iox2_service_name_h service_name = NULL;
+    if (iox2_service_name_new(NULL, service_name_value, strlen(service_name_value), &service_name) != IOX2_OK) {
+        printf("Unable to create service name!\n");
+        goto drop_node;
+    }
+
+    // create service
+    iox2_service_name_ptr service_name_ptr = iox2_cast_service_name_ptr(service_name);
+    iox2_node_ref_h node_ref_handle = iox2_cast_node_ref_h(node_handle);
+    iox2_service_builder_h service_builder = iox2_node_service_builder(node_ref_handle, NULL, service_name_ptr);
+    iox2_service_builder_event_h service_builder_event = iox2_service_builder_event(service_builder);
+    iox2_port_factory_event_h service = NULL;
+    if (iox2_service_builder_event_open_or_create(service_builder_event, NULL, &service) != IOX2_OK) {
+        printf("Unable to create service!\n");
+        goto drop_node;
+    }
+
+    // create listener
+    iox2_port_factory_event_ref_h ref_service = iox2_cast_port_factory_event_ref_h(service);
+    iox2_port_factory_listener_builder_h listener_builder = iox2_port_factory_event_listener_builder(ref_service, NULL);
+    iox2_listener_h listener = NULL;
+    if (iox2_port_factory_listener_builder_create(listener_builder, NULL, &listener) != IOX2_OK) {
+        printf("Unable to create listener!\n");
+        goto drop_service;
+    }
+    iox2_listener_ref_h listener_ref = iox2_cast_listener_ref_h(listener);
+    iox2_event_id_t event_id;
+
+    while (iox2_node_wait(node_ref_handle, 0, 0) == iox2_node_event_e_TICK) {
+        bool has_received_one = false;
+        if (iox2_listener_timed_wait_one(listener_ref, &event_id, &has_received_one, 1, 0) != IOX2_OK) {
+            printf("Unable to wait for notification!\n");
+            goto drop_listener;
+        }
+
+        if (has_received_one) {
+            printf("event was triggered with id: %lu\n", event_id.value);
+        }
+    }
+
+drop_listener:
+    iox2_listener_drop(listener);
+
+drop_service:
+    iox2_port_factory_event_drop(service);
+
+drop_node:
+    iox2_node_drop(node_handle);
+
+end:
+    return 0;
+}

examples/c/event/src/notifier.c

@@ -0,0 +1,90 @@
+// 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 "iox2/iceoryx2.h"
+
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#ifdef _WIN64
+#include <windows.h>
+#define sleep Sleep
+#else
+#include <unistd.h>
+#endif
+
+int main(void) {
+    // create new node
+    iox2_node_builder_h node_builder_handle = iox2_node_builder_new(NULL);
+    iox2_node_h node_handle = NULL;
+    if (iox2_node_builder_create(node_builder_handle, NULL, iox2_service_type_e_IPC, &node_handle) != IOX2_OK) {
+        printf("Could not create node!\n");
+        goto end;
+    }
+
+    // create service name
+    const char* service_name_value = "MyEventName";
+    iox2_service_name_h service_name = NULL;
+    if (iox2_service_name_new(NULL, service_name_value, strlen(service_name_value), &service_name) != IOX2_OK) {
+        printf("Unable to create service name!\n");
+        goto drop_node;
+    }
+
+    // create service
+    iox2_service_name_ptr service_name_ptr = iox2_cast_service_name_ptr(service_name);
+    iox2_node_ref_h node_ref_handle = iox2_cast_node_ref_h(node_handle);
+    iox2_service_builder_h service_builder = iox2_node_service_builder(node_ref_handle, NULL, service_name_ptr);
+    iox2_service_builder_event_h service_builder_event = iox2_service_builder_event(service_builder);
+    iox2_port_factory_event_h service = NULL;
+    if (iox2_service_builder_event_open_or_create(service_builder_event, NULL, &service) != IOX2_OK) {
+        printf("Unable to create service!\n");
+        goto drop_node;
+    }
+
+    // create notifier
+    iox2_port_factory_event_ref_h ref_service = iox2_cast_port_factory_event_ref_h(service);
+    iox2_port_factory_notifier_builder_h notifier_builder = iox2_port_factory_event_notifier_builder(ref_service, NULL);
+    iox2_notifier_h notifier = NULL;
+    if (iox2_port_factory_notifier_builder_create(notifier_builder, NULL, &notifier) != IOX2_OK) {
+        printf("Unable to create notifier!\n");
+        goto drop_service;
+    }
+    iox2_notifier_ref_h notifier_ref = iox2_cast_notifier_ref_h(notifier);
+    iox2_event_id_t event_id;
+
+    uint64_t counter = 0;
+    while (iox2_node_wait(node_ref_handle, 0, 0) == iox2_node_event_e_TICK) {
+        counter += 1;
+        iox2_event_id_t event_id = { .value = counter % 12 }; // NOLINT
+        if (iox2_notifier_notify_with_custom_event_id(notifier_ref, &event_id, NULL) != IOX2_OK) {
+            printf("Failed to notify listener!\n");
+            goto drop_notifier;
+        }
+
+        printf("Trigger event with id %lu ...\n", (long unsigned) event_id.value);
+
+        sleep(1);
+    }
+
+drop_notifier:
+    iox2_notifier_drop(notifier);
+
+drop_service:
+    iox2_port_factory_event_drop(service);
+
+drop_node:
+    iox2_node_drop(node_handle);
+
+end:
+    return 0;
+}

examples/c/publish_subscribe/README.md

@@ -0,0 +1,42 @@
+# Publish-Subscribe
+
+## Running The Example
+
+This example illustrates a robust publisher-subscriber communication
+pattern between two separate processes. The publisher sends two
+messages every second, each containing [`TransmissionData`]. On the
+receiving end, the subscriber checks for new data every second.
+
+The subscriber is printing the sample on the console whenever new data arrives.
+
+First you have to build the C examples:
+
+```sh
+cmake -S . -B target/ffi/build -DBUILD_EXAMPLES=ON
+cmake --build target/ffi/build
+```
+
+To observe this dynamic communication in action, open two separate terminals
+and execute the following commands:
+
+**Terminal 1**
+
+```sh
+./target/ffi/build/examples/c/publish_subscribe/example_c_publish_subscribe_subscriber
+```
+
+**Terminal 2**
+
+```sh
+./target/ffi/build/examples/c/publish_subscribe/example_c_publish_subscribe_publisher
+```
+
+Feel free to run multiple instances of publisher or subscriber processes
+simultaneously to explore how iceoryx2 handles publisher-subscriber communication
+efficiently.
+
+You may hit the maximum supported number of ports when too many publisher or
+subscriber processes run. Take a look at the [iceoryx2 config](../../../config) to set the
+limits globally or at the
+[API of the Service builder](https://docs.rs/iceoryx2/latest/iceoryx2/service/index.html)
+to set them for a single service.