Skip to main content

uqa_execution/row_locks/
sequence_positions.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! The exact position of each sequence between its durable records, shared by the sessions and processes of one database.
8
9use std::collections::HashMap;
10
11use parking_lot::MutexGuard;
12use uqa_sql::SQLError;
13
14use super::{cross_process::FileLockCoordinator, RowLockManager};
15
16/// One allocation generation of one sequence.
17#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
18pub struct SequencePositionKey {
19    pub object: [u8; 16],
20    pub definition: [u8; 16],
21}
22
23/// What a sequence has handed out, and the durable record that covers it.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub struct SequencePosition {
26    /// The value and the called flag of the durable record. Every value handed out is at or before this value.
27    pub logged: (i64, bool),
28    pub current: i64,
29    pub called: bool,
30    pub log_count: i64,
31}
32
33/// A recorded position and whether it was written in this run of the database. A position kept from an earlier run is exact only while the durable record still is the one it names.
34#[derive(Clone, Copy, Debug, PartialEq, Eq)]
35pub struct RecordedSequencePosition {
36    pub position: SequencePosition,
37    pub fresh: bool,
38}
39
40impl RecordedSequencePosition {
41    /// The position when it continues a durable record with this value and called flag.
42    #[must_use]
43    pub fn continuing(self, record: (i64, bool)) -> Option<SequencePosition> {
44        (self.fresh || self.position.logged == record).then_some(self.position)
45    }
46}
47
48/// What the position store holds for one sequence.
49pub(super) struct SequenceSlot {
50    pub recorded: Option<RecordedSequencePosition>,
51    /// Whether the store has room for the sequence's position.
52    pub recordable: bool,
53    /// Whether the store should drop the positions of sequences that no longer exist before it takes a new one.
54    pub crowded: bool,
55}
56
57/// The positions of a database without a position sidecar, which end with this process.
58#[derive(Default)]
59pub(super) struct LocalSequencePositions {
60    positions: HashMap<SequencePositionKey, SequencePosition>,
61}
62
63/// The position of one sequence, held so that no other session or process reads or changes it.
64pub struct SequencePositionGuard<'a> {
65    key: SequencePositionKey,
66    local: MutexGuard<'a, LocalSequencePositions>,
67    shared: Option<&'a FileLockCoordinator>,
68    slot: SequenceSlot,
69}
70
71impl SequencePositionGuard<'_> {
72    #[must_use]
73    pub fn recorded(&self) -> Option<RecordedSequencePosition> {
74        self.slot.recorded
75    }
76
77    /// Whether a position can be recorded. A sequence without room for one keeps its durable record exact instead.
78    #[must_use]
79    pub fn recordable(&self) -> bool {
80        self.slot.recordable
81    }
82
83    /// Whether the positions of sequences that no longer exist should be dropped before this sequence takes a slot.
84    #[must_use]
85    pub fn crowded(&self) -> bool {
86        self.slot.crowded
87    }
88
89    pub fn record(&mut self, position: SequencePosition) -> Result<(), SQLError> {
90        let recorded = match self.shared {
91            Some(coordinator) => coordinator
92                .record_sequence_position(&self.key, &position)
93                .map_err(SQLError::Internal)?,
94            None => {
95                self.local.positions.insert(self.key, position);
96                true
97            }
98        };
99        if !recorded {
100            return Err(SQLError::Internal(
101                "the sequence position store has no room for a position it offered".into(),
102            ));
103        }
104        self.slot.recorded = Some(RecordedSequencePosition {
105            position,
106            fresh: true,
107        });
108        Ok(())
109    }
110
111    /// Forget the position, after which the sequence continues from its durable record.
112    pub fn discard(&mut self) -> Result<(), SQLError> {
113        if self.slot.recorded.take().is_none() {
114            return Ok(());
115        }
116        match self.shared {
117            Some(coordinator) => coordinator
118                .remove_sequence_position(&self.key)
119                .map_err(SQLError::Internal),
120            None => {
121                self.local.positions.remove(&self.key);
122                Ok(())
123            }
124        }
125    }
126
127    /// Drop every position `keep` does not name. The caller names the allocation generations of the sequences that exist, read while it holds this guard.
128    pub fn retain(&mut self, keep: &dyn Fn(&SequencePositionKey) -> bool) -> Result<(), SQLError> {
129        match self.shared {
130            Some(coordinator) => {
131                coordinator
132                    .retain_sequence_positions(keep)
133                    .map_err(SQLError::Internal)?;
134                self.slot = coordinator
135                    .read_sequence_slot(&self.key)
136                    .map_err(SQLError::Internal)?;
137            }
138            None => self.local.positions.retain(|key, _| keep(key)),
139        }
140        // One pass is all the store can free, so a store that is still full is no longer asked again.
141        self.slot.crowded = false;
142        Ok(())
143    }
144}
145
146impl Drop for SequencePositionGuard<'_> {
147    fn drop(&mut self) {
148        if let Some(coordinator) = self.shared {
149            coordinator.unlock_sequence_positions();
150        }
151    }
152}
153
154impl RowLockManager {
155    fn sequence_position_store(&self) -> Result<Option<&FileLockCoordinator>, SQLError> {
156        Ok(self
157            .coordinator()?
158            .filter(|coordinator| coordinator.shares_sequence_positions()))
159    }
160
161    /// Hold the position of one sequence until the guard is dropped. Sessions of this process wait for each other here, and other processes wait at the sidecar.
162    pub fn lock_sequence_position(
163        &self,
164        key: SequencePositionKey,
165    ) -> Result<SequencePositionGuard<'_>, SQLError> {
166        let shared = self.sequence_position_store()?;
167        let local = self.sequence_positions.lock();
168        let slot = match shared {
169            Some(coordinator) => {
170                coordinator
171                    .lock_sequence_positions()
172                    .map_err(SQLError::Internal)?;
173                match coordinator.read_sequence_slot(&key) {
174                    Ok(slot) => slot,
175                    Err(error) => {
176                        coordinator.unlock_sequence_positions();
177                        return Err(SQLError::Internal(error));
178                    }
179                }
180            }
181            None => SequenceSlot {
182                recorded: local
183                    .positions
184                    .get(&key)
185                    .map(|position| RecordedSequencePosition {
186                        position: *position,
187                        fresh: true,
188                    }),
189                recordable: true,
190                crowded: false,
191            },
192        };
193        Ok(SequencePositionGuard {
194            key,
195            local,
196            shared,
197            slot,
198        })
199    }
200
201    /// The recorded position of one sequence.
202    pub fn sequence_position(
203        &self,
204        key: SequencePositionKey,
205    ) -> Result<Option<RecordedSequencePosition>, SQLError> {
206        Ok(self.lock_sequence_position(key)?.recorded())
207    }
208
209    /// The recorded position of every sequence.
210    pub fn sequence_positions(
211        &self,
212    ) -> Result<HashMap<SequencePositionKey, RecordedSequencePosition>, SQLError> {
213        let shared = self.sequence_position_store()?;
214        let local = self.sequence_positions.lock();
215        let Some(coordinator) = shared else {
216            return Ok(local
217                .positions
218                .iter()
219                .map(|(key, position)| {
220                    (
221                        *key,
222                        RecordedSequencePosition {
223                            position: *position,
224                            fresh: true,
225                        },
226                    )
227                })
228                .collect());
229        };
230        coordinator
231            .lock_sequence_positions()
232            .map_err(SQLError::Internal)?;
233        let positions = coordinator.read_sequence_positions();
234        coordinator.unlock_sequence_positions();
235        Ok(positions.map_err(SQLError::Internal)?.into_iter().collect())
236    }
237}
238
239#[cfg(test)]
240mod tests;