[eclipse-iceoryx#504] Add documentation example

iceoryx2-bb/container/src/queue.rs

@@ -57,6 +57,7 @@
 //! ```
 //! use iceoryx2_bb_container::queue::RelocatableQueue;
 //! use iceoryx2_bb_elementary::math::align_to;
+//! use iceoryx2_bb_elementary::bump_allocator::BumpAllocator;
 //! use iceoryx2_bb_elementary::relocatable_container::RelocatableContainer;
 //! use core::mem::MaybeUninit;
 //!
@@ -68,11 +69,16 @@
 //!
 //! impl MyConstruct {
 //!     pub fn new() -> Self {
-//!         Self {
-//!             queue: unsafe { RelocatableQueue::new(QUEUE_CAPACITY,
-//!                             align_to::<MaybeUninit<u128>>(std::mem::size_of::<RelocatableQueue<u128>>()) as isize) },
+//!         let mut new_self = Self {
+//!             queue: unsafe { RelocatableQueue::new_uninit(QUEUE_CAPACITY) },
 //!             queue_memory: core::array::from_fn(|_| MaybeUninit::uninit()),
-//!         }
+//!         };
+//!
+//!         let allocator = BumpAllocator::new(core::ptr::addr_of!(new_self.queue_memory) as usize);
+//!         unsafe {
+//!             new_self.queue.init(&allocator).expect("Enough memory provided.")
+//!         };
+//!         new_self
 //!     }
 //! }
 //! ```
@@ -91,7 +97,7 @@
 //!
 //! let bump_allocator = BumpAllocator::new(memory.as_mut_ptr() as usize);
 //!
-//! let queue = unsafe { RelocatableQueue::<u128>::new_uninit(QUEUE_CAPACITY) };
+//! let mut queue = unsafe { RelocatableQueue::<u128>::new_uninit(QUEUE_CAPACITY) };
 //! unsafe { queue.init(&bump_allocator).expect("queue init failed") };
 //! ```
 //!

iceoryx2-bb/container/src/slotmap.rs

@@ -10,6 +10,30 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! 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.
+//!
+//!  * [`SlotMap`](crate::slotmap::SlotMap), run-time fixed-size slotmap that is not shared-memory
+//!    compatible since the memory resides in the heap.
+//!  * [`FixedSizeSlotMap`](crate::slotmap::FixedSizeSlotMap), compile-time fixed-size slotmap that
+//!    is self-contained and shared-memory compatible.
+//!  * [`RelocatableSlotMap`](crate::slotmap::RelocatableSlotMap), run-time fixed-size slotmap that
+//!    is shared-memory compatible.
+//!
+//! # User Examples
+//!
+//! ```
+//! use iceoryx2_bb_container::slotmap::FixedSizeSlotMap;
+//!
+//! const CAPACITY: usize = 123;
+//! let mut slotmap = FixedSizeSlotMap::<u64, CAPACITY>::new();
+//!
+//! let key = slotmap.insert(78181).unwrap();
+//!
+//! println!("value: {:?}", slotmap.get(key));
+//! ```
+
 use crate::queue::details::MetaQueue;
 use crate::vec::details::MetaVec;
 use crate::{queue::RelocatableQueue, vec::RelocatableVec};
@@ -527,7 +551,7 @@ impl<T, const CAPACITY: usize> FixedSizeSlotMap<T, CAPACITY> {
         Self::default()
     }
 
-    /// Returns the [`Iter`]ator to iterate over all entries.
+    /// Returns the [`details::RelocatableIter`]ator to iterate over all entries.
     pub fn iter(&self) -> details::RelocatableIter<T> {
         unsafe { self.state.iter_impl() }
     }

iceoryx2-bb/container/src/vec.rs

@@ -10,8 +10,10 @@
 //
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-//! Contains two vector variations that are similar to [`std::vec::Vec`].
+//! Contains vector variations that are similar to [`std::vec::Vec`].
 //!
+//!  * [`Vec`](crate::vec::Vec), run-time fixed-size vector that is not shared-memory compatible
+//!     since the memory resides in the heap.
 //!  * [`FixedSizeVec`](crate::vec::FixedSizeVec), compile-time fixed size vector that is
 //!     self-contained.
 //!  * [`RelocatableVec`](crate::vec::RelocatableVec), run-time fixed size vector that uses by default heap memory.
@@ -37,6 +39,7 @@
 //! ```
 //! use iceoryx2_bb_container::vec::RelocatableVec;
 //! use iceoryx2_bb_elementary::math::align_to;
+//! use iceoryx2_bb_elementary::bump_allocator::BumpAllocator;
 //! use iceoryx2_bb_elementary::relocatable_container::RelocatableContainer;
 //! use core::mem::MaybeUninit;
 //!
@@ -48,11 +51,16 @@
 //!
 //! impl MyConstruct {
 //!     pub fn new() -> Self {
-//!         Self {
-//!             vec: unsafe { RelocatableVec::new(VEC_CAPACITY,
-//!                             align_to::<MaybeUninit<u128>>(std::mem::size_of::<Vec<u128>>()) as isize) },
+//!         let mut new_self = Self {
+//!             vec: unsafe { RelocatableVec::new_uninit(VEC_CAPACITY) },
 //!             vec_memory: core::array::from_fn(|_| MaybeUninit::uninit()),
-//!         }
+//!         };
+//!
+//!         let allocator = BumpAllocator::new(core::ptr::addr_of!(new_self.vec_memory) as usize);
+//!         unsafe {
+//!             new_self.vec.init(&allocator).expect("Enough memory provided.")
+//!         };
+//!         new_self
 //!     }
 //! }
 //! ```
@@ -71,7 +79,7 @@
 //!
 //! let bump_allocator = BumpAllocator::new(memory.as_mut_ptr() as usize);
 //!
-//! let vec = unsafe { RelocatableVec::<u128>::new_uninit(VEC_CAPACITY) };
+//! let mut vec = unsafe { RelocatableVec::<u128>::new_uninit(VEC_CAPACITY) };
 //! unsafe { vec.init(&bump_allocator).expect("vec init failed") };
 //! ```
 

iceoryx2-bb/lock-free/src/mpmc/container.rs

@@ -282,8 +282,7 @@ impl<T: Copy + Debug> Container<T> {
     ///
     /// # Safety
     ///
-    ///  * Ensure that the either [`Container::new()`] was used or [`Container::init()`] was used
-    ///     before calling this method
+    ///  * Ensure that [`Container::init()`] was called before calling this method
     ///  * Use [`Container::remove()`] to release the acquired index again. Otherwise, the
     ///     element will leak.
     ///
@@ -314,8 +313,7 @@ impl<T: Copy + Debug> Container<T> {
     ///
     /// # Safety
     ///
-    ///  * Ensure that the either [`Container::new()`] was used or [`Container::init()`] was used
-    ///     before calling this method
+    ///  * Ensure that [`Container::init()`] was called before calling this method
     ///  * Ensure that no one else possesses the [`UniqueIndex`] and the index was unrecoverable
     ///     lost
     ///  * Ensure that the `handle` was acquired by the same [`Container`]
@@ -345,8 +343,7 @@ impl<T: Copy + Debug> Container<T> {
     ///
     /// # Safety
     ///
-    ///  * Ensure that the either [`Container::new()`] was used or [`Container::init()`] was used
-    ///     before calling this method
+    ///  * Ensure that [`Container::init()`] was called before calling this method
     ///
     pub unsafe fn get_state(&self) -> ContainerState<T> {
         self.verify_memory_initialization("get_state");
@@ -361,8 +358,7 @@ impl<T: Copy + Debug> Container<T> {
     ///
     /// # Safety
     ///
-    ///  * Ensure that the either [`Container::new()`] was used or [`Container::init()`] was used
-    ///     before calling this method
+    ///  * Ensure that [`Container::init()`] was called before calling this method
     ///  * Ensure that the input argument `previous_state` was acquired by the same [`Container`]
     ///     with [`Container::get_state()`], otherwise the method will panic.
     ///

iceoryx2-bb/lock-free/src/mpmc/unique_index_set.rs

@@ -27,7 +27,7 @@
 //! let mut memory = [0u8; UniqueIndexSet::const_memory_size(CAPACITY)];
 //! let allocator = BumpAllocator::new(memory.as_mut_ptr() as usize);
 //!
-//! let index_set = unsafe { UniqueIndexSet::new_uninit(CAPACITY) };
+//! let mut index_set = unsafe { UniqueIndexSet::new_uninit(CAPACITY) };
 //! unsafe { index_set.init(&allocator) }.expect("failed to allocate enough memory");
 //!
 //! let new_index = match unsafe { index_set.acquire() } {
@@ -187,7 +187,7 @@ impl Drop for UniqueIndex<'_> {
 /// let mut memory = [0u8; UniqueIndexSet::const_memory_size(CAPACITY)];
 /// let allocator = BumpAllocator::new(memory.as_mut_ptr() as usize);
 ///
-/// let index_set = unsafe { UniqueIndexSet::new_uninit(CAPACITY) };
+/// let mut index_set = unsafe { UniqueIndexSet::new_uninit(CAPACITY) };
 /// unsafe { index_set.init(&allocator) }.expect("failed to allocate enough memory");
 ///
 /// let new_index = match unsafe { index_set.acquire() } {
@@ -200,6 +200,7 @@ impl Drop for UniqueIndex<'_> {
 /// ```
 /// use iceoryx2_bb_lock_free::mpmc::unique_index_set::*;
 /// use iceoryx2_bb_elementary::relocatable_container::*;
+/// use iceoryx2_bb_elementary::bump_allocator::BumpAllocator;
 /// use std::mem::MaybeUninit;
 ///
 /// const CAPACITY: usize = 128;
@@ -214,15 +215,16 @@ impl Drop for UniqueIndex<'_> {
 ///
 /// impl FixedSizeSet {
 ///     pub fn new() -> Self {
-///         FixedSizeSet {
-///             set: unsafe {
-///                 UniqueIndexSet::new(CAPACITY,
-///                 // distance to data beginning from the start of the set (UniqueIndexSet)
-///                 // member start
-///                 std::mem::size_of::<UniqueIndexSet>() as isize)
-///             },
+///         let mut new_self = FixedSizeSet {
+///             set: unsafe { UniqueIndexSet::new_uninit(CAPACITY) },
 ///             data: [MaybeUninit::uninit(); UniqueIndexSet::const_memory_size(CAPACITY)]
-///         }
+///         };
+///
+///         let allocator = BumpAllocator::new(core::ptr::addr_of!(new_self.data) as usize);
+///         unsafe {
+///             new_self.set.init(&allocator).expect("Enough memory provided.")
+///         };
+///         new_self
 ///     }
 /// }
 /// ```
@@ -324,8 +326,7 @@ impl UniqueIndexSet {
     ///
     /// # Safety
     ///
-    /// * Ensure that either the [`UniqueIndexSet`] was created with [`UniqueIndexSet::new()`] or
-    ///     [`UniqueIndexSet::init()`] was called.
+    /// * Ensure that [`UniqueIndexSet::init()`] was called once.
     ///
     pub unsafe fn acquire(&self) -> Result<UniqueIndex<'_>, UniqueIndexSetAcquireFailure> {
         self.verify_init("acquire");
@@ -383,8 +384,7 @@ impl UniqueIndexSet {
     ///
     /// # Safety
     ///
-    ///  * Ensure that either the [`UniqueIndexSet`] was created with [`UniqueIndexSet::new()`] or
-    ///     [`UniqueIndexSet::init()`] was called.
+    ///  * Ensure that [`UniqueIndexSet::init()`] was called once.
     ///  * The index must be manually released with [`UniqueIndexSet::release_raw_index()`]
     ///    otherwise the index is leaked.
     pub unsafe fn acquire_raw_index(&self) -> Result<u32, UniqueIndexSetAcquireFailure> {
@@ -437,6 +437,7 @@ impl UniqueIndexSet {
     ///
     /// # Safety
     ///
+    ///  * Ensure that [`UniqueIndexSet::init()`] was called once.
     ///  * It must be ensured that the index was acquired before and is not released twice.
     ///  * Shall be only used when the index was acquired with
     ///    [`UniqueIndexSet::acquire_raw_index()`]