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