Skip to main content

uqa_execution/row_locks/
relation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Relation-lock grants and acquisition lifecycle.
8
9use super::cross_process::{
10    relation_wait_claim, FileLockCoordinator, RelationClaimWait, RelationIdentityLease,
11};
12use super::{
13    deadlock_detected, relation_deadlock_exists, CrossAttachment, CrossWaitGuard, LockTable,
14    RowLockManager, SQLError, WAIT_SLICE,
15};
16
17#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
18#[repr(u8)]
19pub enum RelationLockMode {
20    AccessShare,
21    RowShare,
22    RowExclusive,
23    ShareUpdateExclusive,
24    Share,
25    ShareRowExclusive,
26    Exclusive,
27    AccessExclusive,
28}
29
30impl RelationLockMode {
31    #[cfg(any(test, windows, all(unix, not(target_os = "emscripten"))))]
32    pub(super) const ALL: [Self; 8] = [
33        Self::AccessShare,
34        Self::RowShare,
35        Self::RowExclusive,
36        Self::ShareUpdateExclusive,
37        Self::Share,
38        Self::ShareRowExclusive,
39        Self::Exclusive,
40        Self::AccessExclusive,
41    ];
42
43    /// The `PostgreSQL` table-lock conflict sets are not an ordering of strengths.
44    pub fn conflicts_with(self, other: Self) -> bool {
45        const CONFLICTS: [u8; 8] = [0x80, 0xc0, 0xf0, 0xf8, 0xec, 0xfc, 0xfe, 0xff];
46        CONFLICTS[self as usize] & (1 << other as u8) != 0
47    }
48}
49
50/// A temporary acquisition above a caller-owned mark. The session must not acquire unrelated locks until this guard is dropped.
51pub struct ScopedRelationLock<'a> {
52    manager: &'a RowLockManager,
53    session_id: u64,
54    table: u64,
55    mode: RelationLockMode,
56    keep_mark: u32,
57    retained: bool,
58}
59
60impl ScopedRelationLock<'_> {
61    /// Keep the successful binding acquisition in the caller's transaction/savepoint after catalog revalidation. No unrelated locks may be acquired while the temporary guard is alive.
62    pub fn retain(self) {
63        let mark = self.keep_mark;
64        self.retain_at(mark);
65    }
66
67    /// Retain this mode at an enclosing transaction mark without extending any other mode already held on the relation.
68    pub fn retain_at(mut self, mark: u32) {
69        let mark = mark.min(self.keep_mark);
70        let mut state = self.manager.state.lock();
71        if let Some(grant) = state.relations.get_mut(&self.table).and_then(|grants| {
72            grants
73                .iter_mut()
74                .find(|grant| grant.session_id == self.session_id)
75        }) {
76            for acquisition in &mut grant.acquisitions {
77                if acquisition.mode == self.mode {
78                    acquisition.mark = acquisition.mark.min(mark);
79                }
80            }
81        }
82        self.retained = true;
83    }
84}
85
86impl Drop for ScopedRelationLock<'_> {
87    fn drop(&mut self) {
88        if !self.retained {
89            self.manager
90                .release_mark_above(self.session_id, self.keep_mark);
91        }
92    }
93}
94
95#[derive(Clone, Copy, Debug)]
96pub(super) struct MarkedRelationMode {
97    pub(super) mode: RelationLockMode,
98    pub(super) mark: u32,
99}
100
101#[derive(Clone, Debug)]
102pub(super) struct RelationLockGrant {
103    pub(super) session_id: u64,
104    pub(super) acquisitions: Vec<MarkedRelationMode>,
105}
106
107struct RelationRequest<'a> {
108    session_id: u64,
109    table: u64,
110    mode: RelationLockMode,
111    mark: u32,
112    cancel: &'a uqa_core::CancellationToken,
113}
114
115impl RelationLockGrant {
116    pub(super) fn conflicting_mode(&self, requested: RelationLockMode) -> Option<RelationLockMode> {
117        self.acquisitions
118            .iter()
119            .map(|acquisition| acquisition.mode)
120            .find(|mode| mode.conflicts_with(requested))
121    }
122}
123
124impl RowLockManager {
125    pub fn acquire_scoped_relation(
126        &self,
127        session_id: u64,
128        table: u64,
129        mode: RelationLockMode,
130        marks: (u32, u32),
131        cancel: &uqa_core::CancellationToken,
132    ) -> Result<ScopedRelationLock<'_>, SQLError> {
133        let (keep_mark, mark) = marks;
134        if mark <= keep_mark {
135            return Err(SQLError::Internal(
136                "temporary relation lock requires a newer mark".into(),
137            ));
138        }
139        self.acquire_relation(session_id, table, mode, mark, cancel)?;
140        Ok(ScopedRelationLock {
141            manager: self,
142            session_id,
143            table,
144            mode,
145            keep_mark,
146            retained: false,
147        })
148    }
149
150    pub fn try_acquire_scoped_relation(
151        &self,
152        session_id: u64,
153        table: u64,
154        mode: RelationLockMode,
155        marks: (u32, u32),
156        cancel: &uqa_core::CancellationToken,
157    ) -> Result<Option<ScopedRelationLock<'_>>, SQLError> {
158        let (keep_mark, mark) = marks;
159        if mark <= keep_mark {
160            return Err(SQLError::Internal(
161                "temporary relation lock requires a newer mark".into(),
162            ));
163        }
164        Ok(self
165            .try_acquire_relation(session_id, table, mode, mark, cancel)?
166            .then(|| ScopedRelationLock {
167                manager: self,
168                session_id,
169                table,
170                mode,
171                keep_mark,
172                retained: false,
173            }))
174    }
175
176    pub(super) fn release_relation_claims(
177        &self,
178        session_id: u64,
179        table: u64,
180        mode: RelationLockMode,
181    ) {
182        if let Some(CrossAttachment::Active(coordinator)) = self.cross.as_ref() {
183            let relation = self.relation_bytes(table);
184            coordinator.release_relation(session_id, &relation, mode);
185        }
186    }
187
188    pub fn acquire_relation(
189        &self,
190        session_id: u64,
191        table: u64,
192        mode: RelationLockMode,
193        mark: u32,
194        cancel: &uqa_core::CancellationToken,
195    ) -> Result<(), SQLError> {
196        self.acquire_relation_inner(
197            RelationRequest {
198                session_id,
199                table,
200                mode,
201                mark,
202                cancel,
203            },
204            true,
205        )
206        .map(|_| ())
207    }
208
209    /// Acquire a relation lock without waiting for conflicting holders. Short internal admission serialization is independent of the SQL wait policy; a failed attempt preserves this session's earlier modes and savepoint marks.
210    pub fn try_acquire_relation(
211        &self,
212        session_id: u64,
213        table: u64,
214        mode: RelationLockMode,
215        mark: u32,
216        cancel: &uqa_core::CancellationToken,
217    ) -> Result<bool, SQLError> {
218        self.acquire_relation_inner(
219            RelationRequest {
220                session_id,
221                table,
222                mode,
223                mark,
224                cancel,
225            },
226            false,
227        )
228    }
229
230    fn acquire_relation_inner(
231        &self,
232        request: RelationRequest<'_>,
233        wait: bool,
234    ) -> Result<bool, SQLError> {
235        let coordinator = self.coordinator()?;
236        let relation = self.relation_bytes(request.table);
237        let mut identity = coordinator
238            .map(|coordinator| coordinator.pin_relation(&relation, request.cancel))
239            .transpose()?;
240        self.wait_for_relation(request, wait, coordinator, identity.as_mut())
241    }
242
243    fn wait_for_relation(
244        &self,
245        request: RelationRequest<'_>,
246        wait: bool,
247        coordinator: Option<&FileLockCoordinator>,
248        mut identity: Option<&mut RelationIdentityLease<'_>>,
249    ) -> Result<bool, SQLError> {
250        let RelationRequest {
251            session_id,
252            table,
253            mode,
254            mark,
255            cancel,
256        } = request;
257        let slot = identity.as_deref().map(RelationIdentityLease::slot);
258        let wanted = slot.map(|slot| relation_wait_claim(slot, mode));
259        let cross_wait = CrossWaitGuard::new(self, coordinator, session_id);
260        let mut wait_started = None;
261        loop {
262            let mut state = self.state.lock();
263            let checked = wait_started
264                .map_or_else(|| cancel.check(), |started| cancel.check_lock_wait(started));
265            if let Err(error) = checked {
266                state.waiting_relations.remove(&session_id);
267                drop(state);
268                self.wake.notify_all();
269                return Err(error.into());
270            }
271            let contended_claim =
272                match try_grant_relation(&mut state, session_id, table, mode, mark) {
273                    RelationGrantAttempt::Conflict => wanted,
274                    RelationGrantAttempt::AlreadyHeld => {
275                        state.waiting_relations.remove(&session_id);
276                        return Ok(true);
277                    }
278                    RelationGrantAttempt::Granted => {
279                        let foreign_conflict = if let Some(coordinator) = coordinator {
280                            match coordinator.try_slot_claim(
281                                session_id,
282                                slot.expect("durable relation identity"),
283                                mode,
284                            ) {
285                                Ok(Ok(())) => None,
286                                Ok(Err(RelationClaimWait::Conflict(_))) => wanted,
287                                Ok(Err(RelationClaimWait::AdmissionBusy)) => {
288                                    rollback_relation_grant(&mut state, session_id, table);
289                                    state.waiting_relations.remove(&session_id);
290                                    cross_wait.clear(&mut state);
291                                    self.wake.wait_for(&mut state, WAIT_SLICE);
292                                    continue;
293                                }
294                                Err(error) => {
295                                    rollback_relation_grant(&mut state, session_id, table);
296                                    drop(state);
297                                    self.wake.notify_all();
298                                    return Err(SQLError::Internal(error));
299                                }
300                            }
301                        } else {
302                            None
303                        };
304                        match foreign_conflict {
305                            None => {
306                                if let Some(identity) = identity.as_mut() {
307                                    identity.retain();
308                                }
309                                state.waiting_relations.remove(&session_id);
310                                return Ok(true);
311                            }
312                            Some(contended) => {
313                                rollback_relation_grant(&mut state, session_id, table);
314                                Some(contended)
315                            }
316                        }
317                    }
318                };
319            if !wait {
320                state.waiting_relations.remove(&session_id);
321                drop(state);
322                self.wake.notify_all();
323                return Ok(false);
324            }
325            if relation_deadlock_exists(&state, session_id, table, mode) {
326                state.waiting_relations.remove(&session_id);
327                drop(state);
328                self.wake.notify_all();
329                return Err(deadlock_detected());
330            }
331            if let (Some(coordinator), Some(contended)) = (coordinator, contended_claim) {
332                cross_wait.register(&mut state, contended);
333                if Self::cross_wait_cycle(&state, coordinator, session_id, contended) {
334                    state.waiting_relations.remove(&session_id);
335                    state.advertised_waits.remove(&session_id);
336                    drop(state);
337                    self.wake.notify_all();
338                    return Err(deadlock_detected());
339                }
340            }
341            state
342                .waiting_relations
343                .entry(session_id)
344                .or_default()
345                .insert(table, mode);
346            let started = *wait_started.get_or_insert_with(std::time::Instant::now);
347            self.wake
348                .wait_for(&mut state, cancel.lock_wait_slice(started, WAIT_SLICE));
349        }
350    }
351}
352
353/// Undo one just-granted relation acquisition whose cross-process claim failed: the newest acquisition of this session on the table.
354fn rollback_relation_grant(state: &mut LockTable, session_id: u64, table: u64) {
355    if let Some(grants) = state.relations.get_mut(&table) {
356        grants.retain_mut(|grant| {
357            if grant.session_id == session_id {
358                grant.acquisitions.pop();
359            }
360            !grant.acquisitions.is_empty()
361        });
362        if grants.is_empty() {
363            state.relations.remove(&table);
364        }
365    }
366}
367
368enum RelationGrantAttempt {
369    Conflict,
370    AlreadyHeld,
371    Granted,
372}
373
374fn try_grant_relation(
375    state: &mut LockTable,
376    session_id: u64,
377    table: u64,
378    mode: RelationLockMode,
379    mark: u32,
380) -> RelationGrantAttempt {
381    let grants = state.relations.entry(table).or_default();
382    if grants
383        .iter()
384        .any(|grant| grant.session_id != session_id && grant.conflicting_mode(mode).is_some())
385    {
386        return RelationGrantAttempt::Conflict;
387    }
388    if let Some(existing) = grants
389        .iter_mut()
390        .find(|grant| grant.session_id == session_id)
391    {
392        if existing
393            .acquisitions
394            .iter()
395            .any(|acquisition| acquisition.mode == mode)
396        {
397            return RelationGrantAttempt::AlreadyHeld;
398        }
399        existing
400            .acquisitions
401            .push(MarkedRelationMode { mode, mark });
402        return RelationGrantAttempt::Granted;
403    }
404    grants.push(RelationLockGrant {
405        session_id,
406        acquisitions: vec![MarkedRelationMode { mode, mark }],
407    });
408    RelationGrantAttempt::Granted
409}
410
411#[cfg(test)]
412mod tests;