o3 0.27.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
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
137
138
139
140
141
142
143
144

use std::num;

use crate::buffer::{self, write, write::consume::Error};

/// Exact-length staged write shortfall.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[repr(C)]
pub struct Gap(num::NonZero<u32>, u32);

/// A staged span whose publication policy is selected in its type.
#[must_use = "commit the initialized span to publish bytes"]
pub struct Writer<'writer, 'target, const EXACT: bool> {
    spare: &'writer mut write::Spare<'target>,
    limit: u32,
    len: u32,
}

impl Gap {
    pub(in crate::buffer) fn check(expected: u32, actual: u32) -> Result<(), Self> {
        if let Some(expected) = num::NonZero::new(expected)
            && actual < expected.get()
        {
            return Err(Self(expected, actual));
        }
        Ok(())
    }

    pub const fn into_parts(self) -> (num::NonZero<u32>, u32) {
        (self.0, self.1)
    }
}

impl<'writer, 'target, const EXACT: bool> Writer<'writer, 'target, EXACT> {
    pub(in crate::buffer::write) fn new(spare: &'writer mut write::Spare<'target>) -> Self {
        let limit = buffer::raw::Space::remaining(spare) as u32;
        Self {
            spare,
            limit,
            len: 0,
        }
    }

    pub(in crate::buffer) fn try_new(
        spare: &'writer mut write::Spare<'target>,
        len: usize,
    ) -> Result<Self, Error> {
        Error::check(len, buffer::raw::Space::remaining(spare))?;
        Ok(Self {
            spare,
            limit: len as u32,
            len: 0,
        })
    }

    pub(in crate::buffer) fn suffix(&mut self) -> (*mut u8, usize) {
        let start = self.spare.len() + self.len as usize;
        (self.spare.pointer.as_ptr().cast(), start)
    }

    /// # Safety
    /// Exactly `copied` admitted bytes were initialized in this writer's suffix.
    pub(in crate::buffer) unsafe fn extend(&mut self, copied: usize) {
        self.len += copied as u32;
    }

    fn publish(self) {
        self.spare.len += self.len;
    }

    /// Initializes one complete source after capacity admission. A shortfall
    /// leaves the destination unchanged and does not call the initializer.
    pub fn try_init<I: buffer::raw::Initializer + ?Sized>(
        &mut self,
        source: &I,
    ) -> Result<(), Error> {
        let len = source.len();
        Error::check(len, buffer::raw::Space::remaining(self))?;
        let (target, start) = self.suffix();
        // SAFETY: admission fits the source's stable length in this exclusive
        // suffix; its retained sources are disjoint from the writer's storage.
        unsafe { source.initialize(target.add(start).cast()) };
        // SAFETY: Initializer initialized exactly the admitted prefix before publication.
        unsafe { self.extend(len) };
        Ok(())
    }
}

impl<'writer, 'target> Writer<'writer, 'target, false> {
    pub fn commit(self) {
        self.publish();
    }
}

impl<'writer, 'target> Writer<'writer, 'target, true> {
    pub fn try_commit(self) -> Result<(), Gap> {
        Gap::check(self.limit, self.len)?;
        self.publish();
        Ok(())
    }
}

impl AsMut<[u8]> for Writer<'_, '_, true> {
    fn as_mut(&mut self) -> &mut [u8] {
        // SAFETY: Writer advances len only after initializing each byte and
        // retains exclusive access to the parent writer until publication.
        unsafe {
            buffer::raw::range_mut(
                self.spare.pointer.as_ptr().cast(),
                self.spare.len(),
                self.len as usize,
            )
        }
    }
}

impl<const EXACT: bool> write::Sink for Writer<'_, '_, EXACT> {
    type Error = Error;

    fn write_slices<const N: usize>(&mut self, slices: [&[u8]; N]) -> Result<(), Self::Error> {
        use buffer::raw::SliceExt as _;

        let len = Error::checked_end(0, buffer::raw::Space::remaining(self), &slices)?;
        let (target, start) = self.suffix();
        // SAFETY: admission retains every source and its exclusive suffix;
        // copying them initializes exactly the bytes published to this writer.
        unsafe {
            slices.copy_to(target.add(start));
            self.extend(len);
        }
        Ok(())
    }
}

impl<const EXACT: bool> buffer::raw::Space for Writer<'_, '_, EXACT> {
    fn remaining(&self) -> usize {
        (self.limit - self.len) as usize
    }
}

const _: () = assert!(size_of::<Gap>() == size_of::<u64>());
const _: () = assert!(size_of::<Option<Gap>>() == size_of::<u64>());
const _: () = assert!(size_of::<Result<(), Gap>>() == size_of::<u64>());
const _: () = assert!(size_of::<Writer<'static, 'static, false>>() == size_of::<usize>() * 2);
const _: () = assert!(size_of::<Writer<'static, 'static, true>>() == size_of::<usize>() * 2);