Skip to main content

khive_db/timeout_sink/
lifecycle.rs

1//! Explicit, cancellation-resumable ownership of diagnostic writer threads.
2
3use std::collections::HashMap;
4use std::path::PathBuf;
5use std::sync::atomic::{AtomicU64, Ordering};
6use std::sync::{Arc, OnceLock};
7use std::thread::JoinHandle;
8use std::time::Duration;
9
10use parking_lot::Mutex;
11
12use super::{
13    heartbeat_interval_from_env, mpsc, thread, writer_thread_loop, SinkHandle, QUEUE_CAPACITY,
14};
15use crate::error::SqliteError;
16
17type SharedRegistry = Arc<Mutex<Registry>>;
18
19#[derive(Default)]
20struct Registry {
21    directories: HashMap<PathBuf, Arc<Entry>>,
22    routes: HashMap<String, Arc<SinkHandle>>,
23}
24
25struct Entry {
26    directory: PathBuf,
27    state: Mutex<State>,
28}
29
30struct State {
31    pools: usize,
32    writers: usize,
33    handle: Option<Arc<SinkHandle>>,
34    join: Option<JoinHandle<()>>,
35    result: Option<Result<(), TimeoutSinkCloseError>>,
36}
37
38static REGISTRY: OnceLock<SharedRegistry> = OnceLock::new();
39static ROUTING_DROPPED: AtomicU64 = AtomicU64::new(0);
40
41/// Failure to finish an explicitly enrolled diagnostic sink shutdown.
42#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
43pub enum TimeoutSinkCloseError {
44    /// Another pool or a writer task still owns the shared sink.
45    #[error("diagnostic sink is busy: {pools} live pools, {writers} writer tasks")]
46    Busy { pools: usize, writers: usize },
47    /// The writer exited by unwinding instead of draining normally.
48    #[error("diagnostic sink writer thread panicked")]
49    ThreadPanicked,
50}
51
52/// A retained completion witness for a pool's diagnostic sink.
53///
54/// Obtain this before releasing the pool. Clones share the same retained
55/// thread join and completion result; none of them keeps pool ownership alive.
56#[derive(Clone)]
57pub struct TimeoutSinkCloseHandle {
58    registry: SharedRegistry,
59    entry: Arc<Entry>,
60}
61
62impl TimeoutSinkCloseHandle {
63    /// Wait for the shared writer thread to drain its accepted queue, close
64    /// its file, and join. Live pools or writer tasks return
65    /// [`TimeoutSinkCloseError::Busy`]; retry after they settle.
66    /// Cancellation retains the join and Closing state, so
67    /// a clone can resume this operation. New pool registration is refused
68    /// while Closing. Ordinary pool Drop does not request this shutdown.
69    pub async fn close(&self) -> Result<(), TimeoutSinkCloseError> {
70        loop {
71            if let Some(result) = self.try_close() {
72                return result;
73            }
74            tokio::time::sleep(Duration::from_millis(2)).await;
75        }
76    }
77
78    fn try_close(&self) -> Option<Result<(), TimeoutSinkCloseError>> {
79        let mut registry = self.registry.lock();
80        let mut state = self.entry.state.lock();
81        if let Some(result) = &state.result {
82            return Some(result.clone());
83        }
84        if state.pools != 0 || state.writers != 0 {
85            return Some(Err(TimeoutSinkCloseError::Busy {
86                pools: state.pools,
87                writers: state.writers,
88            }));
89        }
90        if let Some(handle) = state.handle.take() {
91            registry
92                .routes
93                .retain(|_, route| !Arc::ptr_eq(route, &handle));
94            // Last sender closes admission. In-flight emit calls may still own
95            // a sender; the receiver drains them before its thread can finish.
96            drop(handle);
97        }
98        if !state.join.as_ref().is_some_and(JoinHandle::is_finished) {
99            return None;
100        }
101        // Never take a running join: cancellation cannot detach it. is_finished
102        // includes destruction of the thread's captured values and file owner.
103        let result = state
104            .join
105            .take()
106            .expect("unfinished sink retains its join")
107            .join()
108            .map_err(|_| TimeoutSinkCloseError::ThreadPanicked);
109        state.result = Some(result.clone());
110        registry.directories.remove(&self.entry.directory);
111        Some(result)
112    }
113}
114
115/// One writable pool's registration, retained until the pool's fields drop.
116/// Dropping it deliberately leaves the ordinary process-lifetime sink running.
117pub(crate) struct Registration {
118    registry: SharedRegistry,
119    entry: Arc<Entry>,
120}
121
122impl Registration {
123    pub(crate) fn close_handle(&self) -> TimeoutSinkCloseHandle {
124        TimeoutSinkCloseHandle {
125            registry: self.registry.clone(),
126            entry: self.entry.clone(),
127        }
128    }
129
130    pub(crate) fn writer_lease(&self) -> WriterLease {
131        self.entry.state.lock().writers += 1;
132        WriterLease {
133            _owner: Arc::new(WriterOwner(self.entry.clone())),
134        }
135    }
136}
137
138impl Drop for Registration {
139    fn drop(&mut self) {
140        self.entry.state.lock().pools -= 1;
141    }
142}
143
144/// Retained by the async writer and each native connection-owning child.
145#[derive(Clone)]
146pub(crate) struct WriterLease {
147    _owner: Arc<WriterOwner>,
148}
149
150struct WriterOwner(Arc<Entry>);
151
152impl Drop for WriterOwner {
153    fn drop(&mut self) {
154        self.0.state.lock().writers -= 1;
155    }
156}
157
158pub(super) fn init(dir: PathBuf, db: &str) -> Result<Option<Registration>, SqliteError> {
159    let registry = REGISTRY.get_or_init(|| Arc::new(Mutex::new(Registry::default())));
160    init_in(registry, dir, db)
161}
162
163fn init_in(
164    registry: &SharedRegistry,
165    dir: PathBuf,
166    db: &str,
167) -> Result<Option<Registration>, SqliteError> {
168    let mut guard = registry.lock();
169    let entry = if let Some(entry) = guard.directories.get(&dir) {
170        if entry.state.lock().handle.is_none() {
171            return Err(SqliteError::InvalidConfig(format!(
172                "diagnostic sink is closing for {}",
173                dir.display()
174            )));
175        }
176        entry.clone()
177    } else {
178        if guard.routes.contains_key(db) {
179            return Err(SqliteError::InvalidConfig(
180                "database diagnostic sink is already registered in another directory".into(),
181            ));
182        }
183        let (sender, receiver) = mpsc::sync_channel(QUEUE_CAPACITY);
184        let (go_sender, go_receiver) = mpsc::sync_channel(1);
185        let dropped = Arc::new(AtomicU64::new(0));
186        let thread_dropped = dropped.clone();
187        let thread_dir = dir.clone();
188        let identity = db.to_owned();
189        let heartbeat = heartbeat_interval_from_env();
190        let join = match thread::Builder::new()
191            .name("khive-writer-timeout-sink".into())
192            .spawn(move || {
193                writer_thread_loop(
194                    go_receiver,
195                    receiver,
196                    thread_dir,
197                    identity,
198                    thread_dropped,
199                    heartbeat,
200                )
201            }) {
202            Ok(join) => join,
203            // Preserve fail-open thread-allocation behavior; later opens retry.
204            Err(_) => return Ok(None),
205        };
206        let entry = Arc::new(Entry {
207            directory: dir.clone(),
208            state: Mutex::new(State {
209                pools: 0,
210                writers: 0,
211                handle: Some(Arc::new(SinkHandle { sender, dropped })),
212                join: Some(join),
213                result: None,
214            }),
215        });
216        guard.directories.insert(dir, entry.clone());
217        let _ = go_sender.send(());
218        entry
219    };
220    let mut state = entry.state.lock();
221    let handle = state.handle.as_ref().expect("registered sink is open");
222    if guard
223        .routes
224        .get(db)
225        .is_some_and(|route| !Arc::ptr_eq(route, handle))
226    {
227        return Err(SqliteError::InvalidConfig(
228            "database diagnostic sink is already registered in another directory".into(),
229        ));
230    }
231    guard.routes.insert(db.to_owned(), handle.clone());
232    state.pools += 1;
233    drop(state);
234    Ok(Some(Registration {
235        registry: registry.clone(),
236        entry,
237    }))
238}
239
240/// Producer routing never waits for initialization or shutdown registry locks.
241pub(super) fn route(db: &str) -> Option<Arc<SinkHandle>> {
242    let registry = REGISTRY.get()?;
243    route_in(registry, &ROUTING_DROPPED, db)
244}
245
246fn route_in(
247    registry: &SharedRegistry,
248    routing_dropped: &AtomicU64,
249    db: &str,
250) -> Option<Arc<SinkHandle>> {
251    let Some(guard) = registry.try_lock() else {
252        routing_dropped.fetch_add(1, Ordering::Relaxed);
253        return None;
254    };
255    let handle = guard.routes.get(db)?.clone();
256    handle.dropped.fetch_add(
257        routing_dropped.swap(0, Ordering::Relaxed),
258        Ordering::Relaxed,
259    );
260    Some(handle)
261}
262
263#[cfg(test)]
264#[path = "lifecycle_tests.rs"]
265mod tests;