Skip to main content

uqa_execution/row_locks/
identity_registry.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Stable table identities and explicitly retained transient key identities.
8
9use super::{Arc, HashMap, LockRelationIdentity, Mutex, Weak};
10
11struct Record {
12    identity: LockRelationIdentity,
13    permanent: bool,
14    retained: Weak<Retained>,
15}
16
17struct State {
18    next: u64,
19    by_identity: HashMap<LockRelationIdentity, u64>,
20    by_id: HashMap<u64, Record>,
21}
22
23pub(super) struct IdentityRegistry(Arc<Mutex<State>>);
24
25impl Default for IdentityRegistry {
26    fn default() -> Self {
27        Self(Arc::new(Mutex::new(State {
28            next: 1,
29            by_identity: HashMap::new(),
30            by_id: HashMap::new(),
31        })))
32    }
33}
34
35struct Retained {
36    table: u64,
37    registry: Weak<Mutex<State>>,
38}
39
40/// Keeps a complete key identity available while requests are built. Successful acquisitions retain their own handle through native release. Numeric keys obtained from this handle must not outlive their owner unless promoted through the permanent-key API.
41#[derive(Clone)]
42pub struct KeyReservationIdentity(Arc<Retained>);
43
44impl std::fmt::Debug for KeyReservationIdentity {
45    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
46        formatter
47            .debug_struct("KeyReservationIdentity")
48            .field("table", &self.table_key())
49            .finish_non_exhaustive()
50    }
51}
52
53impl KeyReservationIdentity {
54    #[must_use]
55    pub fn table_key(&self) -> u64 {
56        self.0.table
57    }
58}
59
60impl Drop for Retained {
61    fn drop(&mut self) {
62        let Some(registry) = self.registry.upgrade() else {
63            return;
64        };
65        let mut state = registry.lock();
66        if state
67            .by_id
68            .get(&self.table)
69            .is_some_and(|record| !record.permanent)
70        {
71            let record = state.by_id.remove(&self.table).expect("retained identity");
72            if state.by_identity.get(&record.identity) == Some(&self.table) {
73                state.by_identity.remove(&record.identity);
74            }
75            // Reclaim high-water allocations geometrically, not once per removed key.
76            let retained = state.by_id.len().saturating_mul(4).max(64);
77            if state.by_id.capacity() > retained {
78                state.by_id.shrink_to(retained);
79                state.by_identity.shrink_to(retained);
80            }
81        }
82    }
83}
84
85impl State {
86    fn insert(&mut self, identity: LockRelationIdentity, permanent: bool) -> u64 {
87        let table = self.next;
88        self.next = self
89            .next
90            .checked_add(1)
91            .expect("lock identity space exhausted");
92        self.by_identity.insert(identity.clone(), table);
93        self.by_id.insert(
94            table,
95            Record {
96                identity,
97                permanent,
98                retained: Weak::new(),
99            },
100        );
101        table
102    }
103}
104
105impl IdentityRegistry {
106    pub(super) fn permanent(&self, identity: LockRelationIdentity) -> u64 {
107        let mut state = self.0.lock();
108        if let Some(table) = state.by_identity.get(&identity).copied() {
109            state
110                .by_id
111                .get_mut(&table)
112                .expect("interned identity")
113                .permanent = true;
114            return table;
115        }
116        state.insert(identity, true)
117    }
118
119    pub(super) fn key(&self, digest: [u8; 32]) -> KeyReservationIdentity {
120        let identity = LockRelationIdentity::KeyReservation(digest);
121        let mut state = self.0.lock();
122        let existing = state.by_identity.get(&identity).copied();
123        let table = if let Some(table) = existing {
124            let record = &state.by_id[&table];
125            if let Some(retained) = record.retained.upgrade() {
126                return KeyReservationIdentity(retained);
127            }
128            if record.permanent {
129                table
130            } else {
131                // The last owner may be waiting for this mutex to finish its destructor.
132                state.by_id.remove(&table);
133                state.insert(identity, false)
134            }
135        } else {
136            state.insert(identity, false)
137        };
138        let retained = Arc::new(Retained {
139            table,
140            registry: Arc::downgrade(&self.0),
141        });
142        state
143            .by_id
144            .get_mut(&table)
145            .expect("interned identity")
146            .retained = Arc::downgrade(&retained);
147        KeyReservationIdentity(retained)
148    }
149
150    pub(super) fn retain(&self, table: u64) -> Option<KeyReservationIdentity> {
151        self.0
152            .lock()
153            .by_id
154            .get(&table)?
155            .retained
156            .upgrade()
157            .map(KeyReservationIdentity)
158    }
159
160    pub(super) fn identity(&self, table: u64) -> Option<LockRelationIdentity> {
161        self.0
162            .lock()
163            .by_id
164            .get(&table)
165            .map(|record| record.identity.clone())
166    }
167
168    #[cfg(test)]
169    pub(super) fn retained_counts(&self) -> (usize, usize, usize, usize) {
170        let state = self.0.lock();
171        (
172            state.by_id.len(),
173            state.by_identity.len(),
174            state.by_id.capacity(),
175            state.by_identity.capacity(),
176        )
177    }
178}
179
180#[cfg(test)]
181mod tests;