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

use std::{marker, ops, ptr};

use planes::map::{State, Table};

use crate::depot::{
    map,
    queue::{
        indexed::planes::{
            self,
            map::{Hooks, Record, Slot},
            phase,
        },
        links,
    },
};

/// Installed payload, physical position, and directory membership in one owner.
pub struct Occupied<'a, K, V, const N: usize, P = ()> {
    pub(in crate::depot::queue::indexed::planes::map) owner: &'a mut Table<K, V, N>,
    pub(in crate::depot::queue::indexed::planes::map) index: links::Index,
    phase: marker::PhantomData<P>,
}

impl<'a, K, V, const N: usize, P> Occupied<'a, K, V, N, P> {
    pub(in crate::depot::queue::indexed::planes::map) fn new(
        owner: &'a mut Table<K, V, N>,
        index: links::Index,
    ) -> Self {
        Self {
            owner,
            index,
            phase: marker::PhantomData,
        }
    }
    fn record(&self) -> &Record<K, V> {
        // SAFETY: Occupied retains this owner's installed record and its complete loan.
        unsafe { self.owner.core.record(self.index) }
    }

    pub fn key(&self) -> &K {
        &self.record().key
    }
}

impl<K, V, const N: usize> Occupied<'_, K, V, N> {
    fn parts_mut(&mut self) -> (&mut Record<K, V>, Slot<'_, K, V, N>) {
        let core = &self.owner.core;
        let slot = Slot::new(core, self.index);
        // SAFETY: the exclusive owner lends this installed record; Slot exposes only disjoint hooks.
        let record = unsafe { (*core.node(self.index).record.get()).assume_init_mut() };
        (record, slot)
    }

    pub fn plane<const P: usize>(&mut self) -> State<'_, K, V, N, P> {
        State::new(Slot::new(&self.owner.core, self.index))
    }

    pub fn split<const P: usize>(&mut self) -> (&mut V, State<'_, K, V, N, P>) {
        let (record, slot) = self.parts_mut();
        (&mut record.value, State::new(slot))
    }

    pub fn remove(self) -> (K, V) {
        let record = self.record();
        // SAFETY: removal consumes the sole record loan and its still-live reverse bucket.
        let bucket = unsafe { ptr::read(&record.bucket) };
        unsafe { map::raw::Hole::retire(&mut *self.owner, bucket) };
        let core = &self.owner.core;
        let node = unsafe { core.node(self.index) };
        unsafe {
            core.queues[0]
                .unlink(&Hooks { core, plane: 0 }, self.index)
                .idle()
        };
        for plane in 1..N {
            if self.index.is_linked(&node.hooks[plane]) {
                unsafe {
                    core.queues[plane]
                        .unlink(&Hooks { core, plane }, self.index)
                        .idle()
                };
            }
        }
        let record = unsafe { (*node.record.get()).assume_init_read() };
        (record.key, record.value)
    }
}

impl<K, V, const N: usize, P> ops::Deref for Occupied<'_, K, V, N, P> {
    type Target = V;

    fn deref(&self) -> &V {
        &self.record().value
    }
}

impl<K, V, const N: usize> ops::DerefMut for Occupied<'_, K, V, N> {
    fn deref_mut(&mut self) -> &mut V {
        &mut self.parts_mut().0.value
    }
}

impl<'a, K, V, const N: usize, const P: usize> Occupied<'a, K, V, N, phase::Front<P>> {
    pub fn pop(self) -> Occupied<'a, K, V, N> {
        let core = &self.owner.core;
        let hooks = Hooks { core, plane: P };
        // SAFETY: this phase retains the exact front and its original plane.
        crate::depot::raw::Removal::commit(unsafe {
            crate::depot::raw::Pop::at(&core.queues[P], &hooks, self.index)
        })
        .idle();
        Occupied::new(self.owner, self.index)
    }
}