Skip to main content

uqa_execution/row_locks/
registry.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Shared manager registry, relation identity allocation, and transaction IDs.
8
9use super::{
10    table_hash, Arc, AtomicU64, Condvar, CrossAttachment, FileLockCoordinator, HashMap,
11    LockRelationIdentity, LockTable, ManagerIdentity, Mutex, OnceLock, Ordering, RowLockManager,
12    RwLock, SQLError, Weak,
13};
14
15static DATABASE_MANAGERS: OnceLock<Mutex<HashMap<ManagerIdentity, Weak<RowLockManager>>>> =
16    OnceLock::new();
17
18impl Default for RowLockManager {
19    fn default() -> Self {
20        Self::new()
21    }
22}
23
24impl RowLockManager {
25    pub fn new() -> Self {
26        Self::with_cross_attachment(None)
27    }
28
29    fn with_cross_attachment(cross: Option<CrossAttachment>) -> Self {
30        Self {
31            baseline_owner: Weak::new(),
32            next_session: AtomicU64::new(1),
33            next_transaction_xid: AtomicU64::new(3),
34            catalog_oids: crate::catalog::identity::CatalogOidCounter::default(),
35            identities: super::identity_registry::IdentityRegistry::default(),
36            next_acquisition: AtomicU64::new(1),
37            change_gate: RwLock::new(()),
38            change_preparation: RwLock::new(()),
39            temporary_roles: Mutex::new(HashMap::new()),
40            sequence_positions: Mutex::default(),
41            state: Mutex::new(LockTable {
42                rows: HashMap::new(),
43                waiting: HashMap::new(),
44                relations: HashMap::new(),
45                waiting_relations: HashMap::new(),
46                advertised_waits: HashMap::new(),
47                changes: Vec::new(),
48                change_epoch: 0,
49                active_change_observers: 0,
50            }),
51            wake: Condvar::new(),
52            cross,
53        }
54    }
55
56    #[cfg(test)]
57    pub(super) fn for_database_file(path: &std::path::Path) -> Self {
58        Self::for_database_file_with_key(path, None)
59    }
60
61    fn for_database_file_with_key(
62        path: &std::path::Path,
63        key: Option<uqa_storage::StorageEncryptionKey>,
64    ) -> Self {
65        #[cfg(any(unix, windows))]
66        {
67            let cross = match FileLockCoordinator::open_with_key(path, key) {
68                Ok(coordinator) => CrossAttachment::Active(Arc::new(coordinator)),
69                Err(reason) => CrossAttachment::Unavailable(reason),
70            };
71            Self::with_cross_attachment(Some(cross))
72        }
73        #[cfg(not(any(unix, windows)))]
74        {
75            let _ = (path, key);
76            Self::with_cross_attachment(None)
77        }
78    }
79
80    pub fn allocate_session(&self) -> u64 {
81        self.next_session.fetch_add(1, Ordering::Relaxed)
82    }
83
84    pub fn allocate_transaction_xid(&self) -> Result<u32, SQLError> {
85        match self.cross.as_ref() {
86            Some(CrossAttachment::Active(coordinator)) => {
87                if let Some(xid) = coordinator
88                    .allocate_transaction_xid()
89                    .map_err(SQLError::Internal)?
90                {
91                    return Ok(xid);
92                }
93            }
94            Some(CrossAttachment::Unavailable(reason)) => {
95                return Err(SQLError::Internal(format!(
96                    "cross-process transaction XID allocation is unavailable: {reason}"
97                )));
98            }
99            None => {}
100        }
101        loop {
102            let current = self.next_transaction_xid.load(Ordering::Relaxed);
103            let xid = if (3..=u64::from(u32::MAX)).contains(&current) {
104                u32::try_from(current).expect("validated transaction XID fits u32")
105            } else {
106                3
107            };
108            let following = if xid == u32::MAX {
109                3
110            } else {
111                u64::from(xid + 1)
112            };
113            if self
114                .next_transaction_xid
115                .compare_exchange(current, following, Ordering::Relaxed, Ordering::Relaxed)
116                .is_ok()
117            {
118                return Ok(xid);
119            }
120        }
121    }
122
123    /// The database's OID counter for storage without durable identifier reservations; storage with them keeps the counter's position itself.
124    pub const fn catalog_oids(&self) -> &crate::catalog::identity::CatalogOidCounter {
125        &self.catalog_oids
126    }
127
128    pub fn table_key(&self, table: &str) -> u64 {
129        self.relation_key(LockRelationIdentity::Table(Arc::from(table)))
130    }
131
132    /// An index keeps its relation lock across renames and receives a new one after same-name recreation.
133    pub fn index_key(&self, identity: [u8; 16]) -> u64 {
134        self.relation_key(LockRelationIdentity::Index(identity))
135    }
136
137    pub fn shared_catalog_key(&self, target: super::shared_objects::SharedCatalogLock<'_>) -> u64 {
138        use super::shared_objects::SharedCatalogLock;
139        self.relation_key(match target {
140            SharedCatalogLock::Object { class_id, oid } => {
141                LockRelationIdentity::SharedObject { class_id, oid }
142            }
143            SharedCatalogLock::Name { class_id, name } => LockRelationIdentity::SharedObjectName {
144                class_id,
145                name: Arc::from(name),
146            },
147            SharedCatalogLock::MemberName {
148                class_id,
149                owner_class_id,
150                owner_object_id,
151                name,
152            } => LockRelationIdentity::SharedMemberName {
153                class_id,
154                owner_class_id,
155                owner_object_id,
156                name: Arc::from(name),
157            },
158            SharedCatalogLock::Tuple { class_id, oid } => {
159                LockRelationIdentity::SharedObjectTuple { class_id, oid }
160            }
161        })
162    }
163
164    /// Reserve generated identities independently of tuple locks and SQL constraint keys. One namespace per table keeps registry metadata independent of the number of allocated rows.
165    pub fn document_identity_key(&self, table: &str) -> u64 {
166        self.relation_key(LockRelationIdentity::DocumentIdentityReservations(
167            Arc::from(table),
168        ))
169    }
170
171    pub fn backend_writer_key(&self) -> u64 {
172        self.relation_key(LockRelationIdentity::BackendWriter)
173    }
174
175    #[doc(hidden)]
176    pub fn waiting_for_backend_writer(&self, session_id: u64) -> bool {
177        self.waiting_for_relation(session_id, self.backend_writer_key())
178    }
179
180    #[doc(hidden)]
181    pub fn waiting_for_relation(&self, session_id: u64, key: u64) -> bool {
182        self.state
183            .lock()
184            .waiting_relations
185            .get(&session_id)
186            .is_some_and(|relations| relations.contains_key(&key))
187    }
188
189    #[doc(hidden)]
190    pub fn waiting_for_row(&self, session_id: u64, key: super::RowLockKey) -> bool {
191        self.state
192            .lock()
193            .waiting
194            .get(&session_id)
195            .is_some_and(|rows| rows.contains_key(&key))
196    }
197
198    /// Retain a permanent numeric key for existing callers. SQL requests use `retain_key_reservation` so completed keys can be reclaimed.
199    pub fn key_reservation_key(&self, digest: [u8; 32]) -> u64 {
200        self.relation_key(LockRelationIdentity::KeyReservation(digest))
201    }
202
203    /// Retain a transient key identity while constructing requests; successful grants retain it until release.
204    pub fn retain_key_reservation(&self, digest: [u8; 32]) -> super::KeyReservationIdentity {
205        self.identities.key(digest)
206    }
207
208    /// Coordinate one named scoring-parameter value without locking unrelated signals or SQL tables.
209    pub fn scoring_parameters_key(&self, name: &str) -> u64 {
210        self.relation_key(LockRelationIdentity::ScoringParameters(Arc::from(name)))
211    }
212
213    fn relation_key(&self, identity: LockRelationIdentity) -> u64 {
214        self.identities.permanent(identity)
215    }
216
217    pub fn stable_table_hash(table: &str) -> u64 {
218        table_hash(table.as_bytes())
219    }
220
221    pub fn table_name(&self, table: u64) -> Arc<str> {
222        match self.identities.identity(table) {
223            Some(LockRelationIdentity::Table(name)) => name,
224            Some(_) => panic!("internal lock identity has no SQL table name"),
225            None => panic!("unknown relation lock identity"),
226        }
227    }
228
229    pub(super) fn relation_bytes(&self, table: u64) -> Vec<u8> {
230        self.identities
231            .identity(table)
232            .unwrap_or_else(|| panic!("unknown relation lock identity"))
233            .stable_bytes()
234    }
235
236    pub(super) fn coordinator(&self) -> Result<Option<&FileLockCoordinator>, SQLError> {
237        match self.cross.as_ref() {
238            None => Ok(None),
239            Some(CrossAttachment::Active(coordinator)) => Ok(Some(coordinator)),
240            Some(CrossAttachment::Unavailable(reason)) => Err(SQLError::Internal(format!(
241                "cross-process lock coordination is unavailable: {reason}"
242            ))),
243        }
244    }
245
246    /// Whether this manager has durable cross-process coordination. Unlike a peer-liveness check, this remains true after a peer exits, because commits made by that peer can still be newer than a statement snapshot.
247    pub fn has_cross_process_coordination(&self) -> bool {
248        matches!(self.cross.as_ref(), Some(CrossAttachment::Active(_)))
249    }
250}
251
252pub fn shared_provider_manager(
253    identity: Option<uqa_storage::PersistentStorageIdentity>,
254    provider: &Arc<dyn uqa_storage::PersistentStorageProvider>,
255) -> Arc<RowLockManager> {
256    shared_manager(
257        identity,
258        ManagerIdentity::Provider(Arc::as_ptr(provider).cast::<()>() as usize),
259        provider.auxiliary_encryption_key(),
260    )
261}
262
263pub fn shared_backend_manager(
264    identity: Option<uqa_storage::PersistentStorageIdentity>,
265    backend: &Arc<dyn uqa_storage::PersistentStorageBackend>,
266) -> Arc<RowLockManager> {
267    shared_manager(
268        identity,
269        ManagerIdentity::Provider(Arc::as_ptr(backend).cast::<()>() as usize),
270        backend.auxiliary_encryption_key(),
271    )
272}
273
274fn shared_manager(
275    identity: Option<uqa_storage::PersistentStorageIdentity>,
276    fallback: ManagerIdentity,
277    key: Option<uqa_storage::StorageEncryptionKey>,
278) -> Arc<RowLockManager> {
279    let identity = identity.map_or(fallback, ManagerIdentity::Durable);
280    let registry = DATABASE_MANAGERS.get_or_init(|| Mutex::new(HashMap::new()));
281    let mut registry = registry.lock();
282    registry.retain(|_, manager| manager.strong_count() != 0);
283    if let Some(manager) = registry.get(&identity).and_then(Weak::upgrade) {
284        return manager;
285    }
286    let manager = Arc::new_cyclic(|owner| {
287        let mut manager = match &identity {
288            ManagerIdentity::Durable(uqa_storage::PersistentStorageIdentity::File(path)) => {
289                RowLockManager::for_database_file_with_key(path, key)
290            }
291            _ => RowLockManager::new(),
292        };
293        manager.baseline_owner = owner.clone();
294        manager
295    });
296    registry.insert(identity, Arc::downgrade(&manager));
297    manager
298}
299
300#[cfg(test)]
301mod tests {
302    use super::*;
303
304    #[test]
305    fn a_retained_baseline_preserves_the_single_registered_coordinator() {
306        let directory = tempfile::tempdir().unwrap();
307        let path = directory.path().join("retained.db");
308        let open = || {
309            shared_manager(
310                Some(uqa_storage::PersistentStorageIdentity::File(path.clone())),
311                ManagerIdentity::Provider(0),
312                None,
313            )
314        };
315        let manager = open();
316        let identity = Arc::downgrade(&manager);
317        let baseline = manager
318            .begin_change_snapshot(&uqa_core::CancellationToken::new())
319            .unwrap()
320            .baseline()
321            .unwrap();
322        drop(manager);
323        let reopened = open();
324        assert!(Arc::ptr_eq(&identity.upgrade().unwrap(), &reopened));
325        drop(reopened);
326        assert!(identity.upgrade().is_some());
327        drop(baseline);
328        assert!(identity.upgrade().is_none());
329    }
330}