o3 0.16.3

shared-nothing primitives
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
135
136

use std::{alloc, marker, ptr};

use crate::buffer::{pool, pool::state};

mod core;
mod frozen;
mod layout;
mod lease;

pub use frozen::Frozen;
pub use layout::{Layout, Plan};
pub use lease::Lease;

pub trait Seal {}

#[repr(transparent)]
pub struct Pool<S: state::State = state::Uninitialized, C: pool::Capacity = pool::RuntimeCapacity> {
    core: ptr::NonNull<core::Core>,
    marker: marker::PhantomData<(S, C, *mut ())>,
}

impl<S: state::State> Pool<S, pool::RuntimeCapacity> {
    pub fn from_layout(layout: Layout) -> Self {
        Self {
            core: core::Core::allocate::<S>(layout),
            marker: marker::PhantomData,
        }
    }

    pub fn try_new(slots: usize, capacity: usize) -> Result<Self, pool::LayoutError> {
        Ok(Self::from_layout(Layout::new(slots, capacity)?))
    }

    pub fn try_from_layout(layout: Layout) -> Result<Self, pool::AllocationError> {
        Ok(Self {
            core: core::Core::try_allocate::<S>(layout)?,
            marker: marker::PhantomData,
        })
    }
}

impl<S: state::State, C: pool::Capacity> Pool<S, C> {
    pub fn try_acquire(&self) -> Option<Lease<S, C>> {
        let index = core::Core::acquire_owned(self.core)?;
        Some(Lease::new(self.core, index))
    }

    /// Acquires a slot whose allocation lifetime is proven by this pool borrow.
    /// Unlike [`try_acquire`](Self::try_acquire), this does not retain the pool
    /// allocation.
    pub fn try_acquire_borrowed(&self) -> Option<Lease<S, C, pool::Borrowed<'_>>> {
        let index = core::Core::acquire_borrowed(self.core)?;
        Some(Lease::new(self.core, index))
    }

    pub fn capacity(&self) -> usize {
        // SAFETY: `Pool` owns one live reference to this core.
        unsafe { self.core.as_ref() }.capacity as usize
    }

    pub fn slots(&self) -> usize {
        // SAFETY: `Pool` owns one live reference to this core.
        unsafe { self.core.as_ref() }.slots as usize
    }

    pub fn available(&self) -> usize {
        // SAFETY: `Pool` owns one live reference to this core.
        unsafe { self.core.as_ref() }.free_len.get() as usize
    }
}

impl<S: state::State, const CAP: u32> Pool<S, pool::FixedCapacity<CAP>> {
    pub fn try_with_slots(slots: usize) -> Result<Self, pool::LayoutError> {
        let layout = Layout::new(slots, CAP as usize)?;
        Ok(Self {
            core: core::Core::allocate::<S>(layout),
            marker: marker::PhantomData,
        })
    }

    pub fn try_allocate_slots(slots: usize) -> Result<Self, pool::CreateError> {
        let layout = Layout::new(slots, CAP as usize)?;
        Ok(Self {
            core: core::Core::try_allocate::<S>(layout)?,
            marker: marker::PhantomData,
        })
    }

    #[must_use]
    pub fn fixed<const SLOTS: usize>() -> Self {
        let layout = Layout::fixed_capacity::<SLOTS, CAP>();
        Self {
            core: core::Core::allocate::<S>(layout),
            marker: marker::PhantomData,
        }
    }
}

impl<C: pool::Capacity> Pool<state::Uninitialized, C> {
    #[must_use]
    pub fn try_acquire_buffer(&self) -> Option<pool::Cursor<C>> {
        self.try_acquire().map(pool::Cursor::new)
    }

    #[must_use]
    pub fn try_acquire_borrowed_buffer(&self) -> Option<pool::BorrowedCursor<'_, C>> {
        self.try_acquire_borrowed().map(pool::BorrowedCursor::new)
    }
}

impl<S: state::State, C: pool::Capacity> Clone for Pool<S, C> {
    fn clone(&self) -> Self {
        // SAFETY: the source pool keeps the core allocation live.
        unsafe { self.core.as_ref() }.refs.retain();
        Self {
            core: self.core,
            marker: marker::PhantomData,
        }
    }
}

impl<S: state::State, C: pool::Capacity> Drop for Pool<S, C> {
    fn drop(&mut self) {
        // SAFETY: this pool owns one live core reference.
        let core = unsafe { self.core.as_ref() };
        if !core.refs.release() {
            return;
        }
        // SAFETY: allocation size was produced by `Layout` with Core alignment.
        let layout = unsafe {
            alloc::Layout::from_size_align_unchecked(core.allocation_size, align_of::<core::Core>())
        };
        // SAFETY: the final reference owns the allocation and exact layout.
        unsafe { alloc::dealloc(self.core.as_ptr().cast(), layout) };
    }
}