Skip to main content

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}