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