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

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

use crate::depot::{self, queue::ring};

impl<T> ring::Fifo<T> {
    pub fn front(&self) -> Option<&T> {
        if self.state.is_empty() {
            return None;
        }
        // SAFETY: this nonempty FIFO's shared borrow retains its initialized head.
        Some(unsafe { &*self.block.as_ptr().add(self.state.head()).cast::<T>() })
    }

    pub fn get(&self, index: usize) -> Option<&T> {
        if index >= self.state.len() {
            return None;
        }
        let position = unsafe { self.state.position(self.capacity(), index) };
        // SAFETY: the bounds check admits this initialized logical offset.
        Some(unsafe { &*self.block.as_ptr().add(position).cast::<T>() })
    }

    pub fn as_slices(&self) -> (&[T], &[T]) {
        let state = self.state;
        let (start, [front, back]) = state.prefix(self.capacity(), state.len());
        let entries = self.block.as_ptr().cast::<T>();
        // SAFETY: this FIFO retains the two exact initialized runs for this borrow.
        unsafe {
            (
                slice::from_raw_parts(entries.add(start), front),
                slice::from_raw_parts(entries, back),
            )
        }
    }
}

/// # Safety
/// Consume both initialized runs exclusively, without outstanding loans or reentry.
/// Do not access or destroy these elements again; clear their state before
/// any later owner operation, or finish destruction without revisiting them.
pub(crate) unsafe fn drop_ring<S: depot::raw::RingEdit + ?Sized>(source: &mut S) {
    if mem::needs_drop::<S::Item>() {
        // SAFETY: exclusive ownership retains both disjoint initialized runs.
        let (front, back) = unsafe { depot::raw::RingEdit::slices_mut(source) };
        // SAFETY: both runs are consumed exactly once without competing access.
        unsafe {
            ptr::drop_in_place(front);
            ptr::drop_in_place(back);
        }
    }
}

// SAFETY: state and backing are disjoint parts of this exact exclusive owner.
unsafe impl<T> crate::depot::raw::RingEdit for ring::Fifo<T> {
    unsafe fn parts_mut(&mut self) -> (&mut ring::State<u32>, &mut [mem::MaybeUninit<T>]) {
        (&mut self.state, &mut self.block)
    }
}

// SAFETY: operations publish synchronously and never lend resident references.
unsafe impl<T, S> crate::depot::raw::RingCell for ring::pool::Shared<T, S> {
    unsafe fn publish(&self, state: ring::State<u32>) {
        self.state.set(state);
    }
}

// SAFETY: exclusive ownership rules out shared mutations of this disjoint state and backing.
unsafe impl<T, S> crate::depot::raw::RingEdit for ring::pool::Shared<T, S> {
    unsafe fn parts_mut(&mut self) -> (&mut ring::State<u32>, &mut [mem::MaybeUninit<T>]) {
        (self.state.get_mut(), &mut self.block)
    }
}

// SAFETY: this owner initializes exactly its state's logical range in block.
unsafe impl<T> crate::depot::raw::RingStore for ring::Fifo<T> {
    type Item = T;
    type Word = u32;

    fn state(&self) -> ring::State<u32> {
        self.state
    }
    fn capacity(&self) -> usize {
        self.capacity()
    }
    fn entries(&self) -> *const mem::MaybeUninit<T> {
        self.block.as_ptr()
    }
}

// SAFETY: the shared cell owns exactly the initialized range described by state.
unsafe impl<T, S> crate::depot::raw::RingStore for ring::pool::Shared<T, S> {
    type Item = T;
    type Word = u32;
    fn state(&self) -> ring::State<u32> {
        self.state.get()
    }
    fn capacity(&self) -> usize {
        self.capacity()
    }
    fn entries(&self) -> *const mem::MaybeUninit<T> {
        self.block.as_ptr()
    }
}