Skip to main content

khive_db/
progress_conn.rs

1//! A SQLite connection whose progress handler is installed once, when it is built.
2//!
3//! rusqlite 0.41 takes `&mut Connection` to install any hook, while read scopes run on shared
4//! borrows handed out by the pool. So the handler is installed here, with the owned connection,
5//! and never per read: it asks the per-thread read registration whether a statement on THIS
6//! connection should stop (`read_cancellation::progress_stop`). A read scope accepts only a
7//! `ProgressConn`, so a connection without the handler cannot reach one.
8
9use std::ops::Deref;
10use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
11
12use rusqlite::Connection;
13
14/// SQLite VM steps between progress callbacks.
15const PROGRESS_STEPS: std::os::raw::c_int = 1_000;
16
17static NEXT_ID: AtomicU64 = AtomicU64::new(1);
18
19/// A connection carrying the read-cancellation progress handler and a process-unique identity.
20///
21/// It dereferences to [`Connection`] for statements but gives no `&mut Connection` outside
22/// [`ProgressConn::with_mut`], which re-installs the handler afterwards, so nothing can replace
23/// or remove it:
24/// ```compile_fail
25/// use khive_db::ProgressConn;
26/// let mut conn = ProgressConn::new(rusqlite::Connection::open_in_memory().unwrap()).unwrap();
27/// conn.progress_handler(0, None::<fn() -> bool>).unwrap();
28/// ```
29#[derive(Debug)]
30#[doc(hidden)]
31pub struct ProgressConn {
32    conn: Connection,
33    id: u64,
34    unarmed: AtomicBool,
35}
36
37impl ProgressConn {
38    /// Takes the connection and installs the handler.
39    pub fn new(mut conn: Connection) -> rusqlite::Result<Self> {
40        let id = NEXT_ID.fetch_add(1, Ordering::Relaxed);
41        #[cfg(any(test, feature = "test-support"))]
42        crate::test_hooks::adopt(&mut conn)?;
43        arm(&mut conn, id)?;
44        Ok(ProgressConn {
45            conn,
46            id,
47            unarmed: AtomicBool::new(false),
48        })
49    }
50
51    /// The identity a read registration names.
52    pub(crate) fn id(&self) -> u64 {
53        self.id
54    }
55
56    /// Whether the handler is known to be installed. A failed re-install leaves the connection
57    /// unarmed, and a read scope then refuses it.
58    pub(crate) fn armed(&self) -> bool {
59        !self.unarmed.load(Ordering::Acquire)
60    }
61
62    /// Runs `f` with the owned connection, then installs the handler again on return or unwind.
63    /// If that install fails the connection stays usable for writes but no read scope accepts it.
64    pub fn with_mut<R>(&mut self, f: impl FnOnce(&mut Connection) -> R) -> R {
65        struct Rearm<'a> {
66            conn: &'a mut Connection,
67            id: u64,
68            unarmed: &'a AtomicBool,
69        }
70
71        impl Drop for Rearm<'_> {
72            fn drop(&mut self) {
73                if let Err(error) = arm(self.conn, self.id) {
74                    self.unarmed.store(true, Ordering::Release);
75                    tracing::error!(target: "khive_db::pool", %error, "failed to re-install the read progress handler");
76                }
77            }
78        }
79
80        let rearm = Rearm {
81            conn: &mut self.conn,
82            id: self.id,
83            unarmed: &self.unarmed,
84        };
85        f(rearm.conn)
86    }
87
88    /// Counts progress at `period` VM steps through `hook` until [`Self::test_progress_reset`];
89    /// the registered test delegate and read-cancellation verdict still apply.
90    #[cfg(test)]
91    pub(crate) fn test_progress_every(
92        &mut self,
93        period: std::os::raw::c_int,
94        hook: impl FnMut() -> bool + Send + 'static,
95    ) {
96        install_progress(&mut self.conn, self.id, period, hook)
97            .expect("install the test progress handler");
98    }
99
100    #[cfg(test)]
101    pub(crate) fn test_progress_reset(&mut self) {
102        arm(&mut self.conn, self.id).expect("re-install the progress handler");
103    }
104
105    /// The connection, for closing it. The handler stays installed and its identity is never
106    /// registered again, so it never stops a statement.
107    pub(crate) fn into_inner(self) -> Connection {
108        #[cfg(any(test, feature = "test-support"))]
109        crate::test_hooks::unregister(&self.conn);
110        self.conn
111    }
112}
113
114impl Deref for ProgressConn {
115    type Target = Connection;
116
117    fn deref(&self) -> &Connection {
118        &self.conn
119    }
120}
121
122fn arm(conn: &mut Connection, id: u64) -> rusqlite::Result<()> {
123    install_progress(conn, id, PROGRESS_STEPS, || false)
124}
125
126fn install_progress(
127    conn: &mut Connection,
128    id: u64,
129    period: std::os::raw::c_int,
130    mut observer: impl FnMut() -> bool + Send + 'static,
131) -> rusqlite::Result<()> {
132    #[cfg(any(test, feature = "test-support"))]
133    let test_slots = crate::test_hooks::slots_of(conn);
134    conn.progress_handler(
135        period,
136        Some(move || {
137            if observer() {
138                return true;
139            }
140            #[cfg(any(test, feature = "test-support"))]
141            if test_slots
142                .as_deref()
143                .is_some_and(crate::test_hooks::progress)
144            {
145                return true;
146            }
147            crate::read_cancellation::progress_stop(id)
148        }),
149    )
150}
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155    use crate::read_cancellation::with_traversal_stop;
156    use crate::test_hooks::TestHooks;
157    use std::panic::{catch_unwind, AssertUnwindSafe};
158    use std::sync::atomic::AtomicUsize;
159    use std::sync::Arc;
160
161    const SUM: i64 = 50_005_000;
162
163    fn long_read(conn: &ProgressConn) -> rusqlite::Result<i64> {
164        conn.query_row(
165            "WITH RECURSIVE n(x) AS (VALUES(1) UNION ALL \
166             SELECT x + 1 FROM n WHERE x < 10000) SELECT sum(x) FROM n",
167            [],
168            |row| row.get(0),
169        )
170    }
171
172    fn assert_interrupted(result: rusqlite::Result<i64>, phase: &str) {
173        assert!(
174            matches!(&result, Err(rusqlite::Error::SqliteFailure(error, _))
175                if error.code == rusqlite::ErrorCode::OperationInterrupted),
176            "{phase}: SQLite must interrupt the query, got {result:?}"
177        );
178    }
179
180    #[test]
181    fn with_mut_rearms_after_return_and_unwind() {
182        for panics in [false, true] {
183            let mut conn = ProgressConn::new(Connection::open_in_memory().unwrap()).unwrap();
184            assert_eq!(long_read(&conn).unwrap(), SUM);
185            let result = catch_unwind(AssertUnwindSafe(|| {
186                conn.with_mut(|raw| {
187                    raw.progress_handler(0, None::<fn() -> bool>).unwrap();
188                    if panics {
189                        std::panic::panic_any(73_u64);
190                    }
191                    42
192                })
193            }));
194            if panics {
195                assert_eq!(result.unwrap_err().downcast_ref::<u64>(), Some(&73));
196            } else {
197                assert_eq!(result.unwrap(), 42);
198            }
199            assert!(conn.armed());
200            assert_interrupted(
201                with_traversal_stop(&conn, || true, || long_read(&conn)),
202                if panics {
203                    "after unwind"
204                } else {
205                    "after return"
206                },
207            );
208            assert_eq!(long_read(&conn).unwrap(), SUM);
209        }
210    }
211
212    #[test]
213    fn test_progress_period_preserves_delegate_and_stop() {
214        let mut conn = ProgressConn::new(Connection::open_in_memory().unwrap()).unwrap();
215        let observed = Arc::new(AtomicUsize::new(0));
216        let observer = Arc::clone(&observed);
217        conn.test_progress_every(1, move || {
218            observer.fetch_add(1, Ordering::Relaxed);
219            false
220        });
221        let delegated = Arc::new(AtomicUsize::new(0));
222        let delegate = Arc::clone(&delegated);
223        conn.test_progress_handler(Some(move || {
224            delegate.fetch_add(1, Ordering::Relaxed);
225            true
226        }))
227        .unwrap();
228        assert_interrupted(long_read(&conn), "registered delegate with test cadence");
229        assert!(observed.load(Ordering::Relaxed) > 0);
230        assert!(delegated.load(Ordering::Relaxed) > 0);
231
232        conn.test_progress_handler(None::<fn() -> bool>).unwrap();
233        let delegated_before = delegated.load(Ordering::Relaxed);
234        assert_eq!(long_read(&conn).unwrap(), SUM);
235        assert_eq!(delegated.load(Ordering::Relaxed), delegated_before);
236        assert_interrupted(
237            with_traversal_stop(&conn, || true, || long_read(&conn)),
238            "real stop with test cadence and no delegate",
239        );
240        assert_eq!(long_read(&conn).unwrap(), SUM);
241
242        let delegate = Arc::clone(&delegated);
243        conn.test_progress_handler(Some(move || {
244            delegate.fetch_add(1, Ordering::Relaxed);
245            true
246        }))
247        .unwrap();
248        let observed_before = observed.load(Ordering::Relaxed);
249        conn.test_progress_reset();
250        assert_interrupted(long_read(&conn), "registered delegate after reset");
251        assert_eq!(observed.load(Ordering::Relaxed), observed_before);
252        assert!(delegated.load(Ordering::Relaxed) > delegated_before);
253
254        let observer = Arc::clone(&observed);
255        conn.test_progress_every(1, move || {
256            observer.fetch_add(1, Ordering::Relaxed);
257            true
258        });
259        let delegated_before = delegated.load(Ordering::Relaxed);
260        assert_interrupted(long_read(&conn), "test observer stops before the delegate");
261        assert!(observed.load(Ordering::Relaxed) > observed_before);
262        assert_eq!(delegated.load(Ordering::Relaxed), delegated_before);
263        conn.test_progress_reset();
264        conn.test_progress_handler(None::<fn() -> bool>).unwrap();
265        assert_eq!(long_read(&conn).unwrap(), SUM);
266    }
267}