Crate iceoryx2_bb_container

iceoryx2 Building Blocks (BB) Container

This is a support library for iceoryx2 which comes with containers that are compatible with shared memory and can be used to construct custom payload types for inter-process communication.

Most containers come in 3 variations:

1. FixedSize*Container*, compile-time fixed size version. The capacity must be known at compile time. Those fixed-size constructs are always self-contained, meaning that the required memory is part of the constructs and usually stored in some kind of array.
2. Relocatable*Container*, run-time fixed size version that is shared memory compatible. The capacity must be known when the object is created. This object is not movable!
3. *Container*, run-time fixed size version that is not shared memory compatible but can be moved. The memory is by default stored on the heap.

Example

1. Compile-Time FixedSize Containers

We create a struct consisting of compile-time fixed size containers that can be used for zero copy inter-process communication.

use iceoryx2_bb_container::byte_string::*;
use iceoryx2_bb_container::vec::*;

const TEXT_CAPACITY: usize = 123;
const DATA_CAPACITY: usize = 456;

#[repr(C)]
struct MyMessageType {
    some_text: FixedSizeByteString<TEXT_CAPACITY>,
    some_data: FixedSizeVec<u64, DATA_CAPACITY>,
}

let my_message = MyMessageType {
    some_text: FixedSizeByteString::from_bytes(b"Hello World")?,
    some_data: FixedSizeVec::new(),
};

2. Shared Memory Compatible Run-Time FixedSize Containers

Despite that the containers are already implemented, iceoryx2 itself does not yet support run-time fixed size types. It is planned and will be part of an upcoming release.

3. Run-Time FixedSize Containers

We create a struct consisting of run-time fixed size containers. This can be interesting when it shall be used in a safety-critical environment where everything must be pre-allocated to ensure that required memory is always available.

use iceoryx2_bb_container::queue::*;

const QUEUE_CAPACITY: usize = 123;

#[repr(C)]
struct MyType {
    some_queue: Queue<u64>,
}

let my_thing = MyType {
    some_queue: Queue::new(QUEUE_CAPACITY),
};

Modules

byte_string

A byte string similar to std::string::String but it does not support UTF-8 Relocatable (inter-process shared memory compatible) string implementations.

queue

A queue similar to std::collections::VecDeque Three queue variations that are similar to std::collections::VecDeque.

semantic_string

Extends the ByteString so that custom string types with a semantic ruleset on their content can be realized. The SemanticString is a trait for FixedSizeByteString to create strong string types with semantic content contracts. They can be created with the help of the semantic_string macro.

slotmap

A container with persistent unique keys to access values. A SlotMap is a container that has a static unique key for every stored value. Adding or removing values to the SlotMap do not change the unique key of the remaining values. Multiple variationes of that container are available.

vec

A vector similar to std::vec::Vec Contains vector variations that are similar to std::vec::Vec.

Macros

semantic_string

Helper macro to create a new SemanticString. Usage example can be found here: crate::semantic_string.