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.lock().unwrap_or_else(|e| e.into_inner())
214}
215impl DatabaseWorker {
216    /// Open/migrate on the owning queue, without blocking the caller's executor. The factory
217    /// may create non-Send drivers, schema hooks and model state because it runs on the worker.
218    pub async fn open(
219        factory: impl FnOnce() -> Result<ModelContainer, DbError> + Send + 'static,
220    ) -> Result<Self, DbError> {
221        Self::open_with(WorkerOptions::default(), factory).await
222    }
223
224    pub async fn open_with(
225        options: WorkerOptions,
226        factory: impl FnOnce() -> Result<ModelContainer, DbError> + Send + 'static,
227    ) -> Result<Self, DbError> {
228        if options.capacity == 0 {
229            return Err(DbError::new(
230                DbErrorKind::Busy,
231                "worker capacity must be positive",
232            ));
233        }
234        let (sender, receiver) = mpsc::sync_channel::<Job>(options.capacity);
235        let control = Arc::new(Mutex::new(Control {
236            sender: Some(sender),
237            finished: false,
238            error: None,
239            waiters: Vec::new(),
240            thread: None,
241        }));
242        let weak = Arc::downgrade(&control);
243        let (ready, opened) = day_async::oneshot();
244        std::thread::Builder::new()
245            .name(options.name)
246            .spawn(move || {
247                if let Some(control) = weak.upgrade() {
248                    lock(&control).thread = Some(std::thread::current().id());
249                }
250                let result = catch_unwind(AssertUnwindSafe(|| {
251                    let scope = day_reactive::Scope::detached();
252                    let result = scope.enter(|| {
253                        let container = match factory() {
254                            Ok(container) => container,
255                            Err(error) => {
256                                ready.send(Err(error.clone()));
257                                return Err(error);
258                            }
259                        };
260                        ready.send(Ok(()));
261                        // The thread holds no sender or strong worker reference. Dropping the last
262                        // client drains accepted work, then closes the connection on this thread.
263                        let mut session = Session {
264                            db: container,
265                            revision: 0,
266                            undo: None,
267                            needs_publish: false,
268                            observers: Vec::new(),
269                        };
270                        let result = catch_unwind(AssertUnwindSafe(|| {
271                            while let Ok(job) = receiver.recv() {
272                                job(&mut session)?;
273                                // Bound projection work during bursts without starving observers.
274                                for _ in 1..32 {
275                                    match receiver.try_recv() {
276                                        Ok(job) => job(&mut session)?,
277                                        Err(_) => break,
278                                    }
279                                }
280                                session.publish()?;
281                            }
282                            session.db.save()
283                        }))
284                        .unwrap_or_else(|_| {
285                            Err(DbError::new(
286                                DbErrorKind::Panicked,
287                                "database worker panicked",
288                            ))
289                        });
290                        session.observers.clear();
291                        session.undo.take();
292                        session.db.worker_dispose_caches();
293                        result
294                    });
295                    scope.dispose();
296                    result
297                }))
298                .unwrap_or_else(|_| {
299                    Err(DbError::new(
300                        DbErrorKind::Panicked,
301                        "database worker panicked",
302                    ))
303                });
304                if let Some(control) = weak.upgrade() {
305                    let waiters = {
306                        let mut state = lock(&control);
307                        state.sender.take();
308                        state.finished = true;
309                        state.error = result.as_ref().err().cloned();
310                        std::mem::take(&mut state.waiters)
311                    };
312                    for waiter in waiters {
313                        waiter.send(result.clone());
314                    }
315                }
316            })
317            .map_err(|e| DbError::driver(e.to_string()))?;
318        opened.await.map_err(|_| {
319            DbError::new(DbErrorKind::Panicked, "database worker failed during open")
320        })??;
321        Ok(Self { control })
322    }
323
324    /// Execute a read on the queue. Query-only mode and dirty-cache checks reject accidental
325    /// writes; SQL reads and row materialization never run on the caller's thread.
326    pub fn read<R: Send + 'static>(
327        &self,
328        read: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
329    ) -> WorkerRequest<R> {
330        self.submit(true, move |session| session.db.worker_read(read))
331    }
332
333    /// Execute one atomic transaction, then acknowledge its durable commit. Intermediate saves
334    /// and read-your-writes stay within the transaction. A failed operation restores the cache.
335    /// Accepted writes survive dropping this future. Admission failure means nothing ran.
336    pub fn write<R: Send + 'static>(
337        &self,
338        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
339    ) -> WorkerRequest<R> {
340        self.write_with_origin(crate::WriteOrigin::Local, write)
341    }
342
343    /// A transactional import or maintenance operation. Remote imports persist normally;
344    /// participants use the origin to suppress outbound echo, not the database writes.
345    pub fn write_with_origin<R: Send + 'static>(
346        &self,
347        origin: crate::WriteOrigin,
348        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
349    ) -> WorkerRequest<R> {
350        self.submit(false, move |session| {
351            let checkpoint = session.undo.as_ref().map(|undo| undo.checkpoint());
352            let group = session.undo.as_ref().map(|undo| undo.begin_group("edit"));
353            let result = session.db.worker_write_origin(origin, write);
354            drop(group); // Seal even when no UI observer caused a reactive turn-end drain.
355            if committed(&result) {
356                session.revision += 1;
357                session.needs_publish = true;
358            } else if let (Some(undo), Some(checkpoint)) = (&session.undo, checkpoint) {
359                undo.restore_checkpoint(checkpoint);
360            }
361            result
362        })
363    }
364
365    /// Commit a wholesale replacement and discard obsolete undo/redo history only on success.
366    /// Both actions run on the owning queue, so no edit can interleave between them. A failed
367    /// replacement restores the previous history and rolls back the database transaction.
368    pub fn write_resetting_undo<R: Send + 'static>(
369        &self,
370        write: impl FnOnce(&ModelContainer) -> Result<R, DbError> + Send + 'static,
371    ) -> WorkerRequest<R> {
372        self.submit(false, move |session| {
373            let checkpoint = session.undo.as_ref().map(|undo| undo.checkpoint());
374            let result = session
375                .db
376                .worker_write(|db| day_model::with_author("reset", || write(db)));
377            if committed(&result) {
378                if let Some(undo) = &session.undo {
379                    undo.clear();
380                }
381                session.revision += 1;
382                session.needs_publish = true;
383            } else if let (Some(undo), Some(checkpoint)) = (&session.undo, checkpoint) {
384                undo.restore_checkpoint(checkpoint);
385            }
386            result
387        })
388    }
389
390    /// Install one queue-confined history. Call once before editing. Background imports should
391    /// use `day_model::with_author` inside `write` so they do not enter user undo history.
392    pub fn enable_undo(&self, levels: usize) -> WorkerRequest<()> {
393        self.submit(false, move |session| {
394            if session.undo.is_some() {
395                return Err(DbError::driver("worker undo already installed"));
396            }
397            session.undo = Some(session.db.undo(levels));
398            Ok(())
399        })
400    }
401
402    /// Owned availability for a UI's native undo bridge; no reactive handles cross queues.
403    pub fn undo_status(&self) -> WorkerRequest<(bool, bool)> {
404        self.submit(true, |session| {
405            Ok(session
406                .undo
407                .as_ref()
408                .map(|u| (u.can_undo().get_untracked(), u.can_redo().get_untracked()))
409                .unwrap_or_default())
410        })
411    }
412
413    /// Replay and commit atomically on the owning queue. A failed commit restores the history.
414    pub fn undo(&self, redo: bool) -> WorkerRequest<bool> {
415        self.submit(false, move |session| {
416            let Some(undo) = &session.undo else {
417                return Ok(false);
418            };
419            let checkpoint = undo.checkpoint();
420            let result = session
421                .db
422                .worker_write(|_| Ok(if redo { undo.redo() } else { undo.undo() }));
423            if committed(&result) {
424                session.revision += 1;
425                session.needs_publish = true;
426            } else {
427                undo.restore_checkpoint(checkpoint);
428            }
429            result
430        })
431    }
432
433    /// Observe an owned projection after committed writes. The projection must be read-only;
434    /// it runs on the database queue. Registration participates in FIFO admission, so the first
435    /// result includes all writes accepted before it. Subsequent results may coalesce revisions.
436    pub async fn observe<T: Clone + PartialEq + Send + 'static>(
437        &self,
438        project: impl Fn(&ModelContainer) -> Result<T, DbError> + Send + 'static,
439    ) -> Result<WorkerSubscription<T>, DbError> {
440        let slot = Arc::new(Mutex::new(Latest {
441            value: None,
442            closed: false,
443            waker: None,
444        }));
445        let projection = Projection {
446            slot: Arc::downgrade(&slot),
447            project,
448            previous: None,
449        };
450        self.submit(true, move |session| {
451            session.observers.push(Box::new(projection));
452            session.needs_publish = true;
453            Ok(())
454        })
455        .await?;
456        Ok(WorkerSubscription { slot })
457    }
458
459    /// Create a consistent SQLite backup after all earlier accepted work. Backup runs outside
460    /// an explicit transaction because SQLite's VACUUM INTO requires autocommit mode. The
461    /// driver supplies the snapshot guarantee. The destination must not already exist.
462    pub fn backup_to(&self, path: impl Into<std::path::PathBuf>) -> WorkerRequest<()> {
463        let path = path.into();
464        self.submit(true, move |session| session.db.backup_to(&path))
465    }
466
467    /// Checkpoint the write-ahead log after all earlier accepted work, outside any transaction
468    /// (a checkpoint cannot complete inside one). With `checkpoint_fullfsync` on, this is the
469    /// one point where a replication engine forces committed journal entries through the
470    /// drive cache before it publishes them.
471    pub fn checkpoint(&self) -> WorkerRequest<Checkpoint> {
472        self.submit(true, |session| session.db.checkpoint())
473    }
474
475    /// Explicitly merge writes from another connection on this queue, then refresh projections.
476    /// Applications using one worker as the sole writer do not need polling.
477    pub fn check_external(&self) -> WorkerRequest<bool> {
478        self.submit(true, |session| {
479            let changed = session.db.check_external()?;
480            if changed {
481                session.revision += 1;
482                session.needs_publish = true;
483            }
484            Ok(changed)
485        })
486    }
487
488    fn submit<R: Send + 'static>(
489        &self,
490        read: bool,
491        operation: impl FnOnce(&mut Session) -> Result<R, DbError> + Send + 'static,
492    ) -> WorkerRequest<R> {
493        let (deliver, receiver) = day_async::oneshot();
494        let cancelled = Arc::new(AtomicBool::new(false));
495        let cancel = cancelled.clone();
496        // Keep the completion in a shared slot so rejected jobs can deliver a precise error.
497        let completion = Arc::new(Mutex::new(Some(deliver)));
498        let done = completion.clone();
499        let job: Job = Box::new(move |db| {
500            let result = if read && cancel.load(Ordering::Acquire) {
501                Err(DbError::new(
502                    DbErrorKind::Cancelled,
503                    "database read cancelled before execution",
504                ))
505            } else {
506                catch_unwind(AssertUnwindSafe(|| operation(db))).unwrap_or_else(|_| {
507                    Err(DbError::new(
508                        DbErrorKind::Panicked,
509                        "database operation panicked",
510                    ))
511                })
512            };
513            let fatal = result
514                .as_ref()
515                .err()
516                .filter(|e| matches!(e.kind, DbErrorKind::Panicked | DbErrorKind::Closed))
517                .cloned();
518            let deliver = lock(&done).take();
519            if let Some(deliver) = deliver {
520                deliver.send(result);
521            }
522            fatal.map_or(Ok(()), Err)
523        });
524        let mut rejected_job = None;
525        let rejected = {
526            let state = lock(&self.control);
527            if state.thread == Some(std::thread::current().id()) {
528                Some(DbError::driver(
529                    "a database worker cannot submit work to its own queue",
530                ))
531            } else {
532                match &state.sender {
533                    None => Some(state.error.clone().unwrap_or_else(closed)),
534                    Some(sender) => match sender.try_send(job) {
535                        Ok(()) => None,
536                        Err(mpsc::TrySendError::Full(job)) => {
537                            rejected_job = Some(job);
538                            Some(DbError::new(
539                                DbErrorKind::Busy,
540                                "database worker queue is full",
541                            ))
542                        }
543                        Err(mpsc::TrySendError::Disconnected(job)) => {
544                            rejected_job = Some(job);
545                            Some(closed())
546                        }
547                    },
548                }
549            }
550        };
551        // Captures may run arbitrary Drop code (including another submission). Never drop
552        // a rejected closure while holding the queue's admission lock.
553        drop(rejected_job);
554        if let Some(error) = rejected {
555            let deliver = lock(&completion).take();
556            if let Some(deliver) = deliver {
557                deliver.send(Err(error));
558            }
559        }
560        WorkerRequest {
561            receiver,
562            cancelled,
563            cancel_on_drop: read,
564        }
565    }
566
567    /// Last-chance synchronous shutdown for an OS termination callback that cannot await.
568    /// Normal application code should use `close().await`. This waits for every accepted
569    /// operation and may take as long as the longest transaction. Never call it while holding
570    /// a lock a submitted operation needs. Calling it from this worker is rejected.
571    pub fn close_blocking(&self) -> Result<(), DbError> {
572        struct Unpark(std::thread::Thread);
573        impl std::task::Wake for Unpark {
574            fn wake(self: Arc<Self>) {
575                self.0.unpark();
576            }
577        }
578        let waker = std::task::Waker::from(Arc::new(Unpark(std::thread::current())));
579        let mut context = Context::from_waker(&waker);
580        let mut close = std::pin::pin!(self.close());
581        loop {
582            match close.as_mut().poll(&mut context) {
583                Poll::Ready(result) => return result,
584                Poll::Pending => std::thread::park(),
585            }
586        }
587    }
588
589    /// Stop admission for every clone, drain accepted writes, and close on the owning queue.
590    /// No join or disk flush blocks the caller. Repeated close calls share completion.
591    pub async fn close(&self) -> Result<(), DbError> {
592        let (deliver, receiver) = day_async::oneshot();
593        {
594            let mut state = lock(&self.control);
595            if state.thread == Some(std::thread::current().id()) {
596                return Err(DbError::driver(
597                    "a database worker cannot wait for its own close",
598                ));
599            }
600            state.sender.take();
601            if state.finished {
602                return state.error.clone().map_or(Ok(()), Err);
603            }
604            state.waiters.push(deliver);
605        }
606        receiver.await.map_err(|_| closed())?
607    }
608}