iceoryx2_bb_container/
lib.rs

1// Copyright (c) 2023 Contributors to the Eclipse Foundation
2//
3// See the NOTICE file(s) distributed with this work for additional
4// information regarding copyright ownership.
5//
6// This program and the accompanying materials are made available under the
7// terms of the Apache Software License 2.0 which is available at
8// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
9// which is available at https://opensource.org/licenses/MIT.
10//
11// SPDX-License-Identifier: Apache-2.0 OR MIT
12
13#![no_std]
14#![warn(clippy::alloc_instead_of_core)]
15#![warn(clippy::std_instead_of_alloc)]
16#![warn(clippy::std_instead_of_core)]
17#![warn(missing_docs)]
18
19//! # iceoryx2 Building Blocks (BB) Container
20//!
21//! This is a support library for iceoryx2 which comes with containers that are
22//! compatible with shared memory and can be used to construct custom payload types for
23//! inter-process communication.
24//!
25//! Most containers come in 3 variations:
26//!  1. `FixedSize*Container*`, compile-time fixed size version. The capacity must be known at compile
27//!     time. Those fixed-size constructs are always self-contained, meaning that the required
28//!     memory is part of the constructs and usually stored in some kind of array.
29//!  2. `Relocatable*Container*`, run-time fixed size version that is shared memory compatible. The
30//!     capacity must be known when the object is created. **This object is not movable!**
31//!  3. `*Container*`, run-time fixed size version that is **not** shared memory compatible but can be
32//!     moved. The memory is by default stored on the heap.
33//!
34//! # Example
35//!
36//! ## 1. Compile-Time FixedSize Containers
37//!
38//! We create a struct consisting of compile-time fixed size containers that can be used for
39//! zero copy inter-process communication.
40//!
41//! ```
42//! # extern crate iceoryx2_loggers;
43//!
44//! use iceoryx2_bb_container::string::*;
45//! use iceoryx2_bb_container::vector::*;
46//!
47//! const TEXT_CAPACITY: usize = 123;
48//! const DATA_CAPACITY: usize = 456;
49//!
50//! #[repr(C)]
51//! struct MyMessageType {
52//!     some_text: StaticString<TEXT_CAPACITY>,
53//!     some_data: StaticVec<u64, DATA_CAPACITY>,
54//! }
55//!
56//! # fn main() -> Result<(), Box<dyn core::error::Error>> {
57//! let my_message = MyMessageType {
58//!     some_text: StaticString::from_bytes(b"Hello World")?,
59//!     some_data: StaticVec::new(),
60//! };
61//! # Ok(())
62//! # }
63//! ```
64//!
65//! ## 2. Shared Memory Compatible Run-Time FixedSize Containers
66//!
67//! Despite that the containers are already implemented, iceoryx2 itself does not yet support
68//! run-time fixed size types. It is planned and will be part of an upcoming release.
69//!
70//! ## 3. Run-Time FixedSize Containers
71//!
72//! We create a struct consisting of run-time fixed size containers. This can be interesting when
73//! it shall be used in a safety-critical environment where everything must be pre-allocated to
74//! ensure that required memory is always available.
75//!
76//! ```
77//! # extern crate iceoryx2_loggers;
78//!
79//! use iceoryx2_bb_container::queue::*;
80//!
81//! const QUEUE_CAPACITY: usize = 123;
82//!
83//! #[repr(C)]
84//! struct MyType {
85//!     some_queue: Queue<u64>,
86//! }
87//!
88//! # fn main() -> Result<(), Box<dyn core::error::Error>> {
89//! let my_thing = MyType {
90//!     some_queue: Queue::new(QUEUE_CAPACITY),
91//! };
92//! # Ok(())
93//! # }
94//! ```
95
96extern crate alloc;
97
98/// A queue similar to [`alloc::collections::vec_deque::VecDeque`]
99pub mod queue;
100/// A container with persistent unique keys to access values.
101pub mod slotmap;
102/// Extends the [StaticString](crate::string::StaticString) so that custom string types with a semantic
103/// ruleset on their content can be realized.
104#[macro_use]
105pub mod semantic_string;
106
107/// A container to store key-value pairs.
108pub mod flatmap;
109
110/// A trait that defines the interface of a string and several string variants.
111pub mod string;
112
113#[doc(hidden)]
114pub(crate) mod vec;
115/// A trait that defines the interface of a vector and several vector variants.
116pub mod vector;
iceoryx2_bb_container/lib.rs

iceoryx2_bb_container/
lib.rs
