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

//! Unsafe boundary for borrowed resident nodes and their stable hooks.

use std::{cell, mem, ops, ptr};

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

/// One resident entry borrowed together with its exact compact identity.
pub struct View<'a, T> {
    item: &'a Node<T>,
    key: links::Index,
}

impl<T> Clone for View<'_, T> {
    fn clone(&self) -> Self {
        *self
    }
}

impl<T> Copy for View<'_, T> {}

impl<T> ops::Deref for View<'_, T> {
    type Target = Node<T>;

    fn deref(&self) -> &Self::Target {
        self.item
    }
}

impl<'a, T> View<'a, T> {
    /// # Safety
    /// `key` resolves a node in this exact slice.
    pub unsafe fn new(entries: &'a [Node<T>], key: links::Index) -> Self {
        let item = unsafe { entries.get_unchecked(key.get()) };
        Self { item, key }
    }

    /// # Safety
    /// Reachable hooks belong to these entries and form an acyclic vacant chain.
    pub unsafe fn acquire(free: &links::Free, entries: &'a [Node<T>]) -> Option<Self> {
        let key = unsafe { depot::raw::Hooks::acquire(Slice::new(entries), free) }?;
        Some(unsafe { Self::new(entries, key) })
    }

    pub fn key(&self) -> &links::Index {
        &self.key
    }

    pub fn into_ref(self) -> &'a Node<T> {
        self.item
    }

    pub fn is_parked(&self) -> bool {
        let hook = self.item.hook();
        hook.prev_index() == Some(self.key) && hook.next_index() == Some(self.key)
    }

    pub fn unpark(self) -> Option<links::Detached<'a>> {
        self.item.hook().try_unpark(self.key)
    }
}

const _: () = {
    assert!(mem::size_of::<View<'static, u64>>() == 2 * mem::size_of::<usize>());
    assert!(mem::size_of::<Option<View<'static, u64>>>() == 2 * mem::size_of::<usize>());
};

/// Borrowed stable hooks retaining the exact source slice's extent and lifetime.
#[repr(transparent)]
pub struct Slice<T>([Node<T>]);

impl<T> Slice<T> {
    pub fn new(entries: &[Node<T>]) -> &Self {
        // SAFETY: the transparent unsized view preserves the source pointer and length.
        unsafe { &*(ptr::from_ref(entries) as *const Self) }
    }
}

// SAFETY: each in-bounds node owns one stable hook for this exact borrowed slice.
unsafe impl<T> depot::raw::Hooks for Slice<T> {
    unsafe fn hook_raw(&self, index: links::Index) -> &links::Hook {
        unsafe { self.0.get_unchecked(index.get()) }.hook()
    }
}

const _: () = {
    assert!(mem::size_of::<&Slice<u8>>() == mem::size_of::<&[Node<u8>]>());
    assert!(mem::align_of::<&Slice<u8>>() == mem::align_of::<&[Node<u8>]>());
};

/// One optionally initialized resident payload.
pub struct Entry<T> {
    value: cell::Cell<mem::MaybeUninit<T>>,
}

impl<T> Default for Entry<T> {
    fn default() -> Self {
        Self {
            value: cell::Cell::new(mem::MaybeUninit::uninit()),
        }
    }
}

impl<T> Entry<T> {
    pub fn initialize(&self, value: T)
    where
        T: Copy,
    {
        self.value.set(mem::MaybeUninit::new(value));
    }

    /// # Safety
    /// The caller owns this exact initialized payload and consumes it once.
    /// No access may read or retire it again before its next initialization.
    pub unsafe fn take(&self) -> T {
        // SAFETY: the owning topology proves this entry's value is initialized.
        unsafe { self.value.replace(mem::MaybeUninit::uninit()).assume_init() }
    }

    /// # Safety
    /// The caller owns this exact initialized payload and its sole drop obligation.
    /// No access may read or retire it again before its next initialization.
    pub unsafe fn retire(&self) {
        let mut value = self.value.replace(mem::MaybeUninit::uninit());
        // SAFETY: the owning topology proves this entry's value is initialized.
        unsafe { value.assume_init_drop() };
    }
}

/// One resident value paired with its stable compact hook.
#[repr(C)]
pub struct Node<T> {
    value: T,
    hook: links::Hook,
}

impl<T> Node<T> {
    pub fn vacant(value: T, index: u32, next: u32) -> Self {
        Self {
            value,
            hook: links::Hook::vacant(index, next),
        }
    }

    pub const fn hook(&self) -> &links::Hook {
        &self.hook
    }
}

impl<T> ops::Deref for Node<T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        &self.value
    }
}