1use 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#[derive(Debug)]
25pub struct UnrecordedTables(BTreeSet<String>);
26
27impl UnrecordedTables {
28 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 pub fn recorded(&self, table: &str) -> bool {
35 !self.0.contains(&table.to_ascii_lowercase())
36 }
37}
38
39#[derive(Clone)]
44pub(crate) enum Failure {
45 Host(Arc<dyn Any + Send + Sync>),
48 Bug(Bug),
52}
53
54pub(crate) enum Stop {
57 Failed(Failure),
59 Closed,
61 Bug(Bug),
63}
64
65pub(crate) type Failed<E> = Arc<dyn Fn(Stop) -> E + Send + Sync>;
68
69#[derive(Clone)]
72pub struct CommitState {
73 pub changed: bool,
76 closed: bool,
77 failure: Option<Failure>,
78}
79
80impl CommitState {
81 pub fn closed(&self) -> bool {
83 self.closed
84 }
85
86 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 pub fn stopped(&self) -> bool {
97 self.closed || self.failure.is_some()
98 }
99}
100
101enum Tracking {
102 Reading {
106 commits: Vec<Arc<Vec<RowChange>>>,
107 previous: Arc<ReadSet>,
108 },
109 Waiting(Arc<ReadSet>),
110}
111
112impl Tracking {
113 fn kept(&self) -> &Arc<ReadSet> {
117 match self {
118 Self::Reading { previous: reads, .. } | Self::Waiting(reads) => reads,
119 }
120 }
121}
122
123struct Tracked {
126 tracking: Tracking,
127 epoch: u64,
128}
129
130impl Tracked {
131 fn set(&mut self, tracking: Tracking) {
133 self.tracking = tracking;
134 self.epoch += 1;
135 }
136}
137
138struct Entry {
141 tracked: Mutex<Tracked>,
142 state: watch::Sender<CommitState>,
143 outside: Option<CommitScope>,
145}
146
147impl Entry {
148 fn outside_of(&self, scope: Option<CommitScope>) -> bool {
150 scope.is_some() && scope == self.outside
151 }
152
153 fn marked(&self) -> bool {
155 self.state.borrow().changed
156 }
157
158 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#[derive(Default)]
210struct Refiling {
211 changed: BTreeSet<SubscriptionId>,
212 dropped: BTreeSet<SubscriptionId>,
213}
214
215struct SubscriptionState {
218 id: SubscriptionId,
219 entry: Arc<Entry>,
220 refiling: Arc<Mutex<Refiling>>,
221 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#[derive(Clone)]
234pub struct CommitSubscription {
235 shared: Arc<SubscriptionState>,
236 receiver: watch::Receiver<CommitState>,
237}
238
239impl CommitSubscription {
240 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 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 pub fn state(&self) -> CommitState {
281 self.receiver.borrow().clone()
282 }
283
284 pub fn observe(&mut self) -> CommitState {
287 self.receiver.borrow_and_update().clone()
288 }
289
290 pub async fn changed(&mut self) {
292 self.receiver.changed().await.expect("subscription owns its sender");
293 }
294
295 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 pub fn stop(&self) {
309 self.track(|tracked| {
310 tracked.set(Tracking::Waiting(Arc::new(Vec::new())));
311 });
312 }
313
314 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 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 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
372pub struct Judged {
376 changes: Arc<Vec<RowChange>>,
377 verdicts: HashMap<SubscriptionId, (u64, bool)>,
382}
383
384impl Judged {
385 fn unjudged(changes: Vec<RowChange>) -> Self {
388 Self { changes: Arc::new(changes), verdicts: HashMap::new() }
389 }
390
391 #[cfg(any(test, feature = "test-utils"))]
393 pub(crate) fn judgments(&self) -> usize {
394 self.verdicts.len()
395 }
396}
397
398pub struct AttemptCommits {
401 commits: CommitSubscription,
402}
403
404struct ObserverState {
405 entries: HashMap<SubscriptionId, Arc<Entry>>,
407 next: SubscriptionId,
409 filed: Filed,
412 refiling: Arc<Mutex<Refiling>>,
414 closed: bool,
415 failure: Option<Failure>,
416 #[cfg(test)]
418 entries_read: usize,
419}
420
421thread_local! {
422 #[cfg_attr(target_os = "android", allow(clippy::missing_const_for_thread_local))]
428 static CALL: RefCell<Option<Call>> = const { RefCell::new(None) };
429}
430
431struct Call {
433 handle: usize,
435 bug: Option<Bug>,
438}
439
440#[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
447enum Filing {
450 Waiting { epoch: u64, reads: Arc<ReadSet> },
451 Reading { previous: Arc<ReadSet> },
452}
453
454impl Filing {
455 fn kept(&self) -> &ReadSet {
457 match self {
458 Self::Waiting { reads, .. } | Self::Reading { previous: reads } => reads,
459 }
460 }
461}
462
463#[derive(Default)]
468struct Filed {
469 filings: HashMap<SubscriptionId, Filing>,
470 waiting: ReadIndex,
471 reading: BTreeSet<SubscriptionId>,
472 kept: KeptCounts,
473}
474
475impl Filed {
476 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 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
508fn 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 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 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 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 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#[derive(Clone)]
621pub struct Handle<F> {
622 state: Arc<Mutex<ObserverState>>,
623 bugs: BugSinkRef,
625 unrecorded: Arc<UnrecordedTables>,
627 #[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 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 #[cfg(any(test, feature = "test-utils"))]
660 pub fn recording_all(bugs: BugSinkRef) -> Self {
661 Self::new(bugs, Vec::new())
662 }
663
664 pub fn unrecorded(&self) -> &Arc<UnrecordedTables> {
666 &self.unrecorded
667 }
668
669 #[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 #[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 pub fn subscribe(&self) -> CommitSubscription {
691 self.subscribe_outside(None)
692 }
693
694 pub fn subscribe_outside(&self, outside: Option<CommitScope>) -> CommitSubscription {
698 CommitSubscription::new(&self.state, outside, Arc::clone(&self.unrecorded))
699 }
700
701 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 pub fn attempt(&self, attempt: CommitScope) -> AttemptCommits {
718 let commits = self.subscribe_outside(Some(attempt));
719 commits.begin();
720 AttemptCommits { commits }
721 }
722
723 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 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 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 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 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 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 pub fn kept_columns(&self) -> BTreeMap<String, BTreeSet<String>> {
823 self.with_state(|state| state.filed.kept.columns())
824 }
825
826 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 pub fn has_failed(&self) -> bool {
837 self.with_state(|state| state.failure.is_some())
838 }
839
840 pub fn fail(&self, failure: F) {
843 self.with_state(|state| state.fail(Failure::Host(Arc::new(failure))));
844 }
845
846 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 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 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 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 pub fn report(&self, bug: &Bug) {
909 panic_as_error::report(self.bugs.as_ref(), bug);
910 }
911
912 fn id(&self) -> usize {
914 Arc::as_ptr(&self.state) as usize
915 }
916
917 pub fn close(&self) {
919 self.with_state(ObserverState::close);
920 }
921
922 #[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 fn with_state<R>(&self, change: impl FnOnce(&mut ObserverState) -> R) -> R {
937 with_locked(&self.state, change)
938 }
939}
940
941struct 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;