✨ Add boxed module

This is an abstraction over `heapless::pool::boxed` and `alloc::boxed`.

Author: zeenix

src/boxed.rs

@@ -0,0 +1,200 @@
+//! Abstraction over `heapless::pool::boxed` and `alloc::boxed`.
+//!
+//! The API is modeled after `heapless::pool::boxed` but simpler. This module is only available
+//! when either:
+//!
+//! - `alloc` feature is enabled, or
+//! - `heapless` and `portable-atomic` features are enabled.
+//!
+//! # Usage
+//!
+//! ```
+//! use mayheap::{box_pool, boxed::{BoxPool, Box}};
+//!
+//! // Create a pool for u32 type with a capacity of 10.
+//! box_pool!(MyBoxPool: u32, 2);
+//!
+//! // Allocate a new boxed value from the pool.
+//! let mut boxed = MyBoxPool.alloc(42).unwrap();
+//! assert_eq!(*boxed, 42);
+//!
+//! // Let's mutate the boxed value.
+//! *boxed = 100;
+//! assert_eq!(*boxed, 100);
+//!
+//! // Let's allocate more.
+//! let _boxed = MyBoxPool.alloc(43).unwrap();
+//!
+//! #[cfg(feature = "alloc")]
+//! {
+//!     // This will work fine since capacity (which is 2 here) is irrelevant when using alloc.
+//!     let boxed = MyBoxPool.alloc(44).unwrap();
+//!     assert_eq!(*boxed, 44);
+//! }
+//! #[cfg(feature = "heapless")]
+//! {
+//!     // This will not.
+//!     let res = MyBoxPool.alloc(45);
+//!     assert_eq!(res, Err(45));
+//! }
+//! ```
+
+use core::ops::{Deref, DerefMut};
+
+/// A singleton that manages pool::boxed::Box-es.
+///
+/// Don't implement this trait directly. Use [`box_pool`] to create an implementation.
+pub trait BoxPool {
+    /// The data type managed by the memory pool.
+    type Data;
+    /// The implementation-specific type of the boxed value.
+    type BoxedValue: DerefMut<Target = Self::Data>;
+
+    /// Allocates a new boxed value from the pool.
+    fn alloc(&self, value: Self::Data) -> Result<Box<Self>, Self::Data>
+    where
+        Self: Sized;
+}
+
+/// A boxed value managed by a [`BoxPool`].
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct Box<P: BoxPool>(P::BoxedValue);
+
+impl<P: BoxPool> Box<P> {
+    /// Allocates a new boxed value from the pool.
+    pub fn new(value: P::BoxedValue) -> Self {
+        Self(value)
+    }
+}
+
+impl<P: BoxPool> Deref for Box<P> {
+    type Target = P::Data;
+
+    fn deref(&self) -> &Self::Target {
+        self.0.deref()
+    }
+}
+
+impl<P: BoxPool> DerefMut for Box<P> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.0.deref_mut()
+    }
+}
+
+/// Creates a new BoxPool singleton with the given $name that manages the specified $data_type
+#[cfg(feature = "alloc")]
+#[macro_export]
+macro_rules! box_pool {
+    ($name:ident: $ty:ty, $capacity:expr) => {
+        #[derive(Debug, Clone, PartialEq, Eq)]
+        pub struct $name;
+
+        impl $crate::boxed::BoxPool for $name {
+            type Data = $ty;
+            type BoxedValue = $crate::reexports::alloc::boxed::Box<$ty>;
+
+            fn alloc(&self, value: Self::Data) -> Result<$crate::boxed::Box<Self>, Self::Data> {
+                Ok($crate::boxed::Box::new(
+                    $crate::reexports::alloc::boxed::Box::new(value),
+                ))
+            }
+        }
+
+        $crate::reexports::paste::paste! {
+            // Let's use the $capacity variable so callers don't get "unused const" warnings.
+            #[allow(non_upper_case_globals, dead_code)]
+            const [<__dummy__ $name>]: () = {
+                let _ = $capacity;
+            };
+        }
+    };
+}
+
+/// Creates a new BoxPool singleton with the given $name that manages the specified $data_type
+#[cfg(not(feature = "alloc"))]
+#[macro_export]
+macro_rules! box_pool {
+    ($name:ident: $ty:ty, $capacity:expr) => {
+        $crate::reexports::paste::paste! {
+            heapless::box_pool!([<$name Pool>]: $ty);
+
+            #[derive(Debug, Clone, PartialEq, Eq)]
+            pub struct $name;
+
+            impl $crate::boxed::BoxPool for $name {
+                type Data = $ty;
+                type BoxedValue = heapless::pool::boxed::Box<[<$name Pool>]>;
+
+                fn alloc(&self, value: Self::Data) -> Result<$crate::boxed::Box<Self>, $ty> {
+                    $name.init();
+
+                    [<$name Pool>].alloc(value).map($crate::boxed::Box::new)
+                }
+            }
+
+            impl $name {
+                fn init(&self) {
+                    use portable_atomic::{AtomicU8, Ordering};
+                    use heapless::pool::boxed::BoxBlock;
+
+                    static STATE: AtomicU8 = AtomicU8::new(InitState::Uninitialized as u8);
+
+                    match STATE
+                        .compare_exchange(
+                            InitState::Uninitialized as u8,
+                            InitState::Initializing as u8,
+                            Ordering::AcqRel,
+                            Ordering::Acquire,
+                        )
+                        .map(|state| state.into())
+                        .map_err(|state| state.into())
+                    {
+                        Ok(InitState::Uninitialized) => {
+                            // We won the race, initialize.
+                            let blocks: &'static mut [BoxBlock<$ty>] = {
+                                #[allow(clippy::declare_interior_mutable_const)]
+                                const BLOCK: BoxBlock<$ty> = BoxBlock::new();
+                                static mut BLOCKS: [BoxBlock<$ty>; $capacity] = [BLOCK; $capacity];
+                                unsafe { core::ptr::addr_of_mut!(BLOCKS).as_mut().unwrap() }
+                            };
+                            for block in blocks {
+                               [<$name Pool>].manage(block);
+                            }
+                            STATE.store(InitState::Initialized as u8, Ordering::Release);
+                        }
+                        Err(InitState::Initializing) => {
+                            // Someone else is initializing, wait.
+                            while STATE.load(Ordering::Acquire) == InitState::Initializing as u8 {
+                                core::hint::spin_loop();
+                            }
+                        }
+                        Err(InitState::Initialized) => {
+                            // Already initialized.
+                        }
+                        // All other states should never happen.
+                        _ => unreachable!(),
+                    }
+
+                    #[repr(u8)]
+                    #[derive(PartialEq)]
+                    enum InitState {
+                        Uninitialized = 0,
+                        Initializing = 1,
+                        Initialized = 2,
+                    }
+
+                    impl From<u8> for InitState {
+                        fn from(value: u8) -> Self {
+                            match value {
+                                0 => InitState::Uninitialized,
+                                1 => InitState::Initializing,
+                                2 => InitState::Initialized,
+                                _ => unreachable!(),
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    };
+}

src/lib.rs

@@ -12,12 +12,13 @@
 #[cfg(all(not(feature = "alloc"), not(feature = "heapless")))]
 compile_error!("Either the `alloc` or `heapless` feature must be enabled");
 
-#[cfg(feature = "alloc")]
-extern crate alloc;
-
-// Re-export `paste` for the macros.
+// Re-exports for the macros.
 #[doc(hidden)]
-pub use paste;
+pub mod reexports {
+    #[cfg(feature = "alloc")]
+    pub extern crate alloc;
+    pub use paste;
+}
 
 pub mod vec;
 pub use vec::Vec;
@@ -28,6 +29,12 @@ pub use string::String;
 mod error;
 pub use error::{Error, Result};
 
+#[cfg(any(
+    all(feature = "portable-atomic", feature = "heapless"),
+    feature = "alloc"
+))]
+pub mod boxed;
+
 #[cfg(test)]
 mod tests {
     #[cfg(feature = "serde")]

src/string.rs

@@ -5,7 +5,7 @@ use core::{cmp::Ordering, fmt, hash, iter, ops, str};
 use crate::Vec;
 
 #[cfg(feature = "alloc")]
-type Inner<const N: usize> = alloc::string::String;
+type Inner<const N: usize> = crate::reexports::alloc::string::String;
 #[cfg(not(feature = "alloc"))]
 type Inner<const N: usize> = heapless::String<N>;
 
@@ -357,7 +357,9 @@ macro_rules! impl_try_from_num {
             fn try_from(s: $num) -> Result<Self, Self::Error> {
                 #[cfg(feature = "alloc")]
                 {
-                    Ok(Self(alloc::string::ToString::to_string(&s)))
+                    Ok(Self(crate::reexports::alloc::string::ToString::to_string(
+                        &s,
+                    )))
                 }
                 #[cfg(not(feature = "alloc"))]
                 {

src/vec.rs

@@ -5,7 +5,7 @@
 use core::{cmp::Ordering, fmt, hash, iter::FromIterator, ops, slice};
 
 #[cfg(feature = "alloc")]
-pub(crate) type Inner<T, const N: usize> = alloc::vec::Vec<T>;
+pub(crate) type Inner<T, const N: usize> = crate::reexports::alloc::vec::Vec<T>;
 #[cfg(not(feature = "alloc"))]
 pub(crate) type Inner<T, const N: usize> = heapless::Vec<T, N>;
 
@@ -437,7 +437,7 @@ impl<T, const N: usize> FromIterator<T> for Vec<T, N> {
 #[derive(Clone, Debug)]
 pub struct IntoIter<T, const N: usize> {
     #[cfg(feature = "alloc")]
-    iter: alloc::vec::IntoIter<T>,
+    iter: crate::reexports::alloc::vec::IntoIter<T>,
     // FIXME: Once the fix for https://github.com/rust-embedded/heapless/issues/530 is released. We
     // can turn this into a wrapper around `heapless::vec::IntoIter`.
     #[cfg(not(feature = "alloc"))]