sqlive/snapshot_values.rs
1//! Values the host keeps in memory beside a database, which its SQL
2//! functions read as each transaction's snapshot saw them (ยง4).
3//!
4//! A statement reads the tables from its transaction's snapshot, which fixes
5//! the commits it sees. A function that read the host's memory as each call
6//! ran could join those commits to memory that a later commit's consequences
7//! had already changed, a moment that never existed. So each transaction
8//! takes every value once, as its snapshot is fixed, and every call in the
9//! transaction reads what it took. A read fixes its snapshot and takes the
10//! values while no commit of the database is underway ([`CommitOrder`]), so
11//! the values are those of a moment between its snapshot's last commit and
12//! the next. A write takes them as it begins: it holds the database's write
13//! lock, so no other commit can come between its snapshot and its values.
14
15use panic_as_error::locks::{lock_unpoisoned, read_unpoisoned, write_unpoisoned};
16use std::sync::{Arc, Mutex, RwLock, RwLockReadGuard, RwLockWriteGuard};
17
18/// One value the host keeps in memory, as one connection's transactions
19/// read it: the host's SQL functions hold it and read it with [`Self::get`].
20#[derive(Clone)]
21pub struct SnapshotValue<T> {
22 slot: Arc<SnapshotSlot<T>>,
23}
24
25struct SnapshotSlot<T> {
26 /// The value as it is now.
27 now: Box<dyn Fn() -> T + Send + Sync>,
28 /// The value as the open transaction's snapshot saw it, if a
29 /// transaction took it.
30 taken: Mutex<Option<T>>,
31}
32
33impl<T: Clone> SnapshotValue<T> {
34 /// The value as the open transaction's snapshot saw it. A statement
35 /// outside a transaction reads it as it is now.
36 pub fn get(&self) -> T {
37 let taken = lock_unpoisoned(&self.slot.taken).clone();
38 taken.unwrap_or_else(|| (self.slot.now)())
39 }
40}
41
42/// What a connection's transaction does with one of its values.
43trait TakeAtSnapshot: Send + Sync {
44 /// Keep the value as it is now, for the transaction to read.
45 fn take(&self);
46 /// The transaction ended: the next statement reads the value afresh.
47 fn forget(&self);
48}
49
50impl<T: Send> TakeAtSnapshot for SnapshotSlot<T> {
51 fn take(&self) {
52 let now = (self.now)();
53 *lock_unpoisoned(&self.taken) = Some(now);
54 }
55
56 fn forget(&self) {
57 *lock_unpoisoned(&self.taken) = None;
58 }
59}
60
61/// The values one connection's setup registered, which each of its
62/// transactions takes as its snapshot is fixed and forgets as it ends.
63pub(crate) struct SnapshotValues(Vec<Arc<dyn TakeAtSnapshot>>);
64
65impl SnapshotValues {
66 /// None registered yet.
67 pub(crate) fn new() -> Self {
68 Self(Vec::new())
69 }
70
71 /// A value, which `now` reads as it is at the moment, that each
72 /// transaction then takes and forgets.
73 pub(crate) fn value<T: Clone + Send + 'static>(
74 &mut self,
75 now: impl Fn() -> T + Send + Sync + 'static,
76 ) -> SnapshotValue<T> {
77 let slot = Arc::new(SnapshotSlot { now: Box::new(now), taken: Mutex::new(None) });
78 self.0.push(Arc::clone(&slot) as Arc<dyn TakeAtSnapshot>);
79 SnapshotValue { slot }
80 }
81
82 /// The transaction's snapshot is fixed: keep each value as it is now.
83 pub(crate) fn take(&self) {
84 for value in &self.0 {
85 value.take();
86 }
87 }
88
89 /// The transaction ended.
90 pub(crate) fn forget(&self) {
91 for value in &self.0 {
92 value.forget();
93 }
94 }
95}
96
97/// Orders one database's commits against its reads' snapshots: a commit
98/// runs while no read fixes its snapshot, and a read fixes its snapshot and
99/// takes its values while no commit runs. The database's connections share
100/// it; a connection opened alone has its own.
101pub(crate) struct CommitOrder(RwLock<()>);
102
103impl CommitOrder {
104 /// No commit running and no snapshot being fixed.
105 pub(crate) fn new() -> Self {
106 Self(RwLock::new(()))
107 }
108
109 /// Fix a read's snapshot and take its values while this is held.
110 pub(crate) fn reading(&self) -> RwLockReadGuard<'_, ()> {
111 read_unpoisoned(&self.0)
112 }
113
114 /// Commit while this is held.
115 pub(crate) fn committing(&self) -> RwLockWriteGuard<'_, ()> {
116 write_unpoisoned(&self.0)
117 }
118}
119
120#[cfg(test)]
121#[path = "snapshot_values_tests.rs"]
122mod tests;