diff --git a/FAQ.md b/FAQ.md index 7743886e3..406bc0d48 100644 --- a/FAQ.md +++ b/FAQ.md @@ -4,18 +4,18 @@ iceoryx2 stores all data in shared memory, which imposes certain restrictions. Only data that is self-contained and does not use pointers to reference itself -is allowed. This is because shared memory is mapped at different offsets in -each process, rendering absolute pointers invalid. Additionally, if the data +is allowed. This is because shared memory is mapped at different offsets in each +process, rendering absolute pointers invalid. Additionally, if the data structure uses the heap, it is stored locally within a process and cannot be -accessed by other processes. As a result, data types such as `String`, `Vec`, -or `HashMap` cannot be used as payload types. +accessed by other processes. As a result, data types such as `String`, `Vec`, or +`HashMap` cannot be used as payload types. Additionally, every data type must be annotated with `#[repr(C)]`. The Rust compiler may reorder the members of a struct, which can lead to undefined behavior if another process expects a different ordering. -To address this, iceoryx2 provides shared-memory-compatible data types. You -can refer to the [complex data types example](examples/rust/complex_data_types), +To address this, iceoryx2 provides shared-memory-compatible data types. You can +refer to the [complex data types example](examples/rust/complex_data_types), which demonstrates the use of `FixedSizeByteString` and `FixedSizeVec`. ## How To Define Custom Data Types (Rust) @@ -58,12 +58,10 @@ insufficient, a new publisher with a larger `max_slice_len` can be created. -> [!IMPORTANT] -> Be aware that the history of the old publisher is lost when it is +> [!IMPORTANT] Be aware that the history of the old publisher is lost when it is > removed. -> [!NOTE] -> We are also working on an API that does not require the user to +> [!NOTE] We are also working on an API that does not require the user to > explicitly create a new publisher whenever the memory is insufficient. It > would also solve the history issue. @@ -71,11 +69,11 @@ insufficient, a new publisher with a larger `max_slice_len` can be created. ## How To Make 32-bit and 64-bit iceoryx2 Applications Interoperatable -This is currently not possible since we cannot guarantee to have the same -layout of the data structures in the shared memory. On 32-bit architectures -64-bit POD are aligned to a 4 byte boundary but to a 8 byte boundary on -64-bit architectures. Some additional work is required to make 32-bit and -64-bit applications interoperabel. +This is currently not possible since we cannot guarantee to have the same layout +of the data structures in the shared memory. On 32-bit architectures 64-bit POD +are aligned to a 4 byte boundary but to a 8 byte boundary on 64-bit +architectures. Some additional work is required to make 32-bit and 64-bit +applications interoperabel. ## My Transmission Type Is Too Large, Encounter Stack Overflow On Initialization @@ -89,8 +87,8 @@ than the available stack size. ## 100% CPU Load When Using The WaitSet The WaitSet wakes up whenever an attachment, such as a `Listener` or a `socket`, -has something to read. If you do not handle all notifications, for example, -with `Listener::try_wait_one()`, the WaitSet will wake up immediately again, +has something to read. If you do not handle all notifications, for example, with +`Listener::try_wait_one()`, the WaitSet will wake up immediately again, potentially causing an infinite loop and resulting in 100% CPU usage. ## Does iceoryx2 Offer an Async API? @@ -123,17 +121,31 @@ But you can also use a crate like [ctrlc](https://docs.rs/ctrlc/latest/ctrlc/). ## How to use `log` or `tracing` as default log backend * **log**, add the feature flag `logger_log` to the dependency in `Cargo.toml` - ```toml - iceoryx2 = { version = "0.1.0", features = ["logger_log"]} - ``` + ```toml + iceoryx2 = { version = "0.1.0", features = ["logger_log"]} + ``` * **tracing**, add the feature flag `logger_tracing` to the dependency in `Cargo.toml` - ```toml - iceoryx2 = { version = "0.1.0", features = ["logger_tracing"]} - ``` + ```toml + iceoryx2 = { version = "0.1.0", features = ["logger_tracing"]} + ``` + +## Supported log levels + +iceoryx2 support different log levels +`Trace, Debug, Info, Warning, Error, Fatal` ## How to set the log level +iceoryx2 gets its default logging level from `.cargo/config.toml` , but this can +be over ridden by environment variable `IOX2_LOG_LEVEL` the developer can set +this environment variable with one of the supported levels. + +`export IOX2_LOG_LEVEL=Trace` + +Developers can also set the logging level from within the code which will take +precedence over the environment variable: + ```rust use iceoryx2::prelude::* @@ -144,10 +156,10 @@ set_log_level(LogLevel::Trace); ## A crash leads to the failure `PublishSubscribeOpenError(UnableToOpenDynamicServiceInformation)` -When an application crashes, some resources may remain in the system and need -to be cleaned up. This issue is detected whenever a new iceoryx2 instance is -created, removed, or when someone opens the service that the crashed process -had previously opened. On the command line, you may see a message like this: +When an application crashes, some resources may remain in the system and need to +be cleaned up. This issue is detected whenever a new iceoryx2 instance is +created, removed, or when someone opens the service that the crashed process had +previously opened. On the command line, you may see a message like this: ```ascii 6 [W] "Node::::cleanup_dead_nodes()" @@ -157,9 +169,9 @@ had previously opened. On the command line, you may see a message like this: ``` However, for successful cleanup, the process attempting the cleanup must have -sufficient permissions to remove the stale resources of the dead process. If -the cleanup fails due to insufficient permissions, the process that attempted -the cleanup will continue without removing the resources. +sufficient permissions to remove the stale resources of the dead process. If the +cleanup fails due to insufficient permissions, the process that attempted the +cleanup will continue without removing the resources. Generally, it is not necessary to manually clean up these resources, as other processes should detect and handle the cleanup when creating or removing nodes, @@ -169,6 +181,7 @@ Nevertheless, there are three different approaches to initiate stale resource cleanup: 1. **Using the iceoryx2 API**: + ```rust Node::::list(Config::global_config(), |node_state| { if let NodeState::::Dead(view) = node_state { @@ -184,6 +197,6 @@ cleanup: 2. **Using the command line tool**: `iox2 node -h` (NOT YET IMPLEMENTED) 3. **Manual cleanup**: Stop all running services and remove all shared memory - files with the `iox2` prefix from: + files with the `iox2` prefix from: * POSIX: `/dev/shm/`, `/tmp/iceoryx2` * Windows: `c:\Temp\iceoryx2` diff --git a/doc/release-notes/iceoryx2-unreleased.md b/doc/release-notes/iceoryx2-unreleased.md index 4ed69e61b..714d8f65e 100644 --- a/doc/release-notes/iceoryx2-unreleased.md +++ b/doc/release-notes/iceoryx2-unreleased.md @@ -36,11 +36,16 @@ conflicts when merging. --> -* Rename `NodeEvent` into `WaitEvent` [#390](https://github.com/eclipse-iceoryx/iceoryx2/issues/390) -* Bazel support for the Rust crates [#349](https://github.com/eclipse-iceoryx/iceoryx2/issues/349) -* Remove ACL dependency [#457](https://github.com/eclipse-iceoryx/iceoryx2/issues/457) -* Publish Subscribe Header contains number of elements contained in a `Sample` [#498](https://github.com/eclipse-iceoryx/iceoryx2/issues/498) -* Read LogLevel from environment variable [#396](https://github.com/eclipse-iceoryx/iceoryx2/issues/396) +* Rename `NodeEvent` into `WaitEvent` + [#390](https://github.com/eclipse-iceoryx/iceoryx2/issues/390) +* Bazel support for the Rust crates + [#349](https://github.com/eclipse-iceoryx/iceoryx2/issues/349) +* Remove ACL dependency + [#457](https://github.com/eclipse-iceoryx/iceoryx2/issues/457) +* Publish Subscribe Header contains number of elements contained in a `Sample` + [#498](https://github.com/eclipse-iceoryx/iceoryx2/issues/498) +* Read LogLevel from environment variable + [#396](https://github.com/eclipse-iceoryx/iceoryx2/issues/396) ### Workflow diff --git a/iceoryx2-bb/log/src/lib.rs b/iceoryx2-bb/log/src/lib.rs index ee626ccd6..8dde04043 100644 --- a/iceoryx2-bb/log/src/lib.rs +++ b/iceoryx2-bb/log/src/lib.rs @@ -150,7 +150,6 @@ use std::{ sync::{atomic::Ordering, Once}, }; -use logger::Logger; use once_cell::sync::Lazy; use std::env; @@ -170,7 +169,7 @@ pub static ENV_LOG_LEVEL: Lazy = Lazy::new(|| { .unwrap_or(LogLevel::Info) }); -static mut LOGGER: Option<&'static dyn logger::Logger> = None; +static mut LOGGER: Option<&'static dyn Log> = None; static LOG_LEVEL: IoxAtomicU8 = IoxAtomicU8::new(DEFAULT_LOG_LEVEL as u8); static INIT_LOGGER: Once = Once::new(); static INIT_LOG_LEVEL: Once = Once::new(); @@ -240,8 +239,8 @@ pub fn set_logger(value: &'static T) -> bool { /// Returns a reference to the [`Log`]ger. pub fn get_logger() -> &'static dyn Log { - INIT.call_once(|| { - unsafe { LOGGER = Some(&DEFAULT_LOGGER) }; + INIT_LOGGER.call_once(|| { + unsafe { LOGGER = Some(&*DEFAULT_LOGGER) }; }); // # From The Compiler