slotpool 0.2.1

Fixed-capacity object pools for no_std / embedded systems
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

//! Async wrapper around [`ObjectPool`] — `request` awaits when the pool is full.
//!
//! Requires feature `async`.
//!
//! ## ISR caveat
//!
//! Dropping an [`AsyncObjectGuard`] inside an interrupt handler on **Cortex-M0/M0+**
//! may panic due to non-nestable `cpsid`/`cpsie`.  On M3+ this is safe.
//! For ISR use, prefer the sync [`ObjectPool`](crate::ObjectPool) directly.

use core::cell::UnsafeCell;
use core::mem::{ManuallyDrop, MaybeUninit};
use core::ops::{Deref, DerefMut};

use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
use embassy_sync::semaphore::FairSemaphore;
use embassy_sync::semaphore::Semaphore;

use crate::critical::CriticalSlots;
use crate::free_slots::FreeSlots;
use crate::object::{ObjectGuard, ObjectPool};

/// Async variant of [`ObjectPool`](crate::ObjectPool) — `request` awaits when full.
pub struct AsyncObjectPool<T, const N: usize, B = CriticalSlots<N>> {
    inner: ObjectPool<T, N, B>,
    wake: FairSemaphore<CriticalSectionRawMutex, N>,
}

// SAFETY: inner is Sync, FairSemaphore is Sync.
unsafe impl<T, const N: usize, B: FreeSlots<N>> Sync for AsyncObjectPool<T, N, B> {}

/// Static storage for an [`AsyncObjectPool`].
///
/// ```ignore
/// use slotpool::async_object::StaticAsyncObjectPool;
///
/// static POOL: StaticAsyncObjectPool<[u8; 256], 8> = StaticAsyncObjectPool::new();
/// let pool = POOL.init_pool([0u8; 256]);
/// ```
pub struct StaticAsyncObjectPool<T, const N: usize, B: FreeSlots<N> = CriticalSlots<N>> {
    data: UnsafeCell<MaybeUninit<AsyncObjectPool<T, N, B>>>,
}

unsafe impl<T, const N: usize, B: FreeSlots<N>> Sync for StaticAsyncObjectPool<T, N, B> {}

impl<T: Clone, const N: usize, B: FreeSlots<N>> StaticAsyncObjectPool<T, N, B> {
    #[allow(clippy::new_without_default)]
    pub const fn new() -> Self {
        Self {
            data: UnsafeCell::new(MaybeUninit::uninit()),
        }
    }

    pub fn init_pool(&'static self, init: T) -> &'static AsyncObjectPool<T, N, B> {
        assert!(N > 0, "Pool capacity must be greater than 0");
        unsafe {
            let ptr: *mut AsyncObjectPool<T, N, B> =
                self.data.get().cast::<AsyncObjectPool<T, N, B>>();
            ptr.write(AsyncObjectPool {
                inner: ObjectPool {
                    slots: UnsafeCell::new(MaybeUninit::uninit()),
                    free: B::new(),
                },
                wake: FairSemaphore::new(0),
            });
            (*ptr)
                .inner
                .free
                .fill(N)
                .expect("fill(N) must succeed when count == capacity");
            for i in 0..N {
                (*ptr).inner.slot_mut_ptr(i).write(init.clone());
            }
            &*ptr
        }
    }
}

impl<T, const N: usize, B: FreeSlots<N>> AsyncObjectPool<T, N, B> {
    /// Borrow a slot, awaiting until one is free.
    pub async fn request(&'static self) -> AsyncObjectGuard<T, N, B> {
        loop {
            match self.inner.request() {
                Some(guard) => {
                    return AsyncObjectGuard {
                        guard: ManuallyDrop::new(guard),
                        wake: &self.wake,
                    };
                }
                None => {
                    let _ = self
                        .wake
                        .acquire(1)
                        .await
                        .expect("semaphore acquire(1) must not fail");
                }
            }
        }
    }
}

/// Async borrow of an [`ObjectPool`] slot.  Behaves like [`ObjectGuard`](crate::ObjectGuard)
/// but wakes a waiter on drop.
#[must_use]
pub struct AsyncObjectGuard<T: 'static, const N: usize, B: FreeSlots<N> + 'static> {
    guard: ManuallyDrop<ObjectGuard<T, N, B>>,
    wake: &'static FairSemaphore<CriticalSectionRawMutex, N>,
}

impl<T, const N: usize, B: FreeSlots<N>> Deref for AsyncObjectGuard<T, N, B> {
    type Target = T;
    fn deref(&self) -> &T {
        &self.guard
    }
}

impl<T, const N: usize, B: FreeSlots<N>> DerefMut for AsyncObjectGuard<T, N, B> {
    fn deref_mut(&mut self) -> &mut T {
        &mut self.guard
    }
}

impl<T, const N: usize, B: FreeSlots<N>> Drop for AsyncObjectGuard<T, N, B> {
    fn drop(&mut self) {
        // 1. Release the slot (no destructor — data persists).
        unsafe {
            ManuallyDrop::drop(&mut self.guard);
        }
        // 2. Wake one waiter.
        self.wake.release(1);
    }
}

unsafe impl<T: Send, const N: usize, B: FreeSlots<N>> Send for AsyncObjectGuard<T, N, B> {}