sqlive/test_records.rs
1//! What a test reads back of a connection's work: the work it counts, the
2//! statements its reads run, and the points a write transaction passes; and
3//! the costs a measurement prints for the performance suite.
4
5use panic_as_error::locks::lock_unpoisoned;
6use std::sync::{Arc, Mutex};
7
8/// The work a connection counts: its commits, its reads of the schema
9/// cookie, and the steps of the statements it runs for the app and for live
10/// queries' lookups.
11#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
12pub struct ConnectionWork {
13 /// Successful durable transaction commits, unchanged transactions'
14 /// included.
15 pub commits: usize,
16 /// Reads of SQLite's schema cookie.
17 pub cookie_reads: usize,
18 /// SQLite virtual machine steps the app's statements that return rows
19 /// ran.
20 pub app_read_steps: usize,
21 /// The app's statements that return rows, one per run.
22 pub app_read_statements: usize,
23 /// SQLite virtual machine steps the app's statements that write ran,
24 /// triggers' included.
25 pub app_write_steps: usize,
26 /// Steps of the lookups judging whether a write changed rows a live
27 /// query joins.
28 pub lookup_steps: usize,
29 /// Live queries that a write judged its changes against, one for each
30 /// write that judged each: those it could affect.
31 pub judged_queries: usize,
32 /// Questions about a changed row that ran past `LOOKUP_STEPS` and
33 /// stopped, each of which reran a live query.
34 pub stopped_questions: usize,
35}
36
37/// Where connections count their work. Clones count into the same place.
38#[derive(Clone, Default)]
39pub struct ConnectionWorkCounter(Arc<Mutex<ConnectionWork>>);
40
41impl ConnectionWorkCounter {
42 /// A counter that no connection has counted into yet.
43 pub fn new() -> Self {
44 Self::default()
45 }
46
47 /// The work counted since the last take, starting the count again.
48 pub fn take(&self) -> ConnectionWork {
49 std::mem::take(&mut *lock_unpoisoned(&self.0))
50 }
51
52 /// Count work a connection did.
53 pub(crate) fn record(&self, update: impl FnOnce(&mut ConnectionWork)) {
54 update(&mut lock_unpoisoned(&self.0));
55 }
56}
57
58/// The statements that reads ran on the connections this log was given to,
59/// in order, from when each connection got it. Clones share one log.
60#[derive(Clone, Default)]
61pub struct StatementLog(Arc<Mutex<Vec<String>>>);
62
63impl StatementLog {
64 /// A log no connection has recorded into yet.
65 pub fn new() -> Self {
66 Self::default()
67 }
68
69 /// The recorded statements so far, each as SQLite's text with the bound
70 /// values written in.
71 pub fn statements(&self) -> Vec<String> {
72 lock_unpoisoned(&self.0).clone()
73 }
74
75 /// The recorded statements so far, emptying the log.
76 pub fn take(&self) -> Vec<String> {
77 std::mem::take(&mut lock_unpoisoned(&self.0))
78 }
79
80 pub(crate) fn push(&self, statement: String) {
81 lock_unpoisoned(&self.0).push(statement);
82 }
83}
84
85/// A point a write transaction passes as it commits, for tests that stop or
86/// end the process there.
87#[derive(Clone, Copy, Debug, PartialEq, Eq)]
88pub enum CommitPoint {
89 /// Live queries have judged the write, before SQLite commits it.
90 Judged,
91 /// SQLite has committed, before the handle's subscribers hear of it.
92 Committed,
93 /// The handle's subscribers have heard of the commit.
94 Observed,
95}
96
97/// What a connection calls at each commit point.
98pub(crate) type CommitPointObserver = Box<dyn Fn(CommitPoint) + Send>;
99
100/// One measured number, as a line `scripts/perf.sh` reads:
101/// `COST metric=<name> value=<n> unit=<ms|ratio|count>`. Lower is better in
102/// every unit. A character in `metric` outside letters, digits and `_./-`
103/// becomes `_`, so a caller can pass a label unchanged.
104pub fn report_cost(metric: &str, value: f64, unit: &str) {
105 let metric: String = metric
106 .chars()
107 .map(|c| if c.is_ascii_alphanumeric() || "_./-".contains(c) { c } else { '_' })
108 .collect();
109 eprintln!("COST metric={metric} value={value} unit={unit}");
110}
111
112/// [`report_cost`] for a time, in milliseconds.
113pub fn report_time(metric: &str, time: std::time::Duration) {
114 report_cost(metric, time.as_secs_f64() * 1000.0, "ms");
115}