Skip to main content

uqa_execution/row_locks/
change_gate.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Scoped row-change snapshot and publication gates.
8
9use super::{
10    change_gate_claim, ByteClaim, CrossAttachment, Duration, Instant, RowChangeBaseline,
11    RowLockManager, RwLockReadGuard, RwLockWriteGuard, SQLError, CHANGE_GATE_SESSION,
12    CHANGE_GATE_WAIT_LIMIT, WAIT_SLICE,
13};
14
15pub struct RowChangeSnapshot<'manager> {
16    manager: &'manager RowLockManager,
17    cross_claim: Option<ByteClaim>,
18    _local: RwLockReadGuard<'manager, ()>,
19}
20
21pub struct RowChangePublication<'manager> {
22    manager: &'manager RowLockManager,
23    cross_claim: Option<ByteClaim>,
24    _local: RwLockWriteGuard<'manager, ()>,
25}
26
27impl RowChangeSnapshot<'_> {
28    pub fn baseline(&self) -> Result<RowChangeBaseline, SQLError> {
29        let epoch = self.manager.current_change_epoch();
30        let (cross_sequence, retention) = match self.manager.cross.as_ref() {
31            Some(CrossAttachment::Active(coordinator)) => {
32                let (sequence, lease) = coordinator
33                    .pin_change_sequence()
34                    .map_err(SQLError::Internal)?;
35                (sequence, Some(lease))
36            }
37            _ => (0, None),
38        };
39        Ok(RowChangeBaseline {
40            epoch,
41            cross_sequence,
42            _retention: retention,
43            _manager: self.manager.baseline_owner.upgrade(),
44        })
45    }
46}
47
48impl Drop for RowChangeSnapshot<'_> {
49    fn drop(&mut self) {
50        if let (Some(CrossAttachment::Active(coordinator)), Some(claim)) =
51            (self.manager.cross.as_ref(), self.cross_claim)
52        {
53            coordinator.release(CHANGE_GATE_SESSION, &[claim]);
54        }
55    }
56}
57
58impl Drop for RowChangePublication<'_> {
59    fn drop(&mut self) {
60        if let (Some(CrossAttachment::Active(coordinator)), Some(claim)) =
61            (self.manager.cross.as_ref(), self.cross_claim)
62        {
63            coordinator.release(CHANGE_GATE_SESSION, &[claim]);
64        }
65    }
66}
67
68impl RowLockManager {
69    fn acquire_change_gate_claim(
70        &self,
71        write: bool,
72        cancel: &uqa_core::CancellationToken,
73        deadline: Instant,
74    ) -> Result<Option<ByteClaim>, SQLError> {
75        let Some(CrossAttachment::Active(coordinator)) = self.cross.as_ref() else {
76            return Ok(None);
77        };
78        let claim = change_gate_claim(write);
79        loop {
80            cancel.check()?;
81            if let Ok(()) = coordinator
82                .try_claim(CHANGE_GATE_SESSION, &[claim])
83                .map_err(SQLError::Internal)?
84            {
85                return Ok(Some(claim));
86            }
87            if Instant::now() >= deadline {
88                return Err(change_gate_timeout());
89            }
90            std::thread::sleep(Duration::from_millis(1));
91        }
92    }
93
94    /// Hold the shared commit/snapshot gate while a storage snapshot is pinned and its row-change baseline is captured.
95    pub fn begin_change_snapshot(
96        &self,
97        cancel: &uqa_core::CancellationToken,
98    ) -> Result<RowChangeSnapshot<'_>, SQLError> {
99        let deadline = Instant::now() + CHANGE_GATE_WAIT_LIMIT;
100        let local = loop {
101            cancel.check()?;
102            let remaining = deadline.saturating_duration_since(Instant::now());
103            if remaining.is_zero() {
104                return Err(change_gate_timeout());
105            }
106            if let Some(local) = self.change_gate.try_read_for(remaining.min(WAIT_SLICE)) {
107                break local;
108            }
109        };
110        let cross_claim = self.acquire_change_gate_claim(false, cancel, deadline)?;
111        Ok(RowChangeSnapshot {
112            manager: self,
113            cross_claim,
114            _local: local,
115        })
116    }
117
118    /// Hold the exclusive commit/snapshot gate from immediately before the backend commit through publication of its row-change metadata.
119    pub fn begin_change_publication(
120        &self,
121        cancel: &uqa_core::CancellationToken,
122    ) -> Result<RowChangePublication<'_>, SQLError> {
123        let deadline = Instant::now() + CHANGE_GATE_WAIT_LIMIT;
124        let local = loop {
125            cancel.check()?;
126            let remaining = deadline.saturating_duration_since(Instant::now());
127            if remaining.is_zero() {
128                return Err(change_gate_timeout());
129            }
130            if let Some(local) = self.change_gate.try_write_for(remaining.min(WAIT_SLICE)) {
131                break local;
132            }
133        };
134        let cross_claim = self.acquire_change_gate_claim(true, cancel, deadline)?;
135        Ok(RowChangePublication {
136            manager: self,
137            cross_claim,
138            _local: local,
139        })
140    }
141}
142
143pub(super) fn change_gate_timeout() -> SQLError {
144    SQLError::Routine {
145        sqlstate: "55P03".into(),
146        message: format!(
147            "timed out after {} seconds waiting for cross-process row-change coordination",
148            CHANGE_GATE_WAIT_LIMIT.as_secs()
149        ),
150    }
151}