Skip to main content

second_brain_core/sqlite_store/
pool.rs

1use std::cell::Cell;
2use std::marker::PhantomData;
3use std::path::{Path, PathBuf};
4use std::sync::{Condvar, Mutex, MutexGuard};
5use std::thread;
6use std::time::{Duration, Instant};
7
8use anyhow::{Context, Result};
9use rusqlite::{Connection, ErrorCode};
10
11pub(super) const BUSY_TIMEOUT: Duration = Duration::from_secs(5);
12
13/// Opens one connection with the pragmas every connection in the store needs.
14/// `busy_timeout` is armed before any pragma: switching journal_mode takes a
15/// brief exclusive lock, so two processes opening the same fresh database
16/// concurrently can otherwise hit a hard SQLITE_BUSY with no busy handler
17/// installed yet to retry it.
18pub(super) fn open_connection(path: &Path) -> Result<Connection> {
19    let conn = Connection::open(path)
20        .with_context(|| format!("opening sqlite db at {}", path.display()))?;
21    conn.busy_timeout(BUSY_TIMEOUT)
22        .context("arming busy_timeout")?;
23    set_wal_mode(&conn)?;
24    conn.pragma_update(None, "synchronous", "NORMAL")
25        .context("setting synchronous=NORMAL")?;
26    Ok(conn)
27}
28
29/// `busy_timeout`'s built-in retry loop does not cover the exclusive lock
30/// SQLite takes while switching journal_mode to WAL: two connections racing
31/// to make that switch on the same fresh database can still see a bare
32/// SQLITE_BUSY from the pragma itself, confirmed against this rusqlite
33/// version by a concurrent-open regression test. Retry it by hand, bounded
34/// by the same window `busy_timeout` uses, instead of trusting the driver to
35/// cover a case it does not.
36fn set_wal_mode(conn: &Connection) -> Result<()> {
37    let deadline = Instant::now() + BUSY_TIMEOUT;
38    loop {
39        match conn.pragma_update(None, "journal_mode", "WAL") {
40            Ok(()) => return Ok(()),
41            Err(err) if is_database_busy(&err) && Instant::now() < deadline => {
42                thread::sleep(Duration::from_millis(20));
43            }
44            Err(err) => return Err(err).context("setting journal_mode=WAL"),
45        }
46    }
47}
48
49fn is_database_busy(err: &rusqlite::Error) -> bool {
50    err.sqlite_error_code() == Some(ErrorCode::DatabaseBusy)
51}
52
53/// A sane default reader pool size: enough connections that concurrent
54/// readers stop queueing behind each other, bounded so a store never opens
55/// more file descriptors than the machine has cores to use them with.
56pub(super) fn default_pool_size() -> usize {
57    std::thread::available_parallelism()
58        .map(|n| n.get())
59        .unwrap_or(4)
60        .clamp(2, 16)
61}
62
63thread_local! {
64    static READ_DEADLINE: Cell<Option<Instant>> = const { Cell::new(None) };
65}
66
67/// Bounds the wait for a pooled read connection on this thread until the
68/// guard drops: a read that finds the pool empty waits at most until
69/// `deadline`, then opens a connection of its own, which closes on drop.
70/// That open is bounded by `BUSY_TIMEOUT`, not by the deadline, and if it
71/// fails the read waits for the pool as an unbounded read would.
72/// Thread-local because every store read takes a connection through
73/// `reader()` and a recall's reads all run on the one thread that holds the
74/// guard; the guard is not `Send`, so it cannot be dropped on another.
75pub struct ReadDeadline {
76    previous: Option<Instant>,
77    not_send: PhantomData<*const ()>,
78}
79
80impl ReadDeadline {
81    pub fn set(deadline: Instant) -> Self {
82        ReadDeadline {
83            previous: READ_DEADLINE.replace(Some(deadline)),
84            not_send: PhantomData,
85        }
86    }
87}
88
89impl Drop for ReadDeadline {
90    fn drop(&mut self) {
91        READ_DEADLINE.set(self.previous);
92    }
93}
94
95/// Fixed-size pool of read connections to the same file: `checkout` waits
96/// for a connection to come back rather than ever pooling one past `size`.
97/// WAL gives one writer and many concurrent readers across separate
98/// connections, so each pooled connection is a full physical connection,
99/// not a wrapper over the writer's.
100pub(super) struct ReaderPool {
101    path: PathBuf,
102    free: Mutex<Vec<Connection>>,
103    returned: Condvar,
104}
105
106impl ReaderPool {
107    pub(super) fn open(path: &Path, size: usize) -> Result<Self> {
108        let free = (0..size)
109            .map(|_| open_connection(path))
110            .collect::<Result<Vec<_>>>()?;
111        Ok(Self {
112            path: path.to_path_buf(),
113            free: Mutex::new(free),
114            returned: Condvar::new(),
115        })
116    }
117
118    pub(super) fn checkout(&self) -> PooledConn<'_> {
119        let mut free = self.lock();
120        if let Some(deadline) = READ_DEADLINE.get() {
121            let wait = deadline.saturating_duration_since(Instant::now());
122            free = self
123                .returned
124                .wait_timeout_while(free, wait, |f| f.is_empty())
125                .unwrap_or_else(|e| e.into_inner())
126                .0;
127            if free.is_empty() {
128                drop(free);
129                match open_connection(&self.path) {
130                    Ok(conn) => {
131                        return PooledConn {
132                            conn: Some(conn),
133                            pool: None,
134                        };
135                    }
136                    Err(e) => {
137                        tracing::warn!("no read connection to spare past a deadline: {e:#}");
138                        free = self.lock();
139                    }
140                }
141            }
142        }
143        let mut free = self
144            .returned
145            .wait_while(free, |f| f.is_empty())
146            .unwrap_or_else(|e| e.into_inner());
147        PooledConn {
148            conn: free.pop(),
149            pool: Some(self),
150        }
151    }
152
153    fn lock(&self) -> MutexGuard<'_, Vec<Connection>> {
154        self.free.lock().unwrap_or_else(|e| e.into_inner())
155    }
156}
157
158/// A connection from the pool, or one opened past a read deadline, which
159/// closes on drop instead of joining the pool.
160pub(crate) struct PooledConn<'a> {
161    conn: Option<Connection>,
162    pool: Option<&'a ReaderPool>,
163}
164
165impl std::ops::Deref for PooledConn<'_> {
166    type Target = Connection;
167
168    fn deref(&self) -> &Connection {
169        self.conn.as_ref().expect("taken only in Drop")
170    }
171}
172
173impl Drop for PooledConn<'_> {
174    fn drop(&mut self) {
175        if let (Some(conn), Some(pool)) = (self.conn.take(), self.pool) {
176            pool.lock().push(conn);
177            pool.returned.notify_one();
178        }
179    }
180}
181
182#[cfg(test)]
183mod tests {
184    use std::sync::mpsc;
185    use std::time::Duration;
186
187    use super::*;
188
189    fn pool(size: usize) -> (tempfile::TempDir, ReaderPool) {
190        let dir = tempfile::tempdir().unwrap();
191        let pool = ReaderPool::open(&dir.path().join("brain.db"), size).unwrap();
192        (dir, pool)
193    }
194
195    #[test]
196    fn a_read_past_its_deadline_opens_a_spare_connection_instead_of_waiting() {
197        let (_dir, pool) = pool(1);
198        let held = pool.checkout();
199        let (done, answered) = mpsc::channel();
200        thread::scope(|scope| {
201            scope.spawn(|| {
202                let _bound = ReadDeadline::set(Instant::now() + Duration::from_millis(50));
203                let spare = pool.checkout();
204                let one: i64 = spare.query_row("SELECT 1", [], |r| r.get(0)).unwrap();
205                done.send(one).unwrap();
206            });
207            let answer = answered.recv_timeout(Duration::from_secs(10));
208            drop(held);
209            assert_eq!(
210                answer,
211                Ok(1),
212                "the bounded read waited for the held connection"
213            );
214        });
215        assert_eq!(pool.lock().len(), 1, "only the pooled connection came back");
216    }
217
218    #[test]
219    fn a_read_without_a_deadline_waits_for_a_pooled_connection() {
220        let (_dir, pool) = pool(1);
221        let held = pool.checkout();
222        let (done, answered) = mpsc::channel();
223        thread::scope(|scope| {
224            scope.spawn(|| {
225                let conn = pool.checkout();
226                done.send(conn.is_autocommit()).unwrap();
227            });
228            assert!(answered.recv_timeout(Duration::from_millis(100)).is_err());
229            drop(held);
230            assert!(answered.recv_timeout(Duration::from_secs(10)).is_ok());
231        });
232    }
233
234    #[test]
235    fn a_deadline_guard_restores_the_one_before_it() {
236        let outer = Instant::now() + Duration::from_secs(60);
237        let _outer = ReadDeadline::set(outer);
238        {
239            let _inner = ReadDeadline::set(Instant::now());
240        }
241        assert_eq!(READ_DEADLINE.get(), Some(outer));
242    }
243}