Skip to main content

sqlive/
handle.rs

1//! A handle: the failure state and the subscriptions that several databases
2//! share. A subscription keeps the commits made during a run of its read
3//! until the run ends and its reads are known; an idle subscription keeps
4//! only whether something changed.
5
6use crate::commit_scope::CommitScope;
7use crate::database_changes::DatabaseChanges;
8use crate::kept_counts::KeptCounts;
9use crate::read_index::{ReadIndex, SubscriptionId};
10use crate::read_set::{affected_by, past_row_limit};
11use crate::{affected, Answers, EngineFailure, Error, Judging, Lookups, ReadSet, RowChange};
12use panic_as_error::locks::lock_unpoisoned;
13use panic_as_error::{Bug, BugSinkRef};
14use std::{
15    any::Any,
16    cell::RefCell,
17    collections::{BTreeMap, BTreeSet, HashMap, HashSet},
18    marker::PhantomData,
19    sync::{Arc, Mutex},
20};
21use tokio::sync::watch;
22
23/// Tables whose changes no write records for live queries, lowercase.
24#[derive(Debug)]
25pub struct UnrecordedTables(BTreeSet<String>);
26
27impl UnrecordedTables {
28    /// The tables `tables` names, in any case.
29    pub fn new<'a>(tables: impl IntoIterator<Item = &'a str>) -> Self {
30        Self(tables.into_iter().map(str::to_ascii_lowercase).collect())
31    }
32
33    /// Whether a write records its changes to `table` (ASCII case-insensitive).
34    pub fn recorded(&self, table: &str) -> bool {
35        !self.0.contains(&table.to_ascii_lowercase())
36    }
37}
38
39/// The host's failure that a handle failed with, or a bug. A subscription
40/// holds it too, and its type names no host failure type, so `Failure` holds
41/// the host's failure as `Any`: the handle, whose type names the failure
42/// type, takes it back out ([`Handle::error`]).
43#[derive(Clone)]
44pub(crate) enum Failure {
45    /// A failure that the host reported, or an engine failure that ended the
46    /// handle, as the host's failure type holds it.
47    Host(Arc<dyn Any + Send + Sync>),
48    /// A bug, a panic or a fault a drop found, may have left the databases'
49    /// state wrong (E15). It reached its one reporter as it happened, so
50    /// the calls after it repeat it as `Error::HandleFailed`.
51    Bug(Bug),
52}
53
54/// Why a live query's run or a change watch fails without running: the
55/// handle failed or closed, or a run panicked.
56pub(crate) enum Stop {
57    /// The handle failed with this.
58    Failed(Failure),
59    /// The handle closed.
60    Closed,
61    /// A run panicked with this bug.
62    Bug(Bug),
63}
64
65/// How a live query's or a change watch's error type `E` holds the error a
66/// [`Stop`] stands for.
67pub(crate) type Failed<E> = Arc<dyn Fn(Stop) -> E + Send + Sync>;
68
69/// What a subscription has seen of its handle: whether a commit changed what
70/// it waits on, and whether the handle closed or failed.
71#[derive(Clone)]
72pub struct CommitState {
73    /// Whether a commit changed what the subscription waits on since it
74    /// last began a run.
75    pub changed: bool,
76    closed: bool,
77    failure: Option<Failure>,
78}
79
80impl CommitState {
81    /// Whether the handle has closed.
82    pub fn closed(&self) -> bool {
83        self.closed
84    }
85
86    /// Why the subscription stopped, if it did: the handle's failure, or its
87    /// closing.
88    pub(crate) fn stopped_by(&self) -> Option<Stop> {
89        match &self.failure {
90            Some(failure) => Some(Stop::Failed(failure.clone())),
91            None => self.closed.then_some(Stop::Closed),
92        }
93    }
94
95    /// Whether the handle failed or closed.
96    pub fn stopped(&self) -> bool {
97        self.closed || self.failure.is_some()
98    }
99}
100
101enum Tracking {
102    /// A run whose reads aren't known until it ends: the commits made
103    /// since it began, kept to judge then, and the reads of the run before
104    /// it, whose scopes name the values those commits record (§4).
105    Reading {
106        commits: Vec<Arc<Vec<RowChange>>>,
107        previous: Arc<ReadSet>,
108    },
109    Waiting(Arc<ReadSet>),
110}
111
112impl Tracking {
113    /// The reads whose values a write keeps: those waited on, or, while a
114    /// run reads, its previous run's, which a run with the same statements
115    /// reads and tests again.
116    fn kept(&self) -> &Arc<ReadSet> {
117        match self {
118            Self::Reading { previous: reads, .. } | Self::Waiting(reads) => reads,
119        }
120    }
121}
122
123/// A subscription's tracking, and how many times it began or finished a
124/// run: a write judged against one count's reads can't stand for another's.
125struct Tracked {
126    tracking: Tracking,
127    epoch: u64,
128}
129
130impl Tracked {
131    /// Track commits as `tracking` from now on, at the next epoch.
132    fn set(&mut self, tracking: Tracking) {
133        self.tracking = tracking;
134        self.epoch += 1;
135    }
136}
137
138/// What a subscription shares with its handle: its tracking, behind its own
139/// lock, and what it has seen of the handle.
140struct Entry {
141    tracked: Mutex<Tracked>,
142    state: watch::Sender<CommitState>,
143    /// Commits made within this scope are not observed.
144    outside: Option<CommitScope>,
145}
146
147impl Entry {
148    /// Whether commits made within `scope` don't reach this subscription.
149    fn outside_of(&self, scope: Option<CommitScope>) -> bool {
150        scope.is_some() && scope == self.outside
151    }
152
153    /// Whether a commit has marked this subscription to run again.
154    fn marked(&self) -> bool {
155        self.state.borrow().changed
156    }
157
158    /// Tell this subscription of a commit of `changes`: a reading one keeps
159    /// them; a waiting one not marked already is marked to run again when
160    /// they affect its reads. A waiting one still at the epoch the handle filed it at,
161    /// `filed`, takes the write's verdict at that epoch from `verdicts`, or
162    /// judges the changes at the positions the index found it for; any
163    /// other judges every change. Either judges counting every join's value
164    /// as matched: the write's transaction has ended, so no lookup can read
165    /// it.
166    fn tell(
167        &self,
168        id: SubscriptionId,
169        changes: &Arc<Vec<RowChange>>,
170        crowded: &HashSet<&str>,
171        filed: Option<(u64, &[usize])>,
172        verdicts: &HashMap<SubscriptionId, (u64, bool)>,
173    ) {
174        let mut tracked = lock_unpoisoned(&self.tracked);
175        let epoch = tracked.epoch;
176        let reads = match &mut tracked.tracking {
177            Tracking::Reading { commits, .. } => {
178                commits.push(Arc::clone(changes));
179                return;
180            }
181            Tracking::Waiting(_) if self.marked() => return,
182            Tracking::Waiting(reads) => reads,
183        };
184        let mut matched = |_: Judging<'_>| Ok(true);
185        let found = match filed {
186            Some((at, positions)) if at == epoch => match verdicts.get(&id) {
187                Some(&(judged, found)) if judged == epoch => found,
188                _ => affected_by(
189                    reads,
190                    positions.iter().map(|&position| &changes[position]),
191                    crowded,
192                    &mut Answers::default(),
193                    &mut matched,
194                )
195                .expect("judging without lookups can't fail"),
196            },
197            _ => affected_by(reads, changes.iter(), crowded, &mut Answers::default(), &mut matched)
198                .expect("judging without lookups can't fail"),
199        };
200        if found {
201            self.state.send_modify(|state| state.changed = true);
202        }
203    }
204}
205
206/// The subscriptions whose tracking changed since their handle last filed
207/// them, which it files again before it next reads its index, and those
208/// whose last clone dropped, which it forgets.
209#[derive(Default)]
210struct Refiling {
211    changed: BTreeSet<SubscriptionId>,
212    dropped: BTreeSet<SubscriptionId>,
213}
214
215/// What a subscription's clones share: its number in its handle, its entry,
216/// and where it tells the handle to file it again.
217struct SubscriptionState {
218    id: SubscriptionId,
219    entry: Arc<Entry>,
220    refiling: Arc<Mutex<Refiling>>,
221    /// The tables whose changes no write records, which a run may not read.
222    unrecorded: Arc<UnrecordedTables>,
223}
224
225impl Drop for SubscriptionState {
226    fn drop(&mut self) {
227        lock_unpoisoned(&self.refiling).dropped.insert(self.id);
228    }
229}
230
231/// One waiter on a handle's commits: a live query's, a change watch's, or the
232/// host's own.
233#[derive(Clone)]
234pub struct CommitSubscription {
235    shared: Arc<SubscriptionState>,
236    receiver: watch::Receiver<CommitState>,
237}
238
239impl CommitSubscription {
240    /// A new subscription to the handle whose state is `handle`, which
241    /// commits made within `outside` don't reach, and whose runs may not
242    /// read the tables `unrecorded` names (`Handle::subscribe_outside`).
243    fn new(
244        handle: &Mutex<ObserverState>,
245        outside: Option<CommitScope>,
246        unrecorded: Arc<UnrecordedTables>,
247    ) -> Self {
248        let (shared, receiver) = with_locked(handle, |state| {
249            let failure = if state.closed { None } else { state.failure.clone() };
250            let (sender, receiver) =
251                watch::channel(CommitState { changed: false, closed: state.closed, failure });
252            let entry = Arc::new(Entry {
253                tracked: Mutex::new(Tracked {
254                    tracking: Tracking::Waiting(Arc::new(Vec::new())),
255                    epoch: 0,
256                }),
257                state: sender,
258                outside,
259            });
260            let id = state.next;
261            state.next += 1;
262            state.entries.insert(id, Arc::clone(&entry));
263            let shared =
264                SubscriptionState { id, entry, refiling: Arc::clone(&state.refiling), unrecorded };
265            (shared, receiver)
266        });
267        Self { shared: Arc::new(shared), receiver }
268    }
269
270    /// Change this subscription's tracking with `change`, and have its
271    /// handle file it again before the handle next reads its index.
272    fn track<R>(&self, change: impl FnOnce(&mut Tracked) -> R) -> R {
273        let mut tracked = lock_unpoisoned(&self.shared.entry.tracked);
274        let result = change(&mut tracked);
275        lock_unpoisoned(&self.shared.refiling).changed.insert(self.shared.id);
276        result
277    }
278
279    /// The state now, without marking it seen.
280    pub fn state(&self) -> CommitState {
281        self.receiver.borrow().clone()
282    }
283
284    /// Returns the current state and marks it as seen, so `changed` waits for a
285    /// later state.
286    pub fn observe(&mut self) -> CommitState {
287        self.receiver.borrow_and_update().clone()
288    }
289
290    /// Wait for a state this subscription hasn't seen.
291    pub async fn changed(&mut self) {
292        self.receiver.changed().await.expect("subscription owns its sender");
293    }
294
295    /// Start keeping the commits a run meets, until it finishes. Meanwhile
296    /// a write records the values the scopes this subscription went by
297    /// until now test.
298    pub fn begin(&self) {
299        self.track(|tracked| {
300            let previous = Arc::clone(tracked.tracking.kept());
301            tracked.set(Tracking::Reading { commits: Vec::new(), previous });
302        });
303        self.shared.entry.state.send_modify(|state| state.changed = false);
304    }
305
306    /// Wait on nothing, whatever this subscription was doing: its query
307    /// ended on a bug, so what its run read is unknown (E15).
308    pub fn stop(&self) {
309        self.track(|tracked| {
310            tracked.set(Tracking::Waiting(Arc::new(Vec::new())));
311        });
312    }
313
314    /// Wait on `reads`, which join no table: no commit needs a lookup.
315    pub fn finish(&self, reads: ReadSet) {
316        self.finish_judging(reads, &mut |_| unreachable!("only a live query's run reads a join"))
317            .expect("judging without lookups can't fail");
318    }
319
320    /// Wait on `reads`, a run's. The commits made while it ran are judged
321    /// against them, with `lookups` reading the run's own snapshot: a value
322    /// matches a join there exactly when the run's partners held it. A
323    /// lookup that fails marks the query to run again, and its error is
324    /// the run's.
325    pub fn finish_judging(
326        &self,
327        reads: ReadSet,
328        lookups: &mut Lookups<'_>,
329    ) -> rusqlite::Result<()> {
330        if let Some(read) = reads.iter().find(|read| !self.shared.unrecorded.recorded(&read.table))
331        {
332            panic!("a live query read {}, whose changes no write records", read.table);
333        }
334        let reads = Arc::new(reads);
335        let mut changed = false;
336        let mut failure = None;
337        let mut answers = Answers::default();
338        loop {
339            // Judge without the lock, so writes go on committing; those that
340            // commit meanwhile are judged on the next pass.
341            let commits = self.track(|tracked| {
342                let Tracking::Reading { commits, .. } = &mut tracked.tracking else {
343                    panic!("read observation was not started")
344                };
345                if !commits.is_empty() {
346                    return Some(std::mem::take(commits));
347                }
348                tracked.set(Tracking::Waiting(Arc::clone(&reads)));
349                self.shared.entry.state.send_modify(|state| state.changed = changed);
350                None
351            });
352            let Some(commits) = commits else {
353                break;
354            };
355            for changes in commits {
356                if changed {
357                    break;
358                }
359                match affected(&reads, &changes, &mut answers, lookups) {
360                    Ok(found) => changed = found,
361                    Err(error) => {
362                        changed = true;
363                        failure = Some(error);
364                    }
365                }
366            }
367        }
368        failure.map_or(Ok(()), Err)
369    }
370}
371
372/// A write's changes, and how each live query that waited on known reads
373/// and that the changes could affect judged them in the write's
374/// transaction, before it committed.
375pub struct Judged {
376    changes: Arc<Vec<RowChange>>,
377    /// Each subscription judged, by its number, with its epoch then and
378    /// whether the changes affect it. The changes affect no other
379    /// subscription that waited on its reads then: the index found it for
380    /// none of them.
381    verdicts: HashMap<SubscriptionId, (u64, bool)>,
382}
383
384impl Judged {
385    /// Changes no live query judged, as those that name no row: each
386    /// waiting query judges them as they reach it, without lookups.
387    fn unjudged(changes: Vec<RowChange>) -> Self {
388        Self { changes: Arc::new(changes), verdicts: HashMap::new() }
389    }
390
391    /// How many live queries judged the changes.
392    #[cfg(any(test, feature = "test-utils"))]
393    pub(crate) fn judgments(&self) -> usize {
394        self.verdicts.len()
395    }
396}
397
398/// Every commit made outside one attempt since it began, kept until the
399/// attempt names the rows its wait depends on.
400pub struct AttemptCommits {
401    commits: CommitSubscription,
402}
403
404struct ObserverState {
405    /// Every subscription's entry, by its number.
406    entries: HashMap<SubscriptionId, Arc<Entry>>,
407    /// The number the next subscription takes.
408    next: SubscriptionId,
409    /// The subscriptions by how they tracked commits when the handle last
410    /// filed them.
411    filed: Filed,
412    /// The subscriptions to file again or forget, which they tell.
413    refiling: Arc<Mutex<Refiling>>,
414    closed: bool,
415    failure: Option<Failure>,
416    /// How many entries' tracking the handle has read to file them again.
417    #[cfg(test)]
418    entries_read: usize,
419}
420
421thread_local! {
422    /// The handle's call this thread runs, if any, and the bug its own work
423    /// failed that handle with (E15).
424    // Clippy asks for a `const` initializer this already has where the
425    // target has no native thread locals, as Android: std builds those
426    // from a function, which the lint reads as the initializer.
427    #[cfg_attr(target_os = "android", allow(clippy::missing_const_for_thread_local))]
428    static CALL: RefCell<Option<Call>> = const { RefCell::new(None) };
429}
430
431/// One of a handle's calls running on this thread.
432struct Call {
433    /// The handle the call is on, by its state's address.
434    handle: usize,
435    /// The first bug the call's work failed the handle with, which the call
436    /// returns as its own.
437    bug: Option<Bug>,
438}
439
440/// The bug of `what`, a lock's state, which a panic while it was held may
441/// have left half-changed.
442#[track_caller]
443fn half_changed(what: &'static str) -> Bug {
444    Bug::new(what, "a panic while it was locked may have left it half-changed")
445}
446
447/// How a handle filed a subscription: waiting on reads at an epoch, or
448/// reading, with the reads of its run before.
449enum Filing {
450    Waiting { epoch: u64, reads: Arc<ReadSet> },
451    Reading { previous: Arc<ReadSet> },
452}
453
454impl Filing {
455    /// The reads whose values a write keeps (`Tracking::kept`).
456    fn kept(&self) -> &ReadSet {
457        match self {
458            Self::Waiting { reads, .. } | Self::Reading { previous: reads } => reads,
459        }
460    }
461}
462
463/// A handle's subscriptions by how each tracked commits when the handle last
464/// filed it: those waiting on known reads by their reads, and those whose
465/// runs were reading; and the columns of each table they read that a write
466/// keeps.
467#[derive(Default)]
468struct Filed {
469    filings: HashMap<SubscriptionId, Filing>,
470    waiting: ReadIndex,
471    reading: BTreeSet<SubscriptionId>,
472    kept: KeptCounts,
473}
474
475impl Filed {
476    /// File subscription `id`, which tracks commits as `tracked` says.
477    fn file(&mut self, id: SubscriptionId, tracked: &Tracked) {
478        self.forget(id);
479        let filing = match &tracked.tracking {
480            Tracking::Waiting(reads) => {
481                self.waiting.insert(id, reads);
482                Filing::Waiting { epoch: tracked.epoch, reads: Arc::clone(reads) }
483            }
484            Tracking::Reading { previous, .. } => {
485                self.reading.insert(id);
486                Filing::Reading { previous: Arc::clone(previous) }
487            }
488        };
489        self.kept.add(filing.kept());
490        self.filings.insert(id, filing);
491    }
492
493    /// Take subscription `id` out.
494    fn forget(&mut self, id: SubscriptionId) {
495        let Some(filing) = self.filings.remove(&id) else {
496            return;
497        };
498        self.kept.remove(filing.kept());
499        match filing {
500            Filing::Waiting { reads, .. } => self.waiting.remove(id, &reads),
501            Filing::Reading { .. } => {
502                self.reading.remove(&id);
503            }
504        }
505    }
506}
507
508/// Run `change` on a handle's `state`, once it has filed again the
509/// subscriptions whose tracking changed. A panic while it was held may have
510/// left some subscription untold of a commit, so the handle fails with that
511/// bug, which tells every subscription; the failure then stands in for the
512/// poisoning (E15).
513fn with_locked<R>(state: &Mutex<ObserverState>, change: impl FnOnce(&mut ObserverState) -> R) -> R {
514    let mut held = state.lock().unwrap_or_else(|poisoned| {
515        let mut held = poisoned.into_inner();
516        held.fail(Failure::Bug(half_changed("the handle's live queries")));
517        state.clear_poison();
518        held
519    });
520    held.refile();
521    change(&mut held)
522}
523
524impl ObserverState {
525    /// Fail every later call and subscription. The handle keeps the first
526    /// failure and ignores later ones.
527    fn fail(&mut self, failure: Failure) {
528        let error = self.failure.get_or_insert(failure).clone();
529        for entry in self.entries.values() {
530            entry.state.send_modify(|state| state.failure = Some(error.clone()));
531        }
532    }
533
534    fn close(&mut self) {
535        self.closed = true;
536        for entry in self.entries.values() {
537            entry.state.send_modify(|state| state.closed = true);
538        }
539    }
540
541    /// File again each subscription whose tracking changed since the last
542    /// filing, and forget each one whose last clone dropped.
543    fn refile(&mut self) {
544        let Refiling { changed, dropped } = std::mem::take(&mut *lock_unpoisoned(&self.refiling));
545        for id in changed.difference(&dropped) {
546            if let Some(entry) = self.entries.get(id) {
547                self.filed.file(*id, &lock_unpoisoned(&entry.tracked));
548                #[cfg(test)]
549                {
550                    self.entries_read += 1;
551                }
552            }
553        }
554        for id in dropped {
555            self.entries.remove(&id);
556            self.filed.forget(id);
557        }
558    }
559
560    /// Each subscription filed as waiting that `changes`, made within
561    /// `scope`, could affect, not marked to run again already, with the
562    /// epoch and reads it was filed with and the positions of those changes.
563    fn candidates(
564        &self,
565        changes: &[RowChange],
566        scope: Option<CommitScope>,
567    ) -> Vec<(SubscriptionId, u64, Arc<ReadSet>, Vec<usize>)> {
568        self.filed
569            .waiting
570            .candidates(changes)
571            .into_iter()
572            .filter_map(|(id, positions)| {
573                let entry = &self.entries[&id];
574                if entry.outside_of(scope) || entry.marked() {
575                    return None;
576                }
577                let Some(Filing::Waiting { epoch, reads }) = self.filed.filings.get(&id) else {
578                    unreachable!("the index holds only waiting subscriptions' reads")
579                };
580                Some((id, *epoch, Arc::clone(reads), positions))
581            })
582            .collect()
583    }
584
585    /// Tell each subscription a commit of `changes` made within `scope`
586    /// could reach of it (`Handle::commit`), with the write's `verdicts`:
587    /// those filed as reading, and those filed as waiting that the index
588    /// finds for the changes. One filed as waiting that the index finds
589    /// for none of them is affected by none of them; one whose tracking
590    /// changed since the filing began a run after the commit, or finished
591    /// one it was filed as reading for.
592    fn commit(
593        &self,
594        changes: &Arc<Vec<RowChange>>,
595        verdicts: &HashMap<SubscriptionId, (u64, bool)>,
596        scope: Option<CommitScope>,
597    ) {
598        let crowded = past_row_limit(changes);
599        for id in &self.filed.reading {
600            let entry = &self.entries[id];
601            if !entry.outside_of(scope) {
602                entry.tell(*id, changes, &crowded, None, verdicts);
603            }
604        }
605        for (id, epoch, _, positions) in self.candidates(changes, scope) {
606            self.entries[&id].tell(id, changes, &crowded, Some((epoch, &positions)), verdicts);
607        }
608    }
609}
610
611impl Drop for ObserverState {
612    fn drop(&mut self) {
613        self.close();
614    }
615}
616
617/// The failure state and the subscriptions that several databases share: a
618/// failure in one fails every later call and live query on each, with the
619/// host's failure type `F`.
620#[derive(Clone)]
621pub struct Handle<F> {
622    state: Arc<Mutex<ObserverState>>,
623    /// Where a bug that fails the handle outside its calls goes (E15).
624    bugs: BugSinkRef,
625    /// The tables whose changes no write records.
626    unrecorded: Arc<UnrecordedTables>,
627    /// How many more of the databases' upkeep threads start before the
628    /// handle refuses the next, when a test asked for that.
629    #[cfg(any(test, feature = "test-utils"))]
630    upkeep_threads: Arc<Mutex<Option<usize>>>,
631    failure: PhantomData<fn() -> F>,
632}
633
634impl<F: Clone + Send + Sync + 'static> Handle<F> {
635    /// A handle whose bugs outside its calls go to `bugs`, and whose
636    /// databases' writes record no changes to the tables `unrecorded` names
637    /// for live queries.
638    pub fn new(bugs: BugSinkRef, unrecorded: Vec<String>) -> Self {
639        Self {
640            state: Arc::new(Mutex::new(ObserverState {
641                entries: HashMap::new(),
642                next: 0,
643                filed: Filed::default(),
644                refiling: Arc::new(Mutex::new(Refiling::default())),
645                closed: false,
646                failure: None,
647                #[cfg(test)]
648                entries_read: 0,
649            })),
650            bugs,
651            unrecorded: Arc::new(UnrecordedTables::new(unrecorded.iter().map(String::as_str))),
652            #[cfg(any(test, feature = "test-utils"))]
653            upkeep_threads: Arc::new(Mutex::new(None)),
654            failure: PhantomData,
655        }
656    }
657
658    /// A test handle for which every table records its changes.
659    #[cfg(any(test, feature = "test-utils"))]
660    pub fn recording_all(bugs: BugSinkRef) -> Self {
661        Self::new(bugs, Vec::new())
662    }
663
664    /// The tables whose changes no write records.
665    pub fn unrecorded(&self) -> &Arc<UnrecordedTables> {
666        &self.unrecorded
667    }
668
669    /// Let `started` upkeep threads start, if given, and refuse the next.
670    #[cfg(any(test, feature = "test-utils"))]
671    pub fn refuse_upkeep_thread_after(&self, started: Option<usize>) {
672        *lock_unpoisoned(&self.upkeep_threads) = started;
673    }
674
675    /// Whether the system refuses the upkeep thread starting now.
676    #[cfg(any(test, feature = "test-utils"))]
677    pub fn upkeep_thread_refused(&self) -> bool {
678        let mut left = lock_unpoisoned(&self.upkeep_threads);
679        match left.as_mut() {
680            Some(0) => true,
681            Some(left) => {
682                *left -= 1;
683                false
684            }
685            None => false,
686        }
687    }
688
689    /// Observe every commit from now on.
690    pub fn subscribe(&self) -> CommitSubscription {
691        self.subscribe_outside(None)
692    }
693
694    /// Observe every commit except those made within `outside`. Once the
695    /// database has closed, a new subscription reports that it closed, as a
696    /// call to the database does, not the failure it may have closed with.
697    pub fn subscribe_outside(&self, outside: Option<CommitScope>) -> CommitSubscription {
698        CommitSubscription::new(&self.state, outside, Arc::clone(&self.unrecorded))
699    }
700
701    /// Watch `reads` from now on; `first` reports the state now as their
702    /// first change.
703    pub fn changes<R: 'static, E: 'static>(
704        &self,
705        reads: ReadSet,
706        first: bool,
707        failed: fn(Error<F, R>) -> E,
708    ) -> DatabaseChanges<E> {
709        let commits = self.subscribe();
710        commits.begin();
711        commits.finish(reads.clone());
712        DatabaseChanges::new(commits, reads, first, Self::failed(failed))
713    }
714
715    /// Keep every commit made from now on outside `attempt`, until the
716    /// attempt names the rows it waits on (`watch_attempt`).
717    pub fn attempt(&self, attempt: CommitScope) -> AttemptCommits {
718        let commits = self.subscribe_outside(Some(attempt));
719        commits.begin();
720        AttemptCommits { commits }
721    }
722
723    /// Watch `reads` after `attempt`: the returned changes report at once a
724    /// commit since the attempt began that changed what they read, as
725    /// evidence against the wait the attempt ended in.
726    pub fn watch_attempt<R: 'static, E: 'static>(
727        &self,
728        attempt: AttemptCommits,
729        reads: ReadSet,
730        failed: fn(Error<F, R>) -> E,
731    ) -> DatabaseChanges<E> {
732        attempt.commits.finish(reads.clone());
733        DatabaseChanges::new(attempt.commits, reads, false, Self::failed(failed))
734    }
735
736    /// How a live query's or a change watch's error type holds what stops
737    /// it, through `failed`.
738    pub(crate) fn failed<R: 'static, E: 'static>(failed: fn(Error<F, R>) -> E) -> Failed<E> {
739        Arc::new(move |stop| {
740            failed(match stop {
741                Stop::Failed(failure) => Self::failure_error(&failure),
742                Stop::Closed => Error::Closed,
743                Stop::Bug(bug) => Error::Bug(bug),
744            })
745        })
746    }
747
748    /// The error every call on a handle that failed with `failure` returns.
749    fn failure_error<R>(failure: &Failure) -> Error<F, R> {
750        match failure {
751            Failure::Host(host) => Error::Host(
752                host.downcast_ref::<F>()
753                    .expect("a handle's failure has its host's failure type")
754                    .clone(),
755            ),
756            Failure::Bug(bug) => Error::HandleFailed(bug.clone()),
757        }
758    }
759
760    /// Judge a write's `changes`, made within `scope`, for every live query
761    /// waiting on known reads that isn't already marked to run again and
762    /// that the changes could affect, with `lookups` reading the write's
763    /// transaction before it commits (§4).
764    pub fn judge(
765        &self,
766        changes: Vec<RowChange>,
767        scope: Option<CommitScope>,
768        lookups: &mut Lookups<'_>,
769    ) -> rusqlite::Result<Judged> {
770        let candidates = self.with_state(|state| state.candidates(&changes, scope));
771        let mut verdicts = HashMap::with_capacity(candidates.len());
772        {
773            let crowded = past_row_limit(&changes);
774            let mut answers = Answers::default();
775            for (id, epoch, reads, positions) in candidates {
776                let found = affected_by(
777                    &reads,
778                    positions.iter().map(|&position| &changes[position]),
779                    &crowded,
780                    &mut answers,
781                    lookups,
782                )?;
783                verdicts.insert(id, (epoch, found));
784            }
785        }
786        Ok(Judged { changes: Arc::new(changes), verdicts })
787    }
788
789    /// Tell live queries that each of `columns`, a (table, column) pair of a
790    /// view, changed with no write: each query that read one runs again.
791    pub fn changed_without_write(&self, columns: &[(&str, &str)]) {
792        let changes = columns
793            .iter()
794            .map(|(table, column)| RowChange {
795                table: (*table).into(),
796                column: (*column).into(),
797                rows: None,
798            })
799            .collect();
800        self.commit(Judged::unjudged(changes), None);
801    }
802
803    /// Report a commit made within `scope`, if any. A query still waiting on
804    /// the reads it was judged against takes its verdict. One running keeps
805    /// the changes, to judge against its run's snapshot as it finishes. One
806    /// that finished another run since, or wasn't judged, judges the
807    /// changes counting every join's value as matched: their transaction
808    /// has ended, so no lookup can read it. A waiting query the index finds
809    /// for none of the changes is affected by none of them.
810    pub fn commit(&self, judged: Judged, scope: Option<CommitScope>) {
811        let Judged { changes, verdicts } = judged;
812        self.with_state(|state| state.commit(&changes, &verdicts, scope));
813    }
814
815    /// The columns some subscription reads or its scope tests, by table,
816    /// all lowercase: a waiting one's, or a running one's previous run's.
817    /// Each table such a subscription reads is here, with no column where
818    /// it reads none. A write keys the rows it changes in these tables and
819    /// keeps those values of them, so it can tell each row's net change and
820    /// test the row against the scopes (`net_changes.rs`). A change to any
821    /// other table needs no values to wake the subscriptions that read it.
822    pub fn kept_columns(&self) -> BTreeMap<String, BTreeSet<String>> {
823        self.with_state(|state| state.filed.kept.columns())
824    }
825
826    /// What every call on the handle fails with: its failure, or
827    /// `Error::Closed` once it closed.
828    pub fn error<R>(&self) -> Option<Error<F, R>> {
829        self.with_state(|state| match &state.failure {
830            Some(failure) => Some(Self::failure_error(failure)),
831            None => state.closed.then_some(Error::Closed),
832        })
833    }
834
835    /// Whether the handle failed: a handle its host only closed hasn't.
836    pub fn has_failed(&self) -> bool {
837        self.with_state(|state| state.failure.is_some())
838    }
839
840    /// Fail every later call and subscription with `failure`. The handle
841    /// keeps the first failure and ignores later ones.
842    pub fn fail(&self, failure: F) {
843        self.with_state(|state| state.fail(Failure::Host(Arc::new(failure))));
844    }
845
846    /// Fail every later call and subscription with the host's failure made
847    /// from `failure`, one of sqlive's own.
848    pub fn fail_engine<R>(&self, failure: EngineFailure<F, R>)
849    where
850        F: From<EngineFailure<F, R>>,
851    {
852        self.fail(F::from(failure));
853    }
854
855    /// Fail the handle with `bug`, a panic in work that may have held its
856    /// state or a fault a drop found in it. The handle fails with this bug,
857    /// not the one a poisoned lock would name. The bug goes to one
858    /// reporter: the handle's call this thread runs, which returns it as
859    /// its own (`calling`), or the handle's bug sink, outside such a call or
860    /// once the call has a bug of its own already (E15).
861    pub fn fail_with_bug(&self, bug: Bug) {
862        {
863            let mut state = self.state.lock().unwrap_or_else(|poisoned| {
864                self.state.clear_poison();
865                poisoned.into_inner()
866            });
867            state.fail(Failure::Bug(bug.clone()));
868        }
869        let handle = self.id();
870        // A drop as this thread ends finds its locals gone: no call runs.
871        let unclaimed = CALL
872            .try_with(|call| match call.borrow_mut().as_mut() {
873                Some(call) if call.handle == handle && call.bug.is_none() => {
874                    call.bug = Some(bug.clone());
875                    None
876                }
877                _ => Some(bug.clone()),
878            })
879            .unwrap_or(Some(bug));
880        if let Some(bug) = unclaimed {
881            self.report(&bug);
882        }
883    }
884
885    /// Run `call`, one of this handle's calls, on this thread. Beside its
886    /// result comes the bug its own work failed the handle with, if any,
887    /// which the call returns as its own (E15). A call that unwinds leaves
888    /// that bug to the sink: its panic is the call's bug then. A call made
889    /// inside another on the same handle is part of it, and leaves its bug
890    /// to the outer one, which the app hears from.
891    pub fn calling<R>(&self, call: impl FnOnce() -> R) -> (R, Option<Bug>) {
892        let handle = self.id();
893        if CALL
894            .with(|running| running.borrow().as_ref().is_some_and(|outer| outer.handle == handle))
895        {
896            return (call(), None);
897        }
898        let outer = CALL.with(|running| running.replace(Some(Call { handle, bug: None })));
899        let scope = CallScope { outer, observer: self };
900        let result = call();
901        let bug =
902            CALL.with(|running| running.borrow_mut().as_mut().and_then(|call| call.bug.take()));
903        drop(scope);
904        (result, bug)
905    }
906
907    /// Hand `bug`, which no call returns, to the handle's bug sink (E15).
908    pub fn report(&self, bug: &Bug) {
909        panic_as_error::report(self.bugs.as_ref(), bug);
910    }
911
912    /// This handle, as `CALL` names it.
913    fn id(&self) -> usize {
914        Arc::as_ptr(&self.state) as usize
915    }
916
917    /// Close the handle: every subscription and later call reports it.
918    pub fn close(&self) {
919        self.with_state(ObserverState::close);
920    }
921
922    /// Panic while holding the handle's state, as a bug in judging a commit
923    /// for live queries would.
924    #[cfg(any(test, feature = "test-utils"))]
925    pub fn test_poison(&self) {
926        std::thread::scope(|scope| {
927            let holder = scope.spawn(|| {
928                let _held = self.state.lock();
929                panic!("a live query's judgment broke");
930            });
931            assert!(holder.join().is_err());
932        });
933    }
934
935    /// Run `change` on the handle's state (`with_locked`).
936    fn with_state<R>(&self, change: impl FnOnce(&mut ObserverState) -> R) -> R {
937        with_locked(&self.state, change)
938    }
939}
940
941/// One of a handle's calls running on a thread (`Handle::calling`), which
942/// restores the call it runs inside, if any, as it ends.
943struct CallScope<'a, F: Clone + Send + Sync + 'static> {
944    outer: Option<Call>,
945    observer: &'a Handle<F>,
946}
947
948impl<F: Clone + Send + Sync + 'static> Drop for CallScope<'_, F> {
949    fn drop(&mut self) {
950        let ended = CALL.with(|call| call.replace(self.outer.take()));
951        if let Some(bug) = ended.and_then(|ended| ended.bug) {
952            self.observer.report(&bug);
953        }
954    }
955}
956
957#[cfg(test)]
958#[path = "handle_tests.rs"]
959mod tests;