o3 0.26.0

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 pool::{borrowed, state};

use crate::buffer::{self, pool, pool::owners, storage};

/// An exclusive initialized range retaining its original pool and slot.
pub struct Slice<'pool> {
    pub(in crate::buffer::pool::borrowed) span:
        pool::Span<owners::Plain, pool::Borrowed<'pool>, state::Initialized>,
    pub(in crate::buffer::pool::borrowed) start: u32,
    pub(in crate::buffer::pool::borrowed) end: u32,
}

impl buffer::Residency for Slice<'_> {
    fn resident(&self) -> usize {
        self.span.capacity().get() as usize
    }
}

impl<'pool> Slice<'pool> {
    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    pub fn len(&self) -> usize {
        (self.end - self.start) as usize
    }

    pub fn as_slice(&self) -> &[u8] {
        // SAFETY: this exclusive initialized span owns the checked visible range.
        unsafe { buffer::raw::range(self.span.entry().data(), self.start as usize, self.len()) }
    }

    pub fn as_mut_slice(&mut self) -> &mut [u8] {
        // SAFETY: no other writable capability survives this slot's acquisition.
        unsafe { buffer::raw::range_mut(self.span.entry().data(), self.start as usize, self.len()) }
    }

    pub fn try_frame(
        self,
        prefix: &[u8],
        suffix: usize,
    ) -> Result<borrowed::Frame<'pool>, (Self, borrowed::Error)> {
        let spare = self.start;
        if prefix.len() > spare as usize {
            return Err((
                self,
                borrowed::Error::Prefix {
                    requested: prefix.len(),
                    available: spare,
                },
            ));
        }
        let spare = self.span.capacity().get() - self.end;
        if suffix > spare as usize {
            return Err((
                self,
                borrowed::Error::Suffix {
                    requested: suffix,
                    available: spare,
                },
            ));
        }
        let start = self.start - prefix.len() as u32;
        // SAFETY: the first admission proves this exact source fits the exclusive slot.
        unsafe {
            buffer::raw::SliceExt::copy_to(prefix, self.span.entry().data().add(start as usize));
        }
        Ok(borrowed::Frame {
            start,
            end: self.end + suffix as u32,
            payload: self,
        })
    }

    pub fn freeze(self) -> storage::Shared<owners::Edge<owners::Plain, pool::Borrowed<'pool>>> {
        let len = self.len();
        // SAFETY: this source retains its selected range in the fully initialized slot,
        // independently of the span's published prefix length.
        unsafe { pool::raw::into_shared(self.span, self.start as usize, len) }
    }
}

const _: () = {
    assert!(size_of::<Slice<'static>>() == 3 * size_of::<usize>());
    assert!(size_of::<Option<Slice<'static>>>() == size_of::<Slice<'static>>());
};