o3 0.31.1

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

use crate::{
    buffer,
    buffer::{
        storage,
        storage::regions,
        write::{SpareExt as _, spans},
    },
};

/// Lifetime-independent one-word exact allocation owner.
#[derive(Debug, Default)]
#[repr(transparent)]
pub struct Exact {
    pub(in crate::buffer) inner: Option<regions::Init>,
}

impl Exact {
    #[must_use]
    pub const fn new() -> Self {
        Self { inner: None }
    }

    pub fn try_build<E>(
        capacity: usize,
        build: impl FnOnce(&mut spans::Writer<'_, '_>) -> Result<(), E>,
    ) -> Result<Self, storage::BuildError<E>> {
        use storage::BuildError;

        let mut owned = storage::Owned::try_with(capacity)?;
        let mut spare = owned.spare();
        let mut writer = spare.bounded();
        build(&mut writer).map_err(BuildError::Build)?;
        writer.commit();
        spare
            .try_complete()
            .map_err(|error| BuildError::Length(error.into()))?;
        let Some(heap) = owned.allocation else {
            return Ok(Self::new());
        };
        // SAFETY: the original spare completed this owner's entire uninitialized suffix.
        Ok(Self {
            inner: Some(unsafe { regions::Init::new(heap.into_shared()) }),
        })
    }

    pub fn try_copy(bytes: &[u8]) -> Result<Self, storage::AllocError> {
        use storage::AllocError;

        let Some(slices) = buffer::raw::Slices::try_new([bytes]).map_err(AllocError::Capacity)?
        else {
            return Ok(Self::new());
        };
        slices.try_owned().map_err(AllocError::Exhausted)
    }

    #[must_use]
    pub fn into_shared(self) -> storage::Shared {
        match self.inner {
            Some(inner) => inner.into_buf().into(),
            None => storage::Shared::new(),
        }
    }

    pub fn as_slice(&self) -> &[u8] {
        self.inner.as_ref().map_or(&[], regions::Init::as_slice)
    }
}

impl AsRef<[u8]> for Exact {
    fn as_ref(&self) -> &[u8] {
        self.as_slice()
    }
}

impl buffer::Residency for Exact {
    fn resident(&self) -> usize {
        self.inner
            .as_ref()
            .map_or(0, |inner| inner.capacity().get() as usize)
    }
}

const _: () = assert!(size_of::<Exact>() == size_of::<usize>());

// SAFETY: the exact owner exposes its complete initialized allocation immutably.
unsafe impl buffer::raw::Source for Exact {}