summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-daemon.md51
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/next-daemon.md b/docs/next-daemon.md
index dec02f87..5a4b939a 100644
--- a/docs/next-daemon.md
+++ b/docs/next-daemon.md
@@ -4547,3 +4547,54 @@ After it, the query pane's two:
`--window-clients`; the box soak, seed 7, ReleaseSafe at both ends, 21
min and six clients (late windows and a late terminal among them): no
rejoin, no differing check, no panic. All pass.
+
+## Architecture step 6 notes: the rollback and the digest through the journal
+
+The clean-room plan's step 6 (`.scratch/clean-room/architecture.md` 9.4)
+was the rollback copy and the join through the text journal, deleting what
+the journal made redundant. What landed, and what did not and why:
+
+- **A text is written in place in a replica's core too.** The journal made
+ a session's edit write its text and line index in place; a replica's
+ still made a whole new text and index at every key, so that its rollback
+ copy could pin the old ones. Now the copy keeps none of a text's bytes
+ (File.State's `content` and `line_starts` are `.journal`): the epoch
+ notes what each write into a text or an index that was there when the
+ copy was taken took out (`rollback.Epoch.wrote`), and putting the copy
+ back writes that back, the newest first (`unwrite`), before the saved
+ bytes go back. A write into a buffer the epoch made is not noted: the
+ copy put back frees that buffer, and the one it grew from was never
+ written after the move. The three things the architect's watermark had
+ to handle are the copy's already: the journal's arrays (its steps, its
+ `done`, its entries) are saved allocations, and an entry merged into, or
+ the redo entries a speculation dropped, are put-off frees.
+- **A digest takes a blob of 4 KiB and up by its length.** The blob words
+ (a big text hashed once, its word kept by its address) went at every
+ in-place edit, so every unit's digest after an edit hashed the whole text
+ again. A text's revision says what it holds; a smaller blob is hashed
+ whole. The join's hashing thread, which made the words of texts a session
+ had not digested yet, went with them. The wire's version is 20.
+- **What stays, and why.** `Epoch` and `Copy`'s walk: the core's state is
+ not the architecture's `Small` (pointer-free, one memcpy) but a graph of
+ allocations (panes, views, rows, registers, the journal's arrays); a
+ memcpy of the core struct brings none of what its pointers reach back,
+ and the epoch is what keeps every allocation of before the copy where it
+ was. They go when `Small` exists. memory.zig's pins: a join's writer
+ thread still sends a session's texts after the step that dumped it, and
+ a pinned text is copied on write meanwhile. The join's stream: "the texts
+ as they are now and the journal entries since R" would have the writer
+ read texts the loop writes in place, and the journal cannot say what
+ changed since a revision (typing merges into one entry over many
+ revisions, an entry carries none, an undo turns entries in place, the
+ ring drops old steps). So the byte walker stays too (the join's stream,
+ the closed panes, the `.dump` files of the build before): an image (the
+ dump's form) would be BLAKE3 of every text inside the joining step.
+- **Costs** (`zig build replicas -Doptimize=ReleaseFast`, 4 seeds x 120
+ inputs from each of 3 clients, at 30/80/207 ms; two runs of the build
+ before): a copy p99 83-140 us where it was 85-123; a rollback p99 1.17,
+ 1.76 and 2.23 ms where it was 1.12-1.20, 1.68-1.82 and 2.27-2.44 (the
+ 207 ms cell was past 2 ms before too). A join, in a Debug session with
+ the notes and a 1.1 MB file the session edited, ten clients one after
+ the other: 0.86-1.04 ms of the step (the first 2.9) where it was 5.0-6.0,
+ and a client's input step p50 0.32 ms where it was 2.46: a unit's digest
+ no longer hashes the edited file.