From 4d9284191794e8e1791bd667b1ac4f07d46deb34 Mon Sep 17 00:00:00 2001 From: Christian Eltzschig Date: Thu, 7 Nov 2024 21:28:25 +0100 Subject: [PATCH] [#504] Add documentation example --- iceoryx2-bb/container/src/queue.rs | 16 ++++++---- iceoryx2-bb/container/src/slotmap.rs | 26 ++++++++++++++++- iceoryx2-bb/container/src/vec.rs | 20 +++++++++---- iceoryx2-bb/lock-free/src/mpmc/container.rs | 12 +++----- .../lock-free/src/mpmc/unique_index_set.rs | 29 ++++++++++--------- 5 files changed, 69 insertions(+), 34 deletions(-) diff --git a/iceoryx2-bb/container/src/queue.rs b/iceoryx2-bb/container/src/queue.rs index 582bb3a66..b8d57e208 100644 --- a/iceoryx2-bb/container/src/queue.rs +++ b/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::>(std::mem::size_of::>()) 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::::new_uninit(QUEUE_CAPACITY) }; +//! let mut queue = unsafe { RelocatableQueue::::new_uninit(QUEUE_CAPACITY) }; //! unsafe { queue.init(&bump_allocator).expect("queue init failed") }; //! ``` //! diff --git a/iceoryx2-bb/container/src/slotmap.rs b/iceoryx2-bb/container/src/slotmap.rs index 3f66e8106..5c29a80e8 100644 --- a/iceoryx2-bb/container/src/slotmap.rs +++ b/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::::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 FixedSizeSlotMap { 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 { unsafe { self.state.iter_impl() } } diff --git a/iceoryx2-bb/container/src/vec.rs b/iceoryx2-bb/container/src/vec.rs index cedacec9b..75493493c 100644 --- a/iceoryx2-bb/container/src/vec.rs +++ b/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::>(std::mem::size_of::>()) 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::::new_uninit(VEC_CAPACITY) }; +//! let mut vec = unsafe { RelocatableVec::::new_uninit(VEC_CAPACITY) }; //! unsafe { vec.init(&bump_allocator).expect("vec init failed") }; //! ``` diff --git a/iceoryx2-bb/lock-free/src/mpmc/container.rs b/iceoryx2-bb/lock-free/src/mpmc/container.rs index 9f0790adb..90cb8f253 100644 --- a/iceoryx2-bb/lock-free/src/mpmc/container.rs +++ b/iceoryx2-bb/lock-free/src/mpmc/container.rs @@ -282,8 +282,7 @@ impl Container { /// /// # 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 Container { /// /// # 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 Container { /// /// # 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 { self.verify_memory_initialization("get_state"); @@ -361,8 +358,7 @@ impl Container { /// /// # 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. /// diff --git a/iceoryx2-bb/lock-free/src/mpmc/unique_index_set.rs b/iceoryx2-bb/lock-free/src/mpmc/unique_index_set.rs index 78a49b29b..ceb194a35 100644 --- a/iceoryx2-bb/lock-free/src/mpmc/unique_index_set.rs +++ b/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::() 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, 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 { @@ -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()`]