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, super::write_units::LogicalWriteOwner::Request)
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, super::write_units::LogicalWriteOwner::Checkpoint)
273    }
274
275    #[track_caller]
276    fn writer_checkout(
277        &self,
278        checkpoint_bypass: bool,
279        logical_owner: super::write_units::LogicalWriteOwner,
280    ) -> Result<WriterGuard<'_>, SqliteError> {
281        if !checkpoint_bypass {
282            self.write_admission.ensure_settled()?;
283        }
284        self.ensure_pooled_writer_active()?;
285        let volume_lease = if checkpoint_bypass {
286            None
287        } else {
288            self.write_admission
289                .acquire(crate::disk_guard::LeaseClass::Pooled)?
290        };
291        let Some(guard) = self.writer.try_lock_for(self.config.checkout_timeout) else {
292            self.writer_acquisition_counters
293                .pooled_timeouts
294                .fetch_add(1, Ordering::Relaxed);
295            let message = format!(
296                "timed out after {:?} waiting for sqlite writer connection",
297                self.config.checkout_timeout
298            );
299            crate::timeout_sink::emit_timeout(
300                &crate::timeout_sink::db_label(self),
301                crate::timeout_sink::Site::PoolAdmission,
302                &message,
303                Some(
304                    self.config
305                        .checkout_timeout
306                        .as_millis()
307                        .min(u128::from(u64::MAX)) as u64,
308                ),
309            );
310            return Err(SqliteError::WriterPoolCheckoutTimeout {
311                timeout: self.config.checkout_timeout,
312            });
313        };
314        self.ensure_pooled_writer_active()?;
315        #[cfg(any(unix, windows))]
316        if let Some(path) = self.identity_path.as_deref() {
317            self.verify_opened_file_identity(path)?;
318            self.verify_connection_file_identity(&guard, path)?;
319        }
320        self.writer_acquisition_counters
321            .pooled_acquisitions
322            .fetch_add(1, Ordering::Relaxed);
323        Ok(WriterGuard {
324            guard,
325            origin: self.origin(),
326            pool: self,
327            admission: self.write_admission.as_ref(),
328            logical_owner,
329            _volume_lease: volume_lease,
330        })
331    }
332
333    pub(super) fn writer_for_core_migration(&self) -> Result<WriterGuard<'_>, SqliteError> {
334        self.writer_checkout(false, super::write_units::LogicalWriteOwner::CoreMigration)
335    }
336
337    pub(crate) fn writer_for_schema(&self) -> Result<WriterGuard<'_>, SqliteError> {
338        self.writer_checkout(false, super::write_units::LogicalWriteOwner::Schema)
339    }
340
341    pub(crate) fn writer_for_attachment_cutover(&self) -> Result<WriterGuard<'_>, SqliteError> {
342        self.writer_checkout(
343            false,
344            super::write_units::LogicalWriteOwner::AttachmentCutover,
345        )
346    }
347
348    /// Non-panicking writer checkout.
349    ///
350    /// Returns `Err` on timeout instead of panicking. Use this in request
351    /// handlers where a 500 is preferable to crashing the process.
352    #[track_caller]
353    pub fn try_writer(&self) -> Result<WriterGuard<'_>, SqliteError> {
354        self.writer()
355    }
356
357    #[track_caller]
358    pub(crate) fn schema_writer_until_for_admitted_operation<C>(
359        &self,
360        should_stop: C,
361    ) -> Result<Option<WriterGuard<'_>>, SqliteError>
362    where
363        C: Fn() -> bool,
364    {
365        self.writer_until_for_owner(should_stop, super::write_units::LogicalWriteOwner::Schema)
366    }
367
368    #[cfg(test)]
369    pub(crate) fn writer_until_for_admitted_operation<C>(
370        &self,
371        should_stop: C,
372    ) -> Result<Option<WriterGuard<'_>>, SqliteError>
373    where
374        C: Fn() -> bool,
375    {
376        self.writer_until_for_owner(should_stop, super::write_units::LogicalWriteOwner::Request)
377    }
378
379    fn writer_until_for_owner<C>(
380        &self,
381        should_stop: C,
382        logical_owner: super::write_units::LogicalWriteOwner,
383    ) -> Result<Option<WriterGuard<'_>>, SqliteError>
384    where
385        C: Fn() -> bool,
386    {
387        self.ensure_pooled_writer_active()?;
388        if should_stop() {
389            return Ok(None);
390        }
391        let volume_lease = self
392            .write_admission
393            .acquire(crate::disk_guard::LeaseClass::Pooled)?;
394        let started = Instant::now();
395        loop {
396            if should_stop() {
397                return Ok(None);
398            }
399            let remaining = self
400                .config
401                .checkout_timeout
402                .saturating_sub(started.elapsed());
403            if let Some(guard) = self
404                .writer
405                .try_lock_for(remaining.min(Duration::from_millis(2)))
406            {
407                // Cancellation may have arrived during the final wait slice.
408                // Once this guard is returned, constructor DDL is not interrupted.
409                if should_stop() {
410                    return Ok(None);
411                }
412                self.ensure_pooled_writer_active()?;
413                #[cfg(any(unix, windows))]
414                if let Some(path) = self.identity_path.as_deref() {
415                    self.verify_opened_file_identity(path)?;
416                    self.verify_connection_file_identity(&guard, path)?;
417                }
418                self.writer_acquisition_counters
419                    .pooled_acquisitions
420                    .fetch_add(1, Ordering::Relaxed);
421                return Ok(Some(WriterGuard {
422                    guard,
423                    origin: self.origin(),
424                    pool: self,
425                    admission: self.write_admission.as_ref(),
426                    logical_owner,
427                    _volume_lease: volume_lease,
428                }));
429            }
430            if started.elapsed() >= self.config.checkout_timeout {
431                self.writer_acquisition_counters
432                    .pooled_timeouts
433                    .fetch_add(1, Ordering::Relaxed);
434                let message = format!(
435                    "timed out after {:?} waiting for sqlite writer connection",
436                    self.config.checkout_timeout
437                );
438                crate::timeout_sink::emit_timeout(
439                    &crate::timeout_sink::db_label(self),
440                    crate::timeout_sink::Site::PoolAdmission,
441                    &message,
442                    Some(
443                        self.config
444                            .checkout_timeout
445                            .as_millis()
446                            .min(u128::from(u64::MAX)) as u64,
447                    ),
448                );
449                return Err(SqliteError::WriterPoolCheckoutTimeout {
450                    timeout: self.config.checkout_timeout,
451                });
452            }
453        }
454    }
455
456    /// Zero-wait checkpoint checkout for recovery maintenance.
457    ///
458    /// Uses `try_lock()` (no timeout, no spin) — returns `Err` immediately when
459    /// any other caller holds the writer Mutex. The scheduled checkpoint task
460    /// uses its own dedicated connection (ADR-091 Amendment 5); this optional
461    /// pooled capability remains available for zero-wait recovery callers.
462    ///
463    /// It bypasses the disk-reserve floor because checkpoints can recover WAL
464    /// space at or below that floor (ADR-154 §5). The returned guard exposes
465    /// only fixed PASSIVE and TRUNCATE checkpoint operations.
466    ///
467    /// The former unrestricted checkout must not return:
468    /// ```compile_fail
469    /// use khive_db::{ConnectionPool, PoolConfig};
470    /// let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
471    /// pool.try_writer_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");
472    /// ```
473    pub fn try_checkpoint_nowait(&self) -> Result<CheckpointGuard<'_>, SqliteError> {
474        self.ensure_pooled_writer_active()?;
475        let guard = self.writer.try_lock().ok_or_else(|| {
476            SqliteError::InvalidData(
477                "writer connection busy (checkpoint skipped this tick)".to_string(),
478            )
479        })?;
480        self.ensure_pooled_writer_active()?;
481        Ok(CheckpointGuard { guard })
482    }
483
484    pub(crate) fn retire_pooled_writer(&self, conn: &mut ProgressConn) {
485        self.pooled_writer_retired.store(true, Ordering::Release);
486        if let Err(error) = conn.with_mut(|conn| conn.authorizer(Some(deny_retired_writer))) {
487            tracing::error!(target: "khive_db::pool",
488                %error,
489                "failed to install the retired pooled-writer quarantine authorizer"
490            );
491        }
492    }
493
494    /// Exercise the retired connection's authorizer without exporting a raw
495    /// handle from the pool. This is intentionally unavailable in production.
496    #[cfg(test)]
497    pub(crate) fn probe_retired_pooled_writer_for_test(&self) -> rusqlite::Result<i64> {
498        self.writer
499            .lock()
500            .query_row("SELECT 1", [], |row| row.get(0))
501    }
502
503    /// Leave an inherited transaction on the bare pooled connection to test
504    /// the typed write-unit refusal. A normal WriterGuard rolls it back on
505    /// drop, so it cannot create this poisoned state.
506    #[cfg(test)]
507    pub(crate) fn leave_pooled_writer_transaction_open_for_test(&self) -> rusqlite::Result<()> {
508        self.writer.lock().execute_batch("BEGIN IMMEDIATE")
509    }
510
511    pub(super) fn ensure_pooled_writer_active(&self) -> Result<(), SqliteError> {
512        if self.pooled_writer_retired.load(Ordering::Acquire) {
513            return Err(SqliteError::InvalidData(
514                "pooled writer connection retired after a terminal transaction fault".to_string(),
515            ));
516        }
517        Ok(())
518    }
519}