1use 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 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 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 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 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 #[track_caller]
265 pub fn writer(&self) -> Result<WriterGuard<'_>, SqliteError> {
266 self.writer_checkout(false)
267 }
268
269 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 #[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 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 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 #[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 #[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}