blink_alloc/
api.rs

1use allocator_api2::alloc::Allocator;
2
3/// Extension trait for [`Allocator`] that defines blink allocator API.
4/// Blink-allocators are allocators with cheap allocation
5/// and potentially no-op deallocation.
6/// Blink-allocator *can* reuse deallocated memory, but not required to.
7/// Typically deallocation is either no-op or processed only if deallocating
8/// the very last allocated memory block.
9/// The [`reset`][BlinkAllocator::reset]
10/// method deallocates all memory allocated from this instance at once.
11///
12/// Additional guarantees are provided that
13///
14/// * [`Allocator::shrink`] will always succeed and never move memory
15/// when `ptr` is already aligned to `new_layout.align()`.
16///
17/// # Safety
18///
19/// Draws most requirements from [`Allocator`] super-trait.
20/// The [`reset`][BlinkAllocator::reset] method
21/// may invalidate currently allocated memory if allocator is not cloneable.
22pub unsafe trait BlinkAllocator: Allocator {
23    /// Resets allocator potentially invalidating all allocations
24    /// made from this instance.
25    /// This is no-op if allocator is [`Clone`][core::clone::Clone]
26    /// (typically shared reference to blink-allocator).
27    ///
28    /// # Safety
29    ///
30    /// Caller must guarantee that all allocations made from this instance
31    /// won't be used after this call.
32    /// The potential invalid memory access will happen through
33    /// raw pointer and requires `unsafe`.
34    ///
35    /// This method requires mutable borrow of the blink-allocator
36    /// and so cannot be called while collection types reference it.
37    /// So it is safe to use reference to blink allocator as allocator type
38    /// for, say, [`Vec`] and later then call `reset` safely.
39    /// The `Vec` would have to be dropped (or forgotten) before calling `reset`
40    /// due to mutable borrow.
41    ///
42    /// [`Vec`]: alloc::vec::Vec
43    fn reset(&mut self);
44}
45
46unsafe impl<A> BlinkAllocator for &A
47where
48    A: BlinkAllocator,
49{
50    #[inline]
51    fn reset(&mut self) {}
52}
53
54unsafe impl<'a, A> BlinkAllocator for &'a mut A
55where
56    &'a mut A: Allocator,
57    A: BlinkAllocator,
58{
59    #[inline]
60    fn reset(&mut self) {
61        A::reset(self);
62    }
63}
blink_alloc/api.rs

blink_alloc/
api.rs
