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, super::write_units::LogicalWriteOwner::Request)
267 }
268
269 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 #[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 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 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 #[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 #[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}