Add a macro to make initialization easier

Author: JalonWong

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- Added a `init` macro to make initialization easier.
+
 ## [v0.6.0] - 2024-09-01
 
 ### Added

README.md

@@ -31,6 +31,8 @@ static HEAP: Heap = Heap::empty();
 #[entry]
 fn main() -> ! {
     // Initialize the allocator BEFORE you use it
+    embedded_alloc::init!(HEAP, 1024);
+    // Or do it manually if you have specific requirements.
     {
         use core::mem::MaybeUninit;
         const HEAP_SIZE: usize = 1024;

examples/global_alloc.rs

@@ -17,12 +17,7 @@ static HEAP: Heap = Heap::empty();
 #[entry]
 fn main() -> ! {
     // Initialize the allocator BEFORE you use it
-    {
-        use core::mem::MaybeUninit;
-        const HEAP_SIZE: usize = 1024;
-        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
-        unsafe { HEAP.init(&raw mut HEAP_MEM as usize, HEAP_SIZE) }
-    }
+    embedded_alloc::init!(HEAP, 1024);
 
     let mut xs = Vec::new();
     xs.push(1);

examples/llff_integration_test.rs

@@ -63,11 +63,7 @@ fn test_allocator_api() {
 
 #[entry]
 fn main() -> ! {
-    {
-        const HEAP_SIZE: usize = 1024;
-        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
-        unsafe { HEAP.init(&raw mut HEAP_MEM as usize, HEAP_SIZE) }
-    }
+    embedded_alloc::init!(HEAP, 1024);
 
     #[allow(clippy::type_complexity)]
     let tests: &[(fn() -> (), &'static str)] = &[

examples/tlsf_integration_test.rs

@@ -81,10 +81,7 @@ fn test_allocator_api() {
 
 #[entry]
 fn main() -> ! {
-    {
-        static mut HEAP_MEM: [MaybeUninit<u8>; HEAP_SIZE] = [MaybeUninit::uninit(); HEAP_SIZE];
-        unsafe { HEAP.init(&raw mut HEAP_MEM as usize, HEAP_SIZE) }
-    }
+    embedded_alloc::init!(HEAP, HEAP_SIZE);
 
     #[allow(clippy::type_complexity)]
     let tests: &[(fn() -> (), &'static str)] = &[

src/lib.rs

@@ -12,3 +12,58 @@ mod tlsf;
 pub use llff::Heap as LlffHeap;
 #[cfg(feature = "tlsf")]
 pub use tlsf::Heap as TlsfHeap;
+
+/// Initialize the global heap.
+///
+/// This macro creates a static, uninitialized memory buffer of the specified size and
+/// initializes the heap instance with that buffer.
+///
+/// # Parameters
+///
+/// - `$heap:ident`: The identifier of the global heap instance to initialize.
+/// - `$size:expr`: An expression evaluating to a `usize` that specifies the size of the
+///   static memory buffer in bytes. It must be **greater than zero**.
+///
+/// # Safety
+///
+/// This macro must be called first, before any operations on the heap, and **only once**.
+///
+/// # Example
+///
+/// ```rust
+/// use cortex_m_rt::entry;
+/// use embedded_alloc::LlffHeap as Heap;
+///
+/// #[global_allocator]
+/// static HEAP: Heap = Heap::empty();
+///
+/// #[entry]
+/// fn main() -> ! {
+///     // Initialize the allocator BEFORE you use it
+///     embedded_alloc::init!(HEAP, 1024);
+///     let mut xs = Vec::new();
+///     // ...
+/// }
+/// ```
+#[macro_export]
+macro_rules! init {
+    ($heap:ident, $size:expr) => {
+        assert!($size > 0);
+        // Ensure the heap is static.
+        let static_heap: &'static Heap = &$heap;
+
+        use core::sync::atomic::AtomicBool;
+        use core::sync::atomic::Ordering;
+        // Ensure it is called only once.
+        static CALL_ONCE: AtomicBool = AtomicBool::new(false);
+        assert_eq!(CALL_ONCE.load(Ordering::Acquire), false);
+        CALL_ONCE.store(true, Ordering::Release);
+
+        static mut HEAP_MEM: [core::mem::MaybeUninit<u8>; $size] =
+            [core::mem::MaybeUninit::uninit(); $size];
+        unsafe {
+            #[allow(static_mut_refs)]
+            $heap.init(&raw mut HEAP_MEM as usize, $size)
+        }
+    };
+}