o3 0.14.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
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
145
146
147
148
149
150
151
152
153
154
155
156
157
158

pub mod bytes;
pub mod pool;
pub mod queue;
mod sealed;
pub mod storage;
pub mod view;
pub mod write;

use std::{error, fmt, ops};

pub(crate) use sealed::Seal;
pub use sealed::{Frozen, Layout, Lease, Plan, Pool};

/// Reports the logical byte prefix that an exclusive owner may consume.
pub trait PrefixLength {
    fn prefix_len(&self) -> usize;
}

/// Owns a logical byte prefix that can be consumed after it is proven to fit.
/// Only [`ValidatedPrefix`] can construct the proof passed to this method.
pub trait PrefixConsumer: PrefixLength {
    fn consume_validated_prefix(&mut self, proof: PrefixProof);

    fn try_consume_prefix(
        &mut self,
        amount: usize,
    ) -> Result<ValidatedPrefix<'_, Self>, CapacityError> {
        ValidatedPrefix::try_new(self, amount)
    }

    fn consume_prefix_up_to(&mut self, requested: usize) -> usize {
        let prefix = ValidatedPrefix::up_to(self, requested);
        let amount = prefix.len();
        prefix.commit();
        amount
    }
}

/// An unforgeable proof that one prefix fits its exclusively borrowed owner.
#[doc(hidden)]
pub struct PrefixProof {
    amount: usize,
}

impl PrefixProof {
    fn new(amount: usize) -> Self {
        Self { amount }
    }

    pub const fn amount(&self) -> usize {
        self.amount
    }
}

/// Proof that `amount` fits one exclusively borrowed target prefix.
#[must_use]
pub struct ValidatedPrefix<'a, T: PrefixConsumer + ?Sized> {
    target: &'a mut T,
    proof: PrefixProof,
}

impl<'a, T: PrefixConsumer + ?Sized> ValidatedPrefix<'a, T> {
    fn try_new(target: &'a mut T, amount: usize) -> Result<Self, CapacityError> {
        let available = target.prefix_len();
        if amount > available {
            return Err(CapacityError::new(amount, available));
        }
        Ok(Self {
            target,
            proof: PrefixProof::new(amount),
        })
    }

    /// Proves the largest prefix no longer than `requested`.
    fn up_to(target: &'a mut T, requested: usize) -> Self {
        let amount = requested.min(target.prefix_len());
        Self {
            target,
            proof: PrefixProof::new(amount),
        }
    }

    const fn len(&self) -> usize {
        self.proof.amount()
    }
}

impl<T: PrefixConsumer + ?Sized> ValidatedPrefix<'_, T> {
    /// Applies the validated mutation exactly once.
    pub fn commit(self) {
        self.target.consume_validated_prefix(self.proof);
    }
}

pub const BLOCK_CAPACITY: u32 = 64 * 1024;

#[derive(Clone, Copy, PartialEq, Eq)]
pub struct CapacityError {
    attempted: usize,
    capacity: usize,
}

impl CapacityError {
    const fn new(attempted: usize, capacity: usize) -> Self {
        Self {
            attempted,
            capacity,
        }
    }
}

impl fmt::Debug for CapacityError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CapacityError")
            .field("attempted", &self.attempted)
            .field("capacity", &self.capacity)
            .finish()
    }
}

impl fmt::Display for CapacityError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "capacity exceeded: attempted {}, capacity {}",
            self.attempted, self.capacity
        )
    }
}

impl error::Error for CapacityError {}

fn checked_append_len<const N: usize>(
    start: usize,
    capacity: usize,
    slices: &[&[u8]; N],
) -> Result<usize, CapacityError> {
    let mut end = start;
    for slice in slices {
        end = end
            .checked_add(slice.len())
            .ok_or_else(|| CapacityError::new(usize::MAX, capacity))?;
        if end > capacity {
            return Err(CapacityError::new(end, capacity));
        }
    }
    Ok(end)
}

trait RangeExt {
    fn is_within(&self, len: usize) -> bool;
}

impl RangeExt for ops::Range<usize> {
    fn is_within(&self, len: usize) -> bool {
        self.start <= self.end && self.end <= len
    }
}