o3 0.28.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

use std::{mem::MaybeUninit, slice};

use crate::{buffer, depot::arena::linked::slots};

/// # Safety
/// The nonnull pointer spans this owner's initialized prefix, retained in one
/// live allocation when nonempty. The prefix fits `isize`, satisfies the
/// empty-range pointer rules when empty, and stays immutable during shared access.
pub(in crate::buffer) unsafe trait Prefix {
    fn prefix(&self) -> (*mut MaybeUninit<u8>, u32);

    fn as_slice(&self) -> &[u8] {
        let (pointer, len) = self.prefix();
        // SAFETY: the backend retains this exact initialized prefix for this borrow.
        unsafe { buffer::raw::range(pointer.cast(), 0, len as usize) }
    }
}

/// # Safety
/// A nonnull, `isize`-bounded capacity span is disjoint from its length word.
/// The initialized prefix uses the same pointer and length as [`Prefix`] and fits capacity.
/// Each mutable loan retains exclusive access to its selected range.
/// Nonempty spans lie within one live allocation retained for every loan;
/// empty spans retain a valid pointer. Pure projections retain provenance,
/// owner, length and capacity; writes and growth preserve these proofs.
pub(in crate::buffer) unsafe trait Exclusive: Prefix {
    fn as_mut_ptr(&mut self) -> *mut MaybeUninit<u8>;

    fn len_mut(&mut self) -> &mut u32;

    fn capacity(&self) -> u32;

    fn as_mut_slice(&mut self) -> &mut [u8] {
        let pointer = self.as_mut_ptr();
        let len = self.len_mut();
        // SAFETY: this exclusive owner retains its exact initialized prefix.
        unsafe { buffer::raw::range_mut(pointer.cast(), 0, *len as usize) }
    }

    fn spare_parts(&mut self) -> (&mut u32, &mut [MaybeUninit<u8>]) {
        let capacity = self.capacity();
        let pointer = self.as_mut_ptr();
        let len = self.len_mut();
        let used = *len as usize;
        // SAFETY: the backend pairs this length word with its disjoint live
        // allocation, whose remaining suffix is exclusive and unpublished.
        let spare =
            unsafe { slice::from_raw_parts_mut(pointer.add(used), capacity as usize - used) };
        (len, spare)
    }

    fn fill(&mut self, byte: u8) {
        let capacity = self.capacity();
        let pointer = self.as_mut_ptr();
        let len = self.len_mut();
        // SAFETY: this exclusive backend retains every unpublished byte,
        // and writing u8 initializes the complete remaining prefix.
        unsafe {
            pointer
                .add(*len as usize)
                .cast::<u8>()
                .write_bytes(byte, (capacity - *len) as usize);
        }
        *len = capacity;
    }
}

/// # Safety
/// The consumed owner retains this exact initialized node for `'a`.
/// Shared projection prevents mutation or release throughout the returned borrow.
pub(in crate::buffer) unsafe trait Indexed<'a>: Sized {
    type Item: 'a;

    fn parts(self) -> (&'a slots::Store<Self::Item>, slots::Index);

    fn get(self) -> &'a Self::Item {
        let (store, index) = self.parts();
        // SAFETY: the consumed native owner retains this exact initialized slot.
        unsafe { store.value(index) }
    }
}

/// # Safety
/// The consumed owner exclusively retains its selected node for `'a`.
pub(in crate::buffer) unsafe trait IndexedMut<'a>: Indexed<'a> {
    fn get_mut(self) -> &'a mut Self::Item {
        let (store, index) = self.parts();
        // SAFETY: this native owner lends its exact live node exclusively.
        unsafe { &mut *store.value_ptr(index) }
    }
}

/// # Safety
/// The owner retains this live descriptor and its initialized node partition for `'a`.
/// Its head names a live node in that partition throughout shared projection.
pub(in crate::buffer) unsafe trait Linked<'a>: Sized {
    type Item: 'a;
    type Metadata: 'a;

    fn parts(
        self,
    ) -> (
        &'a slots::Store<Self::Item>,
        &'a slots::Store<Self::Metadata>,
        slots::Index,
    );

    fn head(metadata: &Self::Metadata) -> slots::Index;

    fn metadata(self) -> &'a Self::Metadata {
        let (_, descs, index) = self.parts();
        // SAFETY: this owner retains its exact initialized descriptor.
        unsafe { descs.value(index) }
    }

    fn front(self) -> &'a Self::Item {
        let (nodes, descs, index) = self.parts();
        // SAFETY: the descriptor and its initialized head belong to this same owner.
        let desc = unsafe { descs.value(index) };
        unsafe { nodes.value(Self::head(desc)) }
    }
}

/// # Safety
/// The owner exclusively retains its descriptor and disjoint node partition for `'a`.
pub(in crate::buffer) unsafe trait LinkedMut<'a>: Linked<'a> {
    fn front_mut(self) -> (&'a mut Self::Metadata, &'a mut Self::Item) {
        let (nodes, descs, index) = self.parts();
        // SAFETY: the original owner exclusively retains both live values in
        // distinct stores, and its descriptor selects only its own node partition.
        unsafe {
            let desc = &mut *descs.value_ptr(index);
            let item = &mut *nodes.value_ptr(Self::head(desc));
            (desc, item)
        }
    }
}