Skip to main content

day_persistence/
worker.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! Queue-confined persistence. Neither model handles nor reactive signals cross the queue.
5use crate::{Checkpoint, DbError, DbErrorKind, ModelContainer};
6use std::{
7    future::Future,
8    panic::{AssertUnwindSafe, catch_unwind},
9    pin::Pin,
10    sync::{
11        Arc, Mutex,
12        atomic::{AtomicBool, Ordering},
13        mpsc::{self, SyncSender},
14    },
15    task::{Context, Poll},
16};
17
18type Job = Box<dyn FnOnce(&mut Session) -> Result<(), DbError> + Send>;
19struct Session {
20    db: ModelContainer,
21    revision: u64,
22    undo: Option<day_model::UndoStack>,
23    needs_publish: bool,
24    observers: Vec<Box<dyn Observation>>,
25}
26trait Observation {
27    fn refresh(&mut self, db: &ModelContainer, revision: u64) -> Result<bool, DbError>;
28}
29impl Session {
30    fn publish(&mut self) -> Result<(), DbError> {
31        if !std::mem::take(&mut self.needs_publish) {
32            return Ok(());
33        }
34        let mut error = None;
35        self.observers.retain_mut(|o| {
36            if error.is_some() {
37                return true;
38            }
39            match o.refresh(&self.db, self.revision) {
40                Ok(keep) => keep,
41                Err(e) => {
42                    error = Some(e);
43                    true
44                }
45            }
46        });
47        error.map_or(Ok(()), Err)
48    }
49}
50
51/// A committed value and the worker-local transaction revision it represents.
52#[derive(Clone, Debug, PartialEq)]
53pub struct WorkerSnapshot<T> {
54    pub revision: u64,
55    pub value: T,
56}
57struct Latest<T> {
58    value: Option<Result<WorkerSnapshot<T>, DbError>>,
59    closed: bool,
60    waker: Option<std::task::Waker>,
61}
62/// A bounded, latest-value subscription. Slow consumers receive the newest committed result,
63/// not an unbounded queue of intermediate refreshes. Drop to unsubscribe. Values are compared
64/// on the worker, so unchanged results do not wake the UI. This is not a transaction event log.
65pub struct WorkerSubscription<T> {
66    slot: Arc<Mutex<Latest<T>>>,
67}
68impl<T> WorkerSubscription<T> {
69    /// Await the next changed snapshot; `None` after the worker closes. Cancelling this await
70    /// is safe: it does not consume a value until it returns Ready.
71    pub async fn next(&mut self) -> Option<Result<WorkerSnapshot<T>, DbError>> {
72        std::future::poll_fn(|cx| {
73            let mut slot = lock(&self.slot);
74            if let Some(value) = slot.value.take() {
75                return Poll::Ready(Some(value));
76            }
77            if slot.closed {
78                return Poll::Ready(None);
79            }
80            slot.waker = Some(cx.waker().clone());
81            Poll::Pending
82        })
83        .await
84    }
85}
86struct Projection<T, F> {
87    slot: std::sync::Weak<Mutex<Latest<T>>>,
88    project: F,
89    previous: Option<T>,
90}
91impl<T, F> Drop for Projection<T, F> {
92    fn drop(&mut self) {
93        if let Some(slot) = self.slot.upgrade() {
94            let waker = {
95                let mut slot = lock(&slot);
96                slot.closed = true;
97                slot.waker.take()
98            };
99            if let Some(waker) = waker {
100                waker.wake();
101            }
102        }
103    }
104}
105impl<T: Clone + PartialEq + Send + 'static, F: Fn(&ModelContainer) -> Result<T, DbError>>
106    Observation for Projection<T, F>
107{
108    fn refresh(&mut self, db: &ModelContainer, revision: u64) -> Result<bool, DbError> {
109        let Some(slot) = self.slot.upgrade() else {
110            return Ok(false);
111        };
112        let value = match db.worker_read(|db| (self.project)(db)) {
113            Ok(value) if self.previous.as_ref() == Some(&value) => return Ok(true),
114            Ok(value) => {
115                self.previous = Some(value.clone());
116                Ok(WorkerSnapshot { revision, value })
117            }
118            Err(error) => {
119                self.previous = None;
120                Err(error)
121            }
122        };
123        let fatal = value
124            .as_ref()
125            .err()
126            .filter(|e| matches!(e.kind, DbErrorKind::Closed | DbErrorKind::Panicked))
127            .cloned();
128        let waker = {
129            let mut slot = lock(&slot);
130            slot.value = Some(value);
131            slot.waker.take()
132        };
133        if let Some(waker) = waker {
134            waker.wake();
135        }
136        fatal.map_or(Ok(true), Err)
137    }
138}
139#[derive(Clone, Debug)]
140pub struct WorkerOptions {
141    /// Maximum accepted requests waiting behind the running operation. Admission never blocks.
142    pub capacity: usize,
143    pub name: String,
144}
145impl Default for WorkerOptions {
146    fn default() -> Self {
147        Self {
148            capacity: 256,
149            name: "day-persistence".into(),
150        }
151    }
152}
153struct Control {
154    sender: Option<SyncSender<Job>>,
155    finished: bool,
156    error: Option<DbError>,
157    waiters: Vec<day_async::Deliver<Result<(), DbError>>>,
158    thread: Option<std::thread::ThreadId>,
159}
160/// An explicitly asynchronous database queue. Construct the container in `open`'s factory:
161/// its connection, caches, model handles and query observers stay on this worker until close.
162/// Only owned `Send` arguments and results cross threads. Clones share FIFO admission order.
163/// Do not return model `Store`/`Elem` handles or signals: their cross-thread facilities do not
164/// make them independent of this queue's connection and lifetime. Return model values/IDs.
165///
166/// A container cannot accidentally escape through an owned result:
167/// ```compile_fail
168/// use day_persistence::{DatabaseWorker, ModelContainer};
169/// fn escape(worker: &DatabaseWorker) {
170///     let request = worker.read(|db| Ok(db.clone()));
171/// }
172/// ```
173#[derive(Clone)]
174pub struct DatabaseWorker {
175    control: Arc<Mutex<Control>>,
176}
177
178/// An eagerly submitted operation. Dropping a read cancels it if it has not started. Dropping
179/// a write's result never cancels an accepted transaction: await it to learn commit success.
180#[must_use = "await the request to observe completion and persistence errors"]
181pub struct WorkerRequest<R> {
182    receiver: day_async::Oneshot<Result<R, DbError>>,
183    cancelled: Arc<AtomicBool>,
184    cancel_on_drop: bool,
185}
186impl<R> Future for WorkerRequest<R> {
187    type Output = Result<R, DbError>;
188    fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
189        Pin::new(&mut self.receiver)
190            .poll(cx)
191            .map(|r| r.unwrap_or_else(|_| Err(closed())))
192    }
193}
194impl<R> Drop for WorkerRequest<R> {
195    fn drop(&mut self) {
196        if self.cancel_on_drop {
197            self.cancelled.store(true, Ordering::Release);
198        }
199    }
200}
201// A refresh error is a durable commit, including for undo/redo and reset operations.
202fn committed<T>(result: &Result<T, DbError>) -> bool {
203    result.is_ok()
204        || result
205            .as_ref()
206            .err()
207            .is_some_and(|e| e.kind == DbErrorKind::CommittedRefreshFailed)
208}
209fn closed() -> DbError {
210    DbError::new(DbErrorKind::Closed, "database worker is closed")
211}
212fn lock<T>(value: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
213    value
214        .lock()
215        .unwrap_or_else(std::sync::PoisonError::into_inner)
216}
217impl DatabaseWorker {
218    /// Open/migrate on the owning queue, without blocking the caller's executor. The factory
219    /// may create non-Send drivers, schema hooks and model state because it runs on the worker.
220    ///
221    /// # Errors
222    /// Returns the factory's error, or an error when the worker thread cannot start.
223    pub async fn open(
224        factory: impl FnOnce() -> Result<ModelContainer, DbError> + Send + 'static,
225    ) -> Result<Self, DbError> {
226        Self::open_with(WorkerOptions::default(), factory).await
227    }
228
229    /// [`DatabaseWorker::open`], with a queue capacity and thread name.
230    ///
231    /// # Errors
232    /// Returns a `Busy` error for a zero capacity, the factory's error, or an error when the worker
233    /// thread cannot start.
234    pub async fn open_with(
235        options: WorkerOptions,
236        factory: impl FnOnce() -> Result<ModelContainer, DbError> + Send + 'static,
237    ) -> Result<Self, DbError> {
238        if options.capacity == 0 {
239            return Err(DbError::new(
240                DbErrorKind::Busy,
241                "worker capacity must be positive",
242            ));
243        }
244        let (sender, receiver) = mpsc::sync_channel::<Job>(options.capacity);
245        let control = Arc::new(Mutex::new(Control {
246            sender: Some(sender),
247            finished: false,
248            error: None,
249            waiters: Vec::new(),
250            thread: None,
251        }));
252        let weak = Arc::downgrade(&control);
253        let (ready, opened) = day_async::oneshot();
254        std::thread::Builder::new()
255            .name(options.name)
256            .spawn(move || {
257                if let Some(control) = weak.upgrade() {
258                    lock(&control).thread = Some(std::thread::current().id());
259                }
260                let result = catch_unwind(AssertUnwindSafe(|| {
261                    let scope = day_reactive::Scope::detached();
262                    let result = scope.enter(|| {
263                        let container = match factory() {
264                            Ok(container) => container,
265                            Err(error) => {
266                                ready.send(Err(error.clone()));
267                                return Err(error);
268                            }
269                        };
270                        ready.send(Ok(()));
271                        // The thread holds no sender or strong worker reference. Dropping the last
272                        // client drains accepted work, then closes the connection on this thread.
273                        let mut session = Session {
274                            db: container,
275                            revision: 0,
276                            undo: None,
277                            needs_publish: false,
278                            observers: Vec::new(),
279                        };
280                        let result = catch_unwind(AssertUnwindSafe(|| {
281                            while let Ok(job) = receiver.recv() {
282                                job(&mut session)?;
283                                // Bound projection work during bursts without starving observers.
284                                for _ in 1..32 {
285                                    match receiver.try_recv() {
286                                        Ok(job) => job(&mut session)?,
287                                        Err(_) => break,
288                                    }
289                                }
290                                session.publish()?;
291                            }
292                            session.db.save()
293                        }))
294                        .unwrap_or_else(|_| {
295                            Err(DbError::new(
296                                DbErrorKind::Panicked,
297                                "database worker panicked",
298                            ))
299                        });
300                        session.observers.clear();
301                        session.undo.take();
302                        session.db.worker_dispose_caches();
303                        result
304                    });
305                    scope.dispose();
306                    result
307                }))
308                .unwrap_or_else(|_| {
309                    Err(DbError::new(
310                        DbErrorKind::Panicked,
311                        "database worker panicked",
312                    ))
313                });
314                if let Some(control) = weak.upgrade() {
315                    let waiters = {
316                        let mut state = lock(&control);
317                        state.sender.take();
318                        state.finished = true;
319                        state.error = result.as_ref().err().cloned();
320                        std::mem::take(&mut state.waiters)
321                    };
322                    for waiter in waiters {
323                        waiter.send(result.clone());
324                    }
325                }
326            })
327            .map_err(|e| DbError::driver(e.to_string()))?;
328        opened.await.map_err(|_| {
329            DbError::new(DbErrorKind::Panicked, "database worker failed during open")
330        })??;
331        Ok(Self { control })
332    }
333
334    /// Execute a read on the queue. Query-only mode and dirty-cache checks reject accidental
335    /// writes; SQL reads and row materialization never run on the caller's thread.
336    pub fn read<R: Send + 'static>(
337        &self,
338        read: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
339    ) -> WorkerRequest<R> {
340        self.submit(true, move |session| session.db.worker_read(read))
341    }
342
343    /// Execute one atomic transaction, then acknowledge its durable commit. Intermediate saves
344    /// and read-your-writes stay within the transaction. A failed operation restores the cache.
345    /// Accepted writes survive dropping this future. Admission failure means nothing ran.
346    pub fn write<R: Send + 'static>(
347        &self,
348        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
349    ) -> WorkerRequest<R> {
350        self.write_with_origin(crate::WriteOrigin::Local, write)
351    }
352
353    /// A transactional import or maintenance operation. Remote imports persist normally;
354    /// participants use the origin to suppress outbound echo, not the database writes.
355    pub fn write_with_origin<R: Send + 'static>(
356        &self,
357        origin: crate::WriteOrigin,
358        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
359    ) -> WorkerRequest<R> {
360        self.submit(false, move |session| {
361            let checkpoint = session.undo.as_ref().map(day_model::UndoStack::checkpoint);
362            let group = session.undo.as_ref().map(|undo| undo.begin_group("edit"));
363            let result = session.db.worker_write_origin(origin, write);
364            drop(group); // Seal even when no UI observer caused a reactive turn-end drain.
365            if committed(&result) {
366                session.revision += 1;
367                session.needs_publish = true;
368            } else if let (Some(undo), Some(checkpoint)) = (&session.undo, checkpoint) {
369                undo.restore_checkpoint(checkpoint);
370            }
371            result
372        })
373    }
374
375    /// Commit a wholesale replacement and discard obsolete undo/redo history only on success.
376    /// Both actions run on the owning queue, so no edit can interleave between them. A failed
377    /// replacement restores the previous history and rolls back the database transaction.
378    pub fn write_resetting_undo<R: Send + 'static>(
379        &self,
380        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
381    ) -> WorkerRequest<R> {
382        self.submit(false, move |session| {
383            let checkpoint = session.undo.as_ref().map(day_model::UndoStack::checkpoint);
384            let result = session
385                .db
386                .worker_write(|db| day_model::with_author("reset", || write(db)));
387            if committed(&result) {
388                if let Some(undo) = &session.undo {
389                    undo.clear();
390                }
391                session.revision += 1;
392                session.needs_publish = true;
393            } else if let (Some(undo), Some(checkpoint)) = (&session.undo, checkpoint) {
394                undo.restore_checkpoint(checkpoint);
395            }
396            result
397        })
398    }
399
400    /// Install one queue-confined history. Call once before editing. Background imports should
401    /// use `day_model::with_author` inside `write` so they do not enter user undo history.
402    pub fn enable_undo(&self, levels: usize) -> WorkerRequest<()> {
403        self.submit(false, move |session| {
404            if session.undo.is_some() {
405                return Err(DbError::driver("worker undo already installed"));
406            }
407            session.undo = Some(session.db.undo(levels));
408            Ok(())
409        })
410    }
411
412    /// Owned availability for a UI's native undo bridge; no reactive handles cross queues.
413    pub fn undo_status(&self) -> WorkerRequest<(bool, bool)> {
414        self.submit(true, |session| {
415            Ok(session
416                .undo
417                .as_ref()
418                .map_or_default(|u| (u.can_undo().get_untracked(), u.can_redo().get_untracked())))
419        })
420    }
421
422    /// Replay and commit atomically on the owning queue. A failed commit restores the history.
423    pub fn undo(&self, redo: bool) -> WorkerRequest<bool> {
424        self.submit(false, move |session| {
425            let Some(undo) = &session.undo else {
426                return Ok(false);
427            };
428            let checkpoint = undo.checkpoint();
429            let result = session
430                .db
431                .worker_write(|_| Ok(if redo { undo.redo() } else { undo.undo() }));
432            if committed(&result) {
433                session.revision += 1;
434                session.needs_publish = true;
435            } else {
436                undo.restore_checkpoint(checkpoint);
437            }
438            result
439        })
440    }
441
442    /// Observe an owned projection after committed writes. The projection must be read-only;
443    /// it runs on the database queue. Registration participates in FIFO admission, so the first
444    /// result includes all writes accepted before it. Subsequent results may coalesce revisions.
445    ///
446    /// # Errors
447    /// Returns an error when the worker has closed or stopped before the registration ran.
448    pub async fn observe<T: Clone + PartialEq + Send + 'static>(
449        &self,
450        project: impl Fn(&ModelContainer) -> Result<T, DbError> + Send + 'static,
451    ) -> Result<WorkerSubscription<T>, DbError> {
452        let slot = Arc::new(Mutex::new(Latest {
453            value: None,
454            closed: false,
455            waker: None,
456        }));
457        let projection = Projection {
458            slot: Arc::downgrade(&slot),
459            project,
460            previous: None,
461        };
462        self.submit(true, move |session| {
463            session.observers.push(Box::new(projection));
464            session.needs_publish = true;
465            Ok(())
466        })
467        .await?;
468        Ok(WorkerSubscription { slot })
469    }
470
471    /// Create a consistent SQLite backup after all earlier accepted work. Backup runs outside
472    /// an explicit transaction because SQLite's VACUUM INTO requires autocommit mode. The
473    /// driver supplies the snapshot guarantee. The destination must not already exist.
474    pub fn backup_to(&self, path: impl Into<std::path::PathBuf>) -> WorkerRequest<()> {
475        let path = path.into();
476        self.submit(true, move |session| session.db.backup_to(&path))
477    }
478
479    /// Checkpoint the write-ahead log after all earlier accepted work, outside any transaction
480    /// (a checkpoint cannot complete inside one). With `checkpoint_fullfsync` on, this is the
481    /// one point where a replication engine forces committed journal entries through the
482    /// drive cache before it publishes them.
483    pub fn checkpoint(&self) -> WorkerRequest<Checkpoint> {
484        self.submit(true, |session| session.db.checkpoint())
485    }
486
487    /// Explicitly merge writes from another connection on this queue, then refresh projections.
488    /// Applications using one worker as the sole writer do not need polling.
489    pub fn check_external(&self) -> WorkerRequest<bool> {
490        self.submit(true, |session| {
491            let changed = session.db.check_external()?;
492            if changed {
493                session.revision += 1;
494                session.needs_publish = true;
495            }
496            Ok(changed)
497        })
498    }
499
500    fn submit<R: Send + 'static>(
501        &self,
502        read: bool,
503        operation: impl FnOnce(&mut Session) -> Result<R, DbError> + Send + 'static,
504    ) -> WorkerRequest<R> {
505        let (deliver, receiver) = day_async::oneshot();
506        let cancelled = Arc::new(AtomicBool::new(false));
507        let cancel = cancelled.clone();
508        // Keep the completion in a shared slot so rejected jobs can deliver a precise error.
509        let completion = Arc::new(Mutex::new(Some(deliver)));
510        let done = completion.clone();
511        let job: Job = Box::new(move |db| {
512            let result = if read && cancel.load(Ordering::Acquire) {
513                Err(DbError::new(
514                    DbErrorKind::Cancelled,
515                    "database read cancelled before execution",
516                ))
517            } else {
518                catch_unwind(AssertUnwindSafe(|| operation(db))).unwrap_or_else(|_| {
519                    Err(DbError::new(
520                        DbErrorKind::Panicked,
521                        "database operation panicked",
522                    ))
523                })
524            };
525            let fatal = result
526                .as_ref()
527                .err()
528                .filter(|e| matches!(e.kind, DbErrorKind::Panicked | DbErrorKind::Closed))
529                .cloned();
530            let deliver = lock(&done).take();
531            if let Some(deliver) = deliver {
532                deliver.send(result);
533            }
534            fatal.map_or(Ok(()), Err)
535        });
536        let mut rejected_job = None;
537        let rejected = {
538            let state = lock(&self.control);
539            if state.thread == Some(std::thread::current().id()) {
540                Some(DbError::driver(
541                    "a database worker cannot submit work to its own queue",
542                ))
543            } else {
544                match &state.sender {
545                    None => Some(state.error.clone().unwrap_or_else(closed)),
546                    Some(sender) => match sender.try_send(job) {
547                        Ok(()) => None,
548                        Err(mpsc::TrySendError::Full(job)) => {
549                            rejected_job = Some(job);
550                            Some(DbError::new(
551                                DbErrorKind::Busy,
552                                "database worker queue is full",
553                            ))
554                        }
555                        Err(mpsc::TrySendError::Disconnected(job)) => {
556                            rejected_job = Some(job);
557                            Some(closed())
558                        }
559                    },
560                }
561            }
562        };
563        // Captures may run arbitrary Drop code (including another submission). Never drop
564        // a rejected closure while holding the queue's admission lock.
565        drop(rejected_job);
566        if let Some(error) = rejected {
567            let deliver = lock(&completion).take();
568            if let Some(deliver) = deliver {
569                deliver.send(Err(error));
570            }
571        }
572        WorkerRequest {
573            receiver,
574            cancelled,
575            cancel_on_drop: read,
576        }
577    }
578
579    /// Last-chance synchronous shutdown for an OS termination callback that cannot await.
580    /// Normal application code should use `close().await`. This waits for every accepted
581    /// operation and may take as long as the longest transaction. Never call it while holding
582    /// a lock a submitted operation needs. Calling it from this worker is rejected.
583    ///
584    /// # Errors
585    /// Returns the error the worker stopped with, or a driver error when called from the worker
586    /// itself.
587    pub fn close_blocking(&self) -> Result<(), DbError> {
588        struct Unpark(std::thread::Thread);
589        impl std::task::Wake for Unpark {
590            fn wake(self: Arc<Self>) {
591                self.0.unpark();
592            }
593        }
594        let waker = std::task::Waker::from(Arc::new(Unpark(std::thread::current())));
595        let mut context = Context::from_waker(&waker);
596        let mut close = std::pin::pin!(self.close());
597        loop {
598            match close.as_mut().poll(&mut context) {
599                Poll::Ready(result) => return result,
600                Poll::Pending => std::thread::park(),
601            }
602        }
603    }
604
605    /// Stop admission for every clone, drain accepted writes, and close on the owning queue.
606    /// No join or disk flush blocks the caller. Repeated close calls share completion.
607    ///
608    /// # Errors
609    /// Returns the error the worker stopped with, or a driver error when called from the worker
610    /// itself.
611    pub async fn close(&self) -> Result<(), DbError> {
612        let (deliver, receiver) = day_async::oneshot();
613        {
614            let mut state = lock(&self.control);
615            if state.thread == Some(std::thread::current().id()) {
616                return Err(DbError::driver(
617                    "a database worker cannot wait for its own close",
618                ));
619            }
620            state.sender.take();
621            if state.finished {
622                return state.error.clone().map_or(Ok(()), Err);
623            }
624            state.waiters.push(deliver);
625        }
626        receiver.await.map_err(|_| closed())?
627    }
628}