Skip to main content

uqa_execution/row_locks/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Process-wide logical row locks for `FOR UPDATE` / `FOR SHARE`.
8//!
9//! Locks follow `PostgreSQL` 18 tuple-lock conflict rules and are held until the owning session's transaction ends or a savepoint rolls back the acquisition. Sessions inside one process arbitrate through the in-memory lock table; engines in separate OS processes over the same durable database additionally coordinate through native byte-range locks on a sidecar file next to the database.
10
11mod batch;
12pub mod binding;
13mod change_gate;
14mod change_resolution;
15mod changes;
16mod cleanup;
17mod cross_process;
18mod grants;
19mod identity;
20mod identity_registry;
21mod physical_changes;
22mod registry;
23mod relation;
24mod sequence_positions;
25pub mod shared_objects;
26pub mod temporary_roles;
27mod waits;
28
29pub use change_gate::{RowChangePreparation, RowChangePublication};
30use change_resolution::{
31    epoch_is_after, mutation_strength, normalize_pending_row_changes, remove_inactive_versions,
32    resolve_local_change_target, row_has_waiter,
33};
34use std::collections::{HashMap, HashSet};
35use std::sync::atomic::{AtomicU64, Ordering};
36use std::sync::{Arc, OnceLock, Weak};
37use std::time::{Duration, Instant};
38
39use parking_lot::{Condvar, Mutex, MutexGuard, RwLock, RwLockReadGuard, RwLockWriteGuard};
40use uqa_core::DocId;
41use uqa_sql::ast::LockStrength;
42use uqa_sql::SQLError;
43
44use cross_process::{
45    change_gate_claim, row_byte_claims, table_hash, ByteClaim, FileLockCoordinator,
46};
47pub use physical_changes::PhysicalRowChangeTarget;
48use physical_changes::{resolve_local_physical_change_target, LocalPhysicalRowChangeTarget};
49
50const WAIT_SLICE: Duration = Duration::from_millis(50);
51const CHANGE_GATE_WAIT_LIMIT: Duration = Duration::from_secs(30);
52const CHANGE_GATE_SESSION: u64 = u64::MAX;
53
54#[cfg(test)]
55use change_gate::change_gate_timeout;
56use changes::{CommittedRowChange, CommittedRowChangeKind};
57pub use changes::{
58    PendingRowChange, PendingRowChangeKind, RowChangeBaseline, RowChangeObservation,
59    RowChangeTarget,
60};
61#[cfg(test)]
62use grants::MarkedStrength;
63pub use grants::{lock_strengths_conflict, LockAcquire, LockRequest, RowLockAcquisition};
64use grants::{rollback_grant, try_grant, GrantAttempt, LockGrant, LockTable};
65pub use identity::RowLockKey;
66use identity::{LockRelationIdentity, ManagerIdentity};
67pub use identity_registry::KeyReservationIdentity;
68pub use registry::{shared_backend_manager, shared_provider_manager};
69use relation::RelationLockGrant;
70pub use relation::{RelationLockMode, ScopedRelationLock};
71pub use sequence_positions::{
72    RecordedSequencePosition, SequencePosition, SequencePositionGuard, SequencePositionKey,
73};
74#[cfg(test)]
75use waits::deadlock_exists;
76use waits::{deadlock_detected, relation_deadlock_exists, CrossWaitGuard};
77
78/// Cross-process coordination attachment for durable file databases. A sidecar that cannot be opened surfaces its reason on the first lock attempt instead of silently degrading to process-local locking.
79enum CrossAttachment {
80    Active(Arc<FileLockCoordinator>),
81    Unavailable(String),
82}
83
84pub struct RowLockManager {
85    /// A retained baseline keeps the registered manager, and therefore its single native lock descriptor, alive until the reader finishes.
86    baseline_owner: Weak<Self>,
87    next_session: AtomicU64,
88    next_transaction_xid: AtomicU64,
89    /// The OID counter of a database whose storage does not reserve identifiers durably.
90    catalog_oids: crate::catalog::identity::CatalogOidCounter,
91    identities: identity_registry::IdentityRegistry,
92    next_acquisition: AtomicU64,
93    change_gate: RwLock<()>,
94    change_preparation: RwLock<()>,
95    state: Mutex<LockTable>,
96    temporary_roles: Mutex<HashMap<u64, std::collections::BTreeSet<u32>>>,
97    /// Held while one sequence's position is read and advanced; it also holds the positions of a database without a lock sidecar.
98    sequence_positions: Mutex<sequence_positions::LocalSequencePositions>,
99    wake: Condvar,
100    cross: Option<CrossAttachment>,
101}
102
103#[cfg(test)]
104mod tests;
105
106pub mod recheck;
107pub mod retry_cache;
108
109pub mod session;
110
111pub mod publication;