o3 0.26.4

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

use std::ops;

use crate::{
    buffer,
    buffer::{resident, segments, segments::Seal, storage, storage::regions, write::consume},
    mem::rc,
};
/// Retained bytes that narrow without copying their payload.
/// # Safety
/// Shared access preserves the range, and consuming advances its exact prefix.
pub unsafe trait Segment: Seal + AsRef<[u8]> + consume::Consume + buffer::Residency {
    /// # Safety
    /// Preserve this owner's exact initialized extent and its original backing.
    unsafe fn extent(&mut self) -> &mut regions::Extent;

    fn try_clone(&self) -> Result<Self, rc::Error> {
        buffer::View::new(self).try_retain()
    }

    fn try_get(&self, range: ops::Range<usize>) -> Result<Option<Self>, rc::Error> {
        buffer::View::new(self)
            .get(range)
            .map(buffer::View::<Self>::try_retain)
            .transpose()
    }

    /// Retains an in-bounds owner subrange without copying its payload.
    /// # Safety
    /// `range` must lie within the owner's visible bytes.
    unsafe fn try_project(&self, range: ops::Range<usize>) -> Result<Self, rc::Error> {
        let bytes = unsafe { self.as_ref().get_unchecked(range) };
        buffer::View {
            source: self,
            bytes,
        }
        .try_retain()
    }

    /// Retains at most `limit` leading bytes without copying the payload.
    fn prefix(self, limit: usize) -> Self {
        Seal::truncate(self, limit)
    }

    /// Splits off at most `limit` visible bytes without copying the payload.
    fn try_split(mut self, limit: usize) -> Result<(Self, Option<Self>), (rc::Error, Self)> {
        let Some(tail) = segments::Tail::new(&mut self, limit) else {
            return Ok((self, None));
        };
        let prefix = match tail.try_commit() {
            Ok(result) => result,
            Err(error) => return Err((error, self)),
        };
        Ok((prefix, Some(self)))
    }

    /// Removes at most `amount` visible bytes without copying the payload.
    fn suffix(mut self, amount: usize) -> Option<Self> {
        segments::Tail::new(&mut self, amount)?.commit();
        Some(self)
    }
}
// SAFETY: shared storage changes its visible range only through exclusive access.
unsafe impl Segment for storage::Shared {
    unsafe fn extent(&mut self) -> &mut regions::Extent {
        // SAFETY: the caller preserves this exact owner and initialized subrange.
        unsafe { self.extent_mut() }
    }
}

// SAFETY: resident storage retains its range and domain until exclusive mutation.
unsafe impl Segment for resident::Shared<'_> {
    unsafe fn extent(&mut self) -> &mut regions::Extent {
        // SAFETY: the caller preserves this exact owner and initialized subrange.
        unsafe { self.region.extent_mut() }
    }
}