Skip to main content

khive_db/pool/
acquisition.rs

1//! Reader and writer acquisition with bounded admission.
2
3use std::cell::Cell;
4use std::sync::atomic::Ordering;
5use std::sync::Arc;
6use std::thread;
7use std::time::{Duration, Instant};
8
9use khive_storage::error::StorageError;
10use khive_storage::StorageCapability;
11
12use crate::error::SqliteError;
13use crate::ProgressConn;
14
15use super::{
16    deny_retired_writer, pool_exhausted_error, CheckpointGuard, ConnectionPool, ReaderAdmission,
17    ReaderGuard, ReaderLease, WriterGuard,
18};
19
20impl ConnectionPool {
21    /// Check out a reader connection.
22    ///
23    /// Tries to pop from the lock-free queue. If empty, spins briefly then
24    /// waits with exponential backoff up to `checkout_timeout`.
25    ///
26    /// In degraded mode (WAL unavailable, `max_readers == 0`), this method
27    /// checks the shared writer mutex in bounded slices and returns pool
28    /// exhaustion after `checkout_timeout`; it never blocks indefinitely on
29    /// the non-reentrant mutex.
30    pub fn reader(&self) -> Result<ReaderGuard<'_>, SqliteError> {
31        self.reader_until(|| false)?.ok_or_else(|| {
32            SqliteError::InvalidData("uncancelled reader checkout stopped unexpectedly".into())
33        })
34    }
35
36    /// Check out a reader while cooperatively polling a request cancellation
37    /// predicate. The predicate is evaluated before connection acquisition and
38    /// between backoff slices, so an abandoned request does not sit through the
39    /// full pool checkout timeout or execute a statement when a reader later
40    /// becomes available.
41    pub(crate) fn reader_until<C>(
42        &self,
43        should_stop: C,
44    ) -> Result<Option<ReaderGuard<'_>>, SqliteError>
45    where
46        C: Fn() -> bool,
47    {
48        let started = Instant::now();
49        let mut admission_attempt = 0u32;
50        let admission_slot = loop {
51            if should_stop() {
52                return Ok(None);
53            }
54            match Arc::clone(&self.sql_bridge_reader_slots).try_acquire_owned() {
55                Ok(slot) => break slot,
56                Err(tokio::sync::TryAcquireError::Closed) => {
57                    return Err(SqliteError::InvalidData(
58                        "reader admission semaphore is closed".to_string(),
59                    ));
60                }
61                Err(tokio::sync::TryAcquireError::NoPermits) => {}
62            }
63            if started.elapsed() >= self.config.checkout_timeout {
64                self.reader_acquisition_counters.record_checkout_timeout();
65                return Err(pool_exhausted_error(
66                    self.config.checkout_timeout,
67                    self.max_readers,
68                ));
69            }
70            match admission_attempt {
71                0..=7 => {
72                    let spins = 1usize << admission_attempt;
73                    for _ in 0..spins {
74                        std::hint::spin_loop();
75                    }
76                }
77                8..=15 => thread::yield_now(),
78                _ => {
79                    let remaining = self
80                        .config
81                        .checkout_timeout
82                        .saturating_sub(started.elapsed());
83                    let sleep =
84                        Duration::from_micros(50 * (1u64 << (admission_attempt - 16).min(6)));
85                    thread::sleep(sleep.min(remaining).min(Duration::from_millis(2)));
86                }
87            }
88            admission_attempt = admission_attempt.saturating_add(1);
89        };
90
91        self.reader_with_admission(
92            ReaderAdmission {
93                slot: admission_slot,
94                started,
95            },
96            should_stop,
97        )
98    }
99
100    /// Wait for one pool-wide reader admission permit on the async side, so a
101    /// read that has to queue costs a task and not a blocking-pool thread.
102    ///
103    /// The wait is bounded by `checkout_timeout` and by the current request's
104    /// cancellation and deadline, and it yields the same `Ok(Some)` / `Ok(None)`
105    /// / `Err` outcomes the permit loop in [`Self::reader_until`] does, resolved
106    /// through the same refusal mapping as [`Self::resolve_reader_checkout`].
107    /// Dropping the future abandons the wait without taking a permit.
108    pub(crate) async fn acquire_reader_admission(
109        &self,
110        capability: StorageCapability,
111        operation: &'static str,
112    ) -> Result<ReaderAdmission, StorageError> {
113        let context = khive_storage::capture_request_read_context();
114        let started = Instant::now();
115        let stopped = context.stop_reason().is_some();
116        let outcome: Result<Option<ReaderAdmission>, SqliteError> = if stopped {
117            Ok(None)
118        } else {
119            tokio::select! {
120                biased;
121                _ = context.wait_for_stop() => Ok(None),
122                waited = tokio::time::timeout(
123                    self.config.checkout_timeout,
124                    Arc::clone(&self.sql_bridge_reader_slots).acquire_owned(),
125                ) => match waited {
126                    Ok(Ok(slot)) => Ok(Some(ReaderAdmission { slot, started })),
127                    Ok(Err(_closed)) => Err(SqliteError::InvalidData(
128                        "reader admission semaphore is closed".to_string(),
129                    )),
130                    Err(_elapsed) => {
131                        self.reader_acquisition_counters.record_checkout_timeout();
132                        Err(pool_exhausted_error(
133                            self.config.checkout_timeout,
134                            self.max_readers,
135                        ))
136                    }
137                },
138            }
139        };
140        match outcome {
141            Ok(Some(admission)) => Ok(admission),
142            Ok(None) => Err(self.reader_checkout_refusal(capability, operation, None)),
143            Err(error) => Err(self.reader_checkout_refusal(capability, operation, Some(error))),
144        }
145    }
146
147    /// Select the reader connection for an admission permit already held.
148    ///
149    /// This is [`Self::reader_until`] after its permit loop: the same
150    /// `should_stop` polling, the same `Ok(Some)` / `Ok(None)` / `Err`
151    /// outcomes, and the remainder of the one `checkout_timeout` that began
152    /// when the permit wait did.
153    pub(crate) fn reader_with_admission<C>(
154        &self,
155        admission: ReaderAdmission,
156        should_stop: C,
157    ) -> Result<Option<ReaderGuard<'_>>, SqliteError>
158    where
159        C: Fn() -> bool,
160    {
161        let ReaderAdmission {
162            slot: admission_slot,
163            started,
164        } = admission;
165
166        if self.max_readers == 0 {
167            self.ensure_pooled_writer_active()?;
168            loop {
169                if should_stop() {
170                    return Ok(None);
171                }
172                let remaining = self
173                    .config
174                    .checkout_timeout
175                    .saturating_sub(started.elapsed());
176                if remaining.is_zero() {
177                    self.reader_acquisition_counters.record_checkout_timeout();
178                    return Err(pool_exhausted_error(
179                        self.config.checkout_timeout,
180                        self.max_readers,
181                    ));
182                }
183                if let Some(guard) = self
184                    .writer
185                    .try_lock_for(remaining.min(Duration::from_millis(2)))
186                {
187                    self.ensure_pooled_writer_active()?;
188                    self.reader_acquisition_counters.record_pooled_checkout();
189                    return Ok(Some(ReaderGuard {
190                        lease: Some(ReaderLease::Shared(guard)),
191                        admission_slot: Some(admission_slot),
192                        pool: self,
193                        reusable: Cell::new(true),
194                        query_in_progress: Cell::new(false),
195                        checked_out_at: self.begin_reader_checkout(),
196                        dirty: Cell::new(false),
197                        operation: None,
198                    }));
199                }
200            }
201        }
202
203        let mut attempt = 0u32;
204
205        loop {
206            if should_stop() {
207                return Ok(None);
208            }
209            if let Some(mut conn) = self.readers.pop() {
210                conn.checkouts = conn.checkouts.saturating_add(1);
211                self.reader_acquisition_counters.record_pooled_checkout();
212                return Ok(Some(ReaderGuard {
213                    lease: Some(ReaderLease::Pooled(conn)),
214                    admission_slot: Some(admission_slot),
215                    pool: self,
216                    reusable: Cell::new(true),
217                    query_in_progress: Cell::new(false),
218                    checked_out_at: self.begin_reader_checkout(),
219                    dirty: Cell::new(false),
220                    operation: None,
221                }));
222            }
223
224            if started.elapsed() >= self.config.checkout_timeout {
225                self.reader_acquisition_counters.record_checkout_timeout();
226                return Err(pool_exhausted_error(
227                    self.config.checkout_timeout,
228                    self.max_readers,
229                ));
230            }
231
232            match attempt {
233                0..=7 => {
234                    let spins = 1usize << attempt;
235                    for _ in 0..spins {
236                        std::hint::spin_loop();
237                    }
238                }
239                8..=15 => thread::yield_now(),
240                _ => {
241                    let remaining = self
242                        .config
243                        .checkout_timeout
244                        .saturating_sub(started.elapsed());
245                    let sleep = Duration::from_micros(50 * (1u64 << (attempt - 16).min(6)));
246                    thread::sleep(sleep.min(remaining).min(Duration::from_millis(2)));
247                }
248            }
249
250            attempt = attempt.saturating_add(1);
251        }
252    }
253
254    /// Check out the writer connection.
255    ///
256    /// Waits up to `checkout_timeout` for the writer Mutex and returns
257    /// `Err(SqliteError::WriterPoolCheckoutTimeout)` if the timeout is
258    /// exceeded.
259    ///
260    /// Checkout owns exclusion, not a capacity sample. Consume the returned
261    /// guard with [`WriterGuard::autocommit`] or [`WriterGuard::transaction`];
262    /// those operations sample at execution and retain ownership through
263    /// settlement. Raw connection access is crate-private.
264    #[track_caller]
265    pub fn writer(&self) -> Result<WriterGuard<'_>, SqliteError> {
266        self.writer_checkout(false)
267    }
268
269    /// Checkpoint ownership setup changes only SQLite's checkpoint policy.
270    /// Its bounded checkout must remain available below the write reserve.
271    pub(super) fn writer_for_checkpoint_operation(&self) -> Result<WriterGuard<'_>, SqliteError> {
272        self.writer_checkout(true)
273    }
274
275    #[track_caller]
276    fn writer_checkout(&self, checkpoint_bypass: bool) -> Result<WriterGuard<'_>, SqliteError> {
277        if !checkpoint_bypass {
278            self.write_admission.ensure_settled()?;
279        }
280        self.ensure_pooled_writer_active()?;
281        let volume_lease = if checkpoint_bypass {
282            None
283        } else {
284            self.write_admission
285                .acquire(crate::disk_guard::LeaseClass::Pooled)?
286        };
287        let Some(guard) = self.writer.try_lock_for(self.config.checkout_timeout) else {
288            self.writer_acquisition_counters
289                .pooled_timeouts
290                .fetch_add(1, Ordering::Relaxed);
291            let message = format!(
292                "timed out after {:?} waiting for sqlite writer connection",
293                self.config.checkout_timeout
294            );
295            crate::timeout_sink::emit_timeout(
296                &crate::timeout_sink::db_label(self),
297                crate::timeout_sink::Site::PoolAdmission,
298                &message,
299                Some(
300                    self.config
301                        .checkout_timeout
302                        .as_millis()
303                        .min(u128::from(u64::MAX)) as u64,
304                ),
305            );
306            return Err(SqliteError::WriterPoolCheckoutTimeout {
307                timeout: self.config.checkout_timeout,
308            });
309        };
310        self.ensure_pooled_writer_active()?;
311        #[cfg(any(unix, windows))]
312        if let Some(path) = self.identity_path.as_deref() {
313            self.verify_opened_file_identity(path)?;
314            self.verify_connection_file_identity(&guard, path)?;
315        }
316        self.writer_acquisition_counters
317            .pooled_acquisitions
318            .fetch_add(1, Ordering::Relaxed);
319        Ok(WriterGuard {
320            guard,
321            origin: self.origin(),
322            pool: self,
323            admission: self.write_admission.as_ref(),
324            _volume_lease: volume_lease,
325        })
326    }
327
328    /// Non-panicking writer checkout.
329    ///
330    /// Returns `Err` on timeout instead of panicking. Use this in request
331    /// handlers where a 500 is preferable to crashing the process.
332    #[track_caller]
333    pub fn try_writer(&self) -> Result<WriterGuard<'_>, SqliteError> {
334        self.writer()
335    }
336
337    #[track_caller]
338    pub(crate) fn writer_until_for_admitted_operation<C>(
339        &self,
340        should_stop: C,
341    ) -> Result<Option<WriterGuard<'_>>, SqliteError>
342    where
343        C: Fn() -> bool,
344    {
345        self.ensure_pooled_writer_active()?;
346        if should_stop() {
347            return Ok(None);
348        }
349        let volume_lease = self
350            .write_admission
351            .acquire(crate::disk_guard::LeaseClass::Pooled)?;
352        let started = Instant::now();
353        loop {
354            if should_stop() {
355                return Ok(None);
356            }
357            let remaining = self
358                .config
359                .checkout_timeout
360                .saturating_sub(started.elapsed());
361            if let Some(guard) = self
362                .writer
363                .try_lock_for(remaining.min(Duration::from_millis(2)))
364            {
365                // Cancellation may have arrived during the final wait slice.
366                // Once this guard is returned, constructor DDL is not interrupted.
367                if should_stop() {
368                    return Ok(None);
369                }
370                self.ensure_pooled_writer_active()?;
371                #[cfg(any(unix, windows))]
372                if let Some(path) = self.identity_path.as_deref() {
373                    self.verify_opened_file_identity(path)?;
374                    self.verify_connection_file_identity(&guard, path)?;
375                }
376                self.writer_acquisition_counters
377                    .pooled_acquisitions
378                    .fetch_add(1, Ordering::Relaxed);
379                return Ok(Some(WriterGuard {
380                    guard,
381                    origin: self.origin(),
382                    pool: self,
383                    admission: self.write_admission.as_ref(),
384                    _volume_lease: volume_lease,
385                }));
386            }
387            if started.elapsed() >= self.config.checkout_timeout {
388                self.writer_acquisition_counters
389                    .pooled_timeouts
390                    .fetch_add(1, Ordering::Relaxed);
391                let message = format!(
392                    "timed out after {:?} waiting for sqlite writer connection",
393                    self.config.checkout_timeout
394                );
395                crate::timeout_sink::emit_timeout(
396                    &crate::timeout_sink::db_label(self),
397                    crate::timeout_sink::Site::PoolAdmission,
398                    &message,
399                    Some(
400                        self.config
401                            .checkout_timeout
402                            .as_millis()
403                            .min(u128::from(u64::MAX)) as u64,
404                    ),
405                );
406                return Err(SqliteError::WriterPoolCheckoutTimeout {
407                    timeout: self.config.checkout_timeout,
408                });
409            }
410        }
411    }
412
413    /// Zero-wait checkpoint checkout for recovery maintenance.
414    ///
415    /// Uses `try_lock()` (no timeout, no spin) — returns `Err` immediately when
416    /// any other caller holds the writer Mutex. The scheduled checkpoint task
417    /// uses its own dedicated connection (ADR-091 Amendment 5); this optional
418    /// pooled capability remains available for zero-wait recovery callers.
419    ///
420    /// It bypasses the disk-reserve floor because checkpoints can recover WAL
421    /// space at or below that floor (ADR-154 §5). The returned guard exposes
422    /// only fixed PASSIVE and TRUNCATE checkpoint operations.
423    ///
424    /// The former unrestricted checkout must not return:
425    /// ```compile_fail
426    /// use khive_db::{ConnectionPool, PoolConfig};
427    /// let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
428    /// pool.try_writer_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");
429    /// ```
430    pub fn try_checkpoint_nowait(&self) -> Result<CheckpointGuard<'_>, SqliteError> {
431        self.ensure_pooled_writer_active()?;
432        let guard = self.writer.try_lock().ok_or_else(|| {
433            SqliteError::InvalidData(
434                "writer connection busy (checkpoint skipped this tick)".to_string(),
435            )
436        })?;
437        self.ensure_pooled_writer_active()?;
438        Ok(CheckpointGuard { guard })
439    }
440
441    pub(crate) fn retire_pooled_writer(&self, conn: &mut ProgressConn) {
442        self.pooled_writer_retired.store(true, Ordering::Release);
443        if let Err(error) = conn.with_mut(|conn| conn.authorizer(Some(deny_retired_writer))) {
444            tracing::error!(target: "khive_db::pool",
445                %error,
446                "failed to install the retired pooled-writer quarantine authorizer"
447            );
448        }
449    }
450
451    /// Exercise the retired connection's authorizer without exporting a raw
452    /// handle from the pool. This is intentionally unavailable in production.
453    #[cfg(test)]
454    pub(crate) fn probe_retired_pooled_writer_for_test(&self) -> rusqlite::Result<i64> {
455        self.writer
456            .lock()
457            .query_row("SELECT 1", [], |row| row.get(0))
458    }
459
460    /// Leave an inherited transaction on the bare pooled connection to test
461    /// the typed write-unit refusal. A normal WriterGuard rolls it back on
462    /// drop, so it cannot create this poisoned state.
463    #[cfg(test)]
464    pub(crate) fn leave_pooled_writer_transaction_open_for_test(&self) -> rusqlite::Result<()> {
465        self.writer.lock().execute_batch("BEGIN IMMEDIATE")
466    }
467
468    pub(super) fn ensure_pooled_writer_active(&self) -> Result<(), SqliteError> {
469        if self.pooled_writer_retired.load(Ordering::Acquire) {
470            return Err(SqliteError::InvalidData(
471                "pooled writer connection retired after a terminal transaction fault".to_string(),
472            ));
473        }
474        Ok(())
475    }
476}