Skip to main content

coven/
handle_writes.rs

1//! Writes: the app's SQL and coven's steps as one write, and the app bytes
2//! staged before one (§4, §17.2, E3).
3use crate::coven_write::CovenWrite;
4use crate::*;
5
6impl CovenHandle {
7    /// Runs one write: the app's SQL and coven's steps, in one transaction.
8    /// It fails with the closure's own error type, which keeps a failed
9    /// rollback or byte removal beside the write's failure
10    /// (`WriteFailure`).
11    pub async fn write<F, R, E>(&self, write: F) -> Result<R, E>
12    where
13        F: FnOnce(CovenWrite<'_>) -> Result<R, E> + Send + 'static,
14        R: Send + 'static,
15        E: WriteFailure + Send + 'static,
16    {
17        let (steps, files) = (self.steps.clone(), self.files.clone());
18        self.database.write_as(move |sql| write(CovenWrite::new(sql, &steps, &files))).await
19    }
20
21    /// Runs one bulk write: SQL that changes device-local tables alone, run
22    /// as plain SQLite with no record of each row change, so emptying a table
23    /// takes one step and filling one runs at SQLite's own speed (§4). A
24    /// statement that would write a synced table, itself or through a
25    /// trigger or foreign-key action, fails the write with
26    /// `SyncedTableInBulkWrite`. Triggers still run, and so does the app's
27    /// before-commit function, after the closure (§9.4). After commit, every
28    /// live query that read a table the write's statements or the function's
29    /// may change runs again, whatever rows it read; a small change that
30    /// should rerun only the live queries reading its rows belongs in
31    /// `write`.
32    pub async fn write_bulk<F, R, E>(&self, sql: F) -> Result<R, E>
33    where
34        F: FnOnce(BulkSqlContext<'_>) -> Result<R, E> + Send + 'static,
35        R: Send + 'static,
36        E: WriteFailure + Send + 'static,
37    {
38        self.database.write_bulk(sql).await
39    }
40
41    /// Stages app bytes for a write that puts them in rows (§17.2): `stage`
42    /// stages each file and returns what that write needs, such as the ids
43    /// staging gave them, and the write takes it with
44    /// `CovenWrite::put_staged`. The bytes are streamed to coven's own copies,
45    /// synced and flushed before this returns; close waits for staging and
46    /// its cleanup, including cancellation. The staged files hold nothing
47    /// close waits for: dropped uncommitted, or after the store closes, they
48    /// are removed by the next write or open. An undeclared namespace fails
49    /// with `UndeclaredNamespace`, a user one with `NamespaceKind`.
50    pub async fn stage_files<F, T, E>(&self, stage: F) -> Result<StagedFiles<T>, E>
51    where
52        F: FnOnce(&mut WriteBatch<'_>) -> Result<T, E> + Send + 'static,
53        T: Send + 'static,
54        E: WriteFailure + Send + 'static,
55    {
56        self.database.stage_files(stage).await
57    }
58}
59
60#[cfg(test)]
61impl CovenHandle {
62    /// Stage app bytes, then run a write that puts them in its rows, as an
63    /// app does with `stage_files` and `put_staged`, for tests.
64    pub(crate) async fn test_staged_write<F, S, T, R, E>(&self, stage: F, write: S) -> Result<R, E>
65    where
66        F: FnOnce(&mut WriteBatch<'_>) -> Result<T, E> + Send + 'static,
67        S: FnOnce(CovenWrite<'_>, T) -> Result<R, E> + Send + 'static,
68        T: Send + 'static,
69        R: Send + 'static,
70        E: WriteFailure + Send + 'static,
71    {
72        let staged = self.stage_files(stage).await?;
73        self.write(move |sql| {
74            let value = sql.put_staged(staged)?;
75            write(sql, value)
76        })
77        .await
78    }
79}
80
81#[cfg(test)]
82#[path = "handle_writes_tests.rs"]
83mod tests;