Merge pull request #216 from elBoberido/iox2-210-restructure-examples

[#210] Restructure examples

BEST_PRACTICES.md

@@ -24,7 +24,7 @@
 ### Error Handling
 
  * Never return `Err(...)`, always use `fail!` macro.
-   * Iceoryx2 shall always log a message to `DEBUG` whenever an `Err(...)` is.
+   * iceoryx2 shall always log a message to `DEBUG` whenever an `Err(...)` is.
    * When providing for instance `self` as origin, the current state of the object that caused the
      problem is logged.
 
@@ -50,7 +50,7 @@
 ### Fatal Error Handling
 
  * Never call `panic!(...)` directly, always use the `fatal_panic!` macro.
-   * Iceoryx2 shall always log a message to `FATAL` whenever a panic occurs.
+   * iceoryx2 shall always log a message to `FATAL` whenever a panic occurs.
    * When providing for instance `self` as origin, the current state of the object that caused the
      problem is logged.
 

Cargo.toml

@@ -26,7 +26,7 @@ members = [
 
 [workspace.package]
 categories = ["network-programming"]
-description = "Iceoryx2: Lock-Free Zero-Copy Interprocess Communication"
+description = "iceoryx2: Lock-Free Zero-Copy Interprocess Communication"
 edition = "2021"
 homepage = "https://iceoryx.io"
 keywords = ["zero-copy", "communication", "ipc", "inter-process", "publish-subscribe", "request-response", "shmem", "shared-memory", "shared_memory", "shared"]

FAQ.md

@@ -3,7 +3,7 @@
 ## How To Send Data Where The Size Is Unknown At Compilation-Time?
 
 Take a look at the
-[publish-subscribe dynamic data size example](examples/examples/publish_subscribe_dynamic_data_size).
+[publish-subscribe dynamic data size example](examples/rust/publish_subscribe_dynamic_data_size).
 
 The idea is to create a service based on a slice and define at runtime a `max_slice_len`. Then
 samples up to a length of the max slice length can be allocated with `loan_slice{_uninit}`. When it
@@ -28,7 +28,7 @@ go out of scope. This is not the case when the application is:
 
 iceoryx2 already provides a mechanism that registers a signal handler that
 handles termination requests gracefully, see
-[publish subscribe example](examples/examples/publish_subscribe) and
+[publish subscribe example](examples/rust/publish_subscribe) and
 
 ```rust
 while let Iox2Event::Tick = Iox2::wait(CYCLE_TIME) {

README.md

@@ -26,30 +26,30 @@
 
 ## Introduction
 
-Welcome to Iceoryx2, the efficient, and ultra-low latency inter-process communication
+Welcome to iceoryx2, the efficient, and ultra-low latency inter-process communication
 middleware. This library is designed to provide you with fast and reliable
 zero-copy and lock-free inter-process communication mechanisms.
 
-Iceoryx2 is all about providing a seamless experience for inter-process
+iceoryx2 is all about providing a seamless experience for inter-process
 communication, featuring versatile messaging patterns. Whether you're diving
 into publish-subscribe, events, or the promise of upcoming features like
-request-response, pipelines, and blackboard, Iceoryx2 has you covered.
+request-response, pipelines, and blackboard, iceoryx2 has you covered.
 
-One of the features of Iceoryx2 is its consistently low transmission latency
+One of the features of iceoryx2 is its consistently low transmission latency
 regardless of payload size, ensuring a predictable and reliable
 communication experience.
 
-Iceoryx2's origins can be traced back to
+iceoryx2's origins can be traced back to
 [iceoryx](https://github.com/eclipse-iceoryx/iceoryx). By overcoming past
-technical debts and refining the architecture, Iceoryx2 enables the modularity
+technical debts and refining the architecture, iceoryx2 enables the modularity
 we've always desired.
 
-In the near future, Iceoryx2 is poised to support at least the same feature set
+In the near future, iceoryx2 is poised to support at least the same feature set
 and platforms as [iceoryx](https://github.com/eclipse-iceoryx/iceoryx),
 ensuring a seamless transition and offering enhanced
 capabilities for your inter-process communication needs. So, if you're looking
 for lightning-fast, cross-platform communication that doesn't compromise on
-performance or modularity, Iceoryx2 is your answer.
+performance or modularity, iceoryx2 is your answer.
 
 ## Performance
 
@@ -131,7 +131,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 ```
 
 This example is a simplified version of the
-[publish-subscribe example](examples/examples/publish_subscribe/). You can
+[publish-subscribe example](examples/rust/publish_subscribe/). You can
 execute it by opening two terminals and calling:
 
 **Terminal 1:**
@@ -236,7 +236,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 ```
 
 This example is a simplified version of the
-[event example](examples/examples/event/). You can
+[event example](examples/rust/event/). You can
 execute it by opening two terminals and calling:
 
 **Terminal 1:**

ROADMAP.md

@@ -54,7 +54,7 @@
 
 ## Microservices (Quality of Life Improvements)
 
-### Iceoryx Tooling
+### iceoryx Tooling
 
 * [ ] Service Discovery
 * [ ] Introspection Service

config/README.md

@@ -1,8 +1,8 @@
-# Iceoryx2 Global Configuration
+# iceoryx2 Global Configuration
 
 For streamlined multi-instance operation and interference-free communication,
-Iceoryx2 introduces global configuration settings. It enables the concurrent
-execution of multiple Iceoryx2 setups on the same machine or within a single
+iceoryx2 introduces global configuration settings. It enables the concurrent
+execution of multiple iceoryx2 setups on the same machine or within a single
 process by employing distinct configurations.
 
 ## Sections
@@ -18,8 +18,8 @@ Adjusting `global` settings ensures a non-interfering setup.
 
 ### Global
 
- * `global.root_path_{unix|windows}` - [string]: Defines the path for all Iceoryx2 files and directories.
- * `global.prefix` - [string]: Prefix that is used for every file Iceoryx2 creates.
+ * `global.root_path_{unix|windows}` - [string]: Defines the path for all iceoryx2 files and directories.
+ * `global.prefix` - [string]: Prefix that is used for every file iceoryx2 creates.
  * `global.service.directory` - [string]: Specifies the path for service-related files under `global.root_path`.
  * `global.service.publisher_data_segment_suffix` - [string]: Suffix added to the publisher's data segment.
  * `global.service.static_config_storage_suffix` - [string]: Suffix for static service configuration files.

doc/announcements/initial_announcement.md

@@ -5,7 +5,7 @@ and to announce the release of iceoryx generation 2, crafted entirely in
 Rust. As one of the main developers of iceoryx, this journey commenced over a
 year ago as a personal side project.
 
-Iceoryx2, or iceoryx generation 2, is poised to inherit all the familiar
+iceoryx2, or iceoryx generation 2, is poised to inherit all the familiar
 features you've come to rely on from its predecessor. In its initial release,
 expect support for publish-subscribe, service discovery, and dedicated event
 messaging — all without the need for a central broker (RouDi).
@@ -85,7 +85,7 @@ causing frustration.
 Why dwell in the abstract when we can scrutinize a real-world example, comparing
 iceoryx (C++) to iceoryx2 (Rust)? Brace yourself for a journey into a future where
 Rust takes the lead in inter-process zero-copy communication within our specialized
-domain. Iceoryx2 is not just an upgrade — it's a leap forward into a safer, more
+domain. iceoryx2 is not just an upgrade — it's a leap forward into a safer, more
 efficient era.
 
 ## Example: Sending Data

examples/Cargo.toml

@@ -15,47 +15,47 @@ iceoryx2 = { workspace = true }
 iceoryx2-bb-container = { workspace = true }
 
 [lib]
-name = "transmission_data"
-path = "src/transmission_data.rs"
+name = "examples_common"
+path = "rust/_examples_common/lib.rs"
 
 # complex data types
 
 [[example]]
 name = "complex_data_types"
-path = "examples/complex_data_types/complex_data_types.rs"
+path = "rust/complex_data_types/complex_data_types.rs"
 
 # discovery
 
 [[example]]
 name = "discovery"
-path = "examples/discovery/discovery.rs"
+path = "rust/discovery/discovery.rs"
 
 # event
 
 [[example]]
 name = "event_listener"
-path = "examples/event/listener.rs"
+path = "rust/event/listener.rs"
 
 [[example]]
 name = "event_notifier"
-path = "examples/event/notifier.rs"
+path = "rust/event/notifier.rs"
 
 # publish_subscribe
 
 [[example]]
 name = "publish_subscribe_publisher"
-path = "examples/publish_subscribe/publisher.rs"
+path = "rust/publish_subscribe/publisher.rs"
 
 [[example]]
 name = "publish_subscribe_subscriber"
-path = "examples/publish_subscribe/subscriber.rs"
+path = "rust/publish_subscribe/subscriber.rs"
 
 # publish_subscribe_dynamic_data
 
 [[example]]
 name = "publish_subscribe_dyn_publisher"
-path = "examples/publish_subscribe_dynamic_data/publisher.rs"
+path = "rust/publish_subscribe_dynamic_data/publisher.rs"
 
 [[example]]
 name = "publish_subscribe_dyn_subscriber"
-path = "examples/publish_subscribe_dynamic_data/subscriber.rs"
+path = "rust/publish_subscribe_dynamic_data/subscriber.rs"

examples/README.md

@@ -1,15 +1,15 @@
 # Examples
 
-## Foundations of Communication in Iceoryx2 Applications
+## Foundations of Communication in iceoryx2 Applications
 
-In the world of Iceoryx2, communication is at the core of everything. To
+In the world of iceoryx2, communication is at the core of everything. To
 facilitate seamless communication, we always begin by opening or creating a
-service, the fundamental building block of an Iceoryx2 application. Services
+service, the fundamental building block of an iceoryx2 application. Services
 serve as the conduit through which different parts of your application
 interact.
 
 The type of service you create is defined by a messaging pattern, which
-dictates how data flows between participants. Iceoryx2 supports various
+dictates how data flows between participants. iceoryx2 supports various
 messaging patterns, including:
 
 * **Publish-Subscribe:** In this pattern, a publisher sends a continuous stream
@@ -38,10 +38,10 @@ they interact and exchange data.
 
 | Name | Description |
 |------|-------------|
-| [complex data types](examples/complex_data_types) | Send zero-copy compatible versions of `Vec`, `String`, .... |
-| [discovery](examples/discovery) | List all available services in a system. |
-| [docker](examples/docker) | Communicate between different docker containers and the host. |
-| [event](examples/event) | Exchanging event signals between multiple processes.|
-| [publish subscribe](examples/publish_subscribe) | Communication between multiple processes with a [publish subscribe messaging pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern). |
-| [publish subscribe dynamic data](examples/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. |
+| [complex data types](rust/complex_data_types) | Send zero-copy compatible versions of `Vec`, `String`, .... |
+| [discovery](rust/discovery) | List all available services in a system. |
+| [docker](rust/docker) | Communicate between different docker containers and the host. |
+| [event](rust/event) | Exchanging event signals between multiple processes.|
+| [publish subscribe](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/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/rust/_examples_common/lib.rs

@@ -0,0 +1,14 @@
+// Copyright (c) 2023 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
+
+mod transmission_data;
+pub use transmission_data::TransmissionData;

examples/examples/discovery/README.md → examples/rust/discovery/README.md

@@ -2,7 +2,7 @@
 
 ## Running The Example
 
-This example demonstrates how to list all active services within your Iceoryx2
+This example demonstrates how to list all active services within your iceoryx2
 application. To get the most out of this example, you can combine it with other
 examples, such as the [event example](../event/) or the
 [publish-subscribe example](../publish_subscribe/), to see active services in
@@ -31,4 +31,4 @@ cargo run --example discovery
 
 This will display the static service details of both the event and the
 publish-subscribe service, giving you a comprehensive view of the active
-services in your Iceoryx2 application.
+services in your iceoryx2 application.

examples/examples/docker/README.md → examples/rust/docker/README.md

@@ -1,4 +1,4 @@
-# Using Iceoryx2 in A Docker Environment
+# Using iceoryx2 in A Docker Environment
 
 ## Introduction
 
@@ -30,7 +30,7 @@ the host.
 
 ## Requirements
 
-Iceoryx2 discovers services by parsing the service toml files in the
+iceoryx2 discovers services by parsing the service toml files in the
 `/tmp/iceoryx2` directory and communicates via shared memory that is located
 in `/dev/shm`. If both directories are available in every docker container and
 are shared with the host, iceoryx2 can establish a connection between them.
@@ -48,7 +48,7 @@ cargo build --example publish_subscribe_subscriber
 ```
 
 Create the directory `/tmp/iceoryx2` so that it can be mounted into the docker
-container. Iceoryx2 creates it automatically but in our case we start the
+container. iceoryx2 creates it automatically but in our case we start the
 container before we start iceoryx2, therefore we have to create it manually.
 
 ```sh

examples/examples/event/README.md → examples/rust/event/README.md

@@ -27,4 +27,4 @@ cargo run --example event_notifier
 ```
 
 Feel free to run multiple listeners or notifiers concurrently to observe how
-Iceoryx2 efficiently handles event signaling across processes.
+iceoryx2 efficiently handles event signaling across processes.

examples/examples/publish_subscribe/README.md → examples/rust/publish_subscribe/README.md

@@ -25,11 +25,11 @@ cargo run --example publish_subscribe_publisher
 ```
 
 Feel free to run multiple instances of publisher or subscriber processes
-simultaneously to explore how Iceoryx2 handles publisher-subscriber communication
+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.
+to set them for a single service.

examples/examples/publish_subscribe/publisher.rs → examples/rust/publish_subscribe/publisher.rs

@@ -11,8 +11,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 use core::time::Duration;
+use examples_common::TransmissionData;
 use iceoryx2::prelude::*;
-use transmission_data::TransmissionData;
 
 const CYCLE_TIME: Duration = Duration::from_secs(1);
 

examples/examples/publish_subscribe/subscriber.rs → examples/rust/publish_subscribe/subscriber.rs

@@ -11,8 +11,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
 use core::time::Duration;
+use examples_common::TransmissionData;
 use iceoryx2::prelude::*;
-use transmission_data::TransmissionData;
 
 const CYCLE_TIME: Duration = Duration::from_secs(1);
 

iceoryx2/src/config.rs

@@ -233,9 +233,9 @@ pub struct Event {
     pub event_id_max_value: usize,
 }
 
-/// Represents the configuration that Iceoryx2 will utilize. It is divided into two sections:
-/// the [Global] settings, which must align with the Iceoryx2 instance the application intends to
-/// join, and the [Defaults] for communication within that Iceoryx2 instance. The user has the
+/// Represents the configuration that iceoryx2 will utilize. It is divided into two sections:
+/// the [Global] settings, which must align with the iceoryx2 instance the application intends to
+/// join, and the [Defaults] for communication within that iceoryx2 instance. The user has the
 /// flexibility to override both sections.
 #[non_exhaustive]
 #[derive(Serialize, Deserialize, Debug, Clone)]

iceoryx2/src/lib.rs

@@ -10,12 +10,12 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! # Iceoryx2
+//! # iceoryx2
 //!
-//! Iceoryx2 is a cutting-edge service-oriented zero-copy lock-free inter-process communication
+//! iceoryx2 is a cutting-edge service-oriented zero-copy lock-free inter-process communication
 //! middleware. Designed to support various
 //! [`MessagingPattern`](crate::service::messaging_pattern::MessagingPattern)s
-//! Iceoryx2 empowers developers with
+//! iceoryx2 empowers developers with
 //! the flexibility of:
 //!
 //! - Publish-Subscribe
@@ -36,9 +36,9 @@
 //! on the same machine or even within the same process without interference. This versatility
 //! allows iceoryx2 to seamlessly integrate with other frameworks simultaneously.
 //!
-//! Iceoryx2 traces its lineage back to the
+//! iceoryx2 traces its lineage back to the
 //! [eclipse iceoryx](https://github.com/eclipse-iceoryx/iceoryx) project, addressing a major
-//! drawback – the central daemon. Iceoryx2 embraces a fully decentralized architecture,
+//! drawback – the central daemon. iceoryx2 embraces a fully decentralized architecture,
 //! eliminating the need for a central daemon entirely.
 //!
 //! # Examples
@@ -267,7 +267,7 @@
 //!
 //! # Custom Configuration
 //!
-//! Iceoryx2 offers the flexibility to configure default quality of service settings, paths, and
+//! iceoryx2 offers the flexibility to configure default quality of service settings, paths, and
 //! file suffixes through a custom configuration file.
 //!
 //! For in-depth details and examples, please visit the