o3 0.34.2

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

//! Fixed-capacity FIFO handoff of affine grants.

use std::mem;

use crate::depot::queue::resident;

mod lane;
mod registry;

pub use lane::Lane;
pub use registry::Registry;

/// A linear registration in a [`Registry`]. Value and grant payloads are
/// invariant, so safe code cannot widen borrowed ownership.
///
#[repr(transparent)]
pub struct Registration<'target, W, G, L> {
    lease: resident::Lease<'target, Registry<W, G, L>>,
}

impl<W, G, L> Default for Registration<'_, W, G, L> {
    fn default() -> Self {
        Self::new()
    }
}

impl<W, G, L> Registration<'_, W, G, L> {
    pub const fn new() -> Self {
        Self {
            lease: resident::Lease::new(),
        }
    }

    /// Cancels the registration, retiring a pending value at its registry and
    /// returning any delivered grant to the caller.
    pub fn cancel(&mut self) -> Cancel<G> {
        let Some((registry, key)) = self.lease.active() else {
            return Cancel::Empty;
        };
        let key = *key;
        self.lease.detach();
        match registry.lanes.remove(key) {
            resident::Removal::Linked => Cancel::Wake,
            resident::Removal::Parked(entry) => Cancel::Grant(entry.take_grant()),
            resident::Removal::Empty => Cancel::Empty,
        }
    }

    pub fn take_grant(&mut self) -> Grant<G> {
        let Some((registry, key)) = self.lease.active() else {
            return Grant::Empty;
        };
        let Some(entry) = registry.lanes.claim(*key) else {
            return Grant::Pending;
        };
        self.lease.detach();
        Grant::Ready(entry.take_grant())
    }
}

const _: () = {
    assert!(
        mem::size_of::<Registration<'static, usize, usize, resident::Fixed<2>>>()
            == 2 * mem::size_of::<usize>()
    );
    assert!(
        mem::align_of::<Registration<'static, usize, usize, resident::Fixed<2>>>()
            == mem::align_of::<usize>()
    );
};

/// A registration whose current handoff binding rejected an update.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use = "a rejected registration must be handled"]
pub enum Reject {
    Active { index: usize },
    Draining { index: usize },
    Full { index: usize },
    GrantPending { index: usize },
}

/// Exact result of one grant offer.
#[derive(Eq, PartialEq)]
#[must_use = "a rejected affine grant remains caller-owned"]
pub enum Offer<W, G> {
    Value(W),
    Draining(G),
    Empty(G),
}

/// State of an affine grant retained by one registration.
#[derive(Eq, PartialEq)]
pub enum Grant<G> {
    Empty,
    Pending,
    Ready(G),
}

#[must_use = "a delivered affine grant remains caller-owned"]
#[derive(Eq, PartialEq)]
pub enum Cancel<G> {
    Empty,
    Wake,
    Grant(G),
}