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;