summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:46:18 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:47:26 -0300
commit5f1f95098611b077bd7e0ca27283fa0e02d1adbc (patch)
tree59385d79fa57e94bbaa489fbef0b8c5abc88c500 /README.md
parent233d9cf30b178501e3194297434791b6de35eff2 (diff)
downloadcomputeranim-5f1f95098611b077bd7e0ca27283fa0e02d1adbc.tar.gz
computeranim-5f1f95098611b077bd7e0ca27283fa0e02d1adbc.zip
recorder: a moment is its events, state is at keyframes
Folding every event into persistent state at every moment cost 750 bytes a step and 2 KB a scattered 8-byte write: the tree's path copied each time. Now a moment stores its events alone, in a compact code (a flags byte, varints, time as a difference, registers as the ones that changed), and the state (threads, memory, heap, variables, mappings, strings) is written at a keyframe a batch, sharing with the one before. A reader replays at most a batch over a keyframe, and keeps four positions replayed, so playing forward reads one moment a step. Of a memory write the recorder keeps the spans that differ from what it holds, so a region read again costs what changed in it. It stops at max_bytes (1 GiB). A step with registers: 749 bytes to 57. fib(12) by instruction, 142 000 moments: 111 MB to 8 MB, 197 000 moments/s. bench-store measures the rest.
Diffstat (limited to 'README.md')
-rw-r--r--README.md39
1 files changed, 28 insertions, 11 deletions
diff --git a/README.md b/README.md
index dfc0fb1..ec54259 100644
--- a/README.md
+++ b/README.md
@@ -38,10 +38,12 @@ is another, with the recorder at its far end.
## A recording
-An xitdb file: a list of immutable **moments**. A moment is the state of
-the program then, sharing what did not change with the moment before, and
-the events that led to it. `Trace.moment(i)` is any of them, in any order:
-time travel is an index.
+An xitdb file, kept small. A **moment** stores only its events, encoded
+compactly (registers as the ones that changed since the thread's last). The
+program's **state** is stored at a keyframe every 256 moments, each sharing
+what did not change with the one before; the state at any moment is the
+keyframe before it with the moments since replayed over it. `Trace.moment(i)`
+is any of them, in any order: time travel is an index.
| `Moment` | from the events |
| --- | --- |
@@ -56,13 +58,28 @@ time travel is an index.
| `events()` | everything, as it came |
The recorder ends a moment at the kinds in `Recorder.cut` (by default a
-step, a breakpoint, a syscall's exit, a signal, a source line, a mark), so
-the cost of time travel is chosen per recording; moments are written 256 a
-transaction. Measured (release, this machine): a moment holding one small
-event is 284 bytes and about 1 µs (936 000 a second through the ring); an
-instruction-level recording of `fib(12)` under ptrace, 142 000 moments each
-with the registers, is 111 MB at 165 000 moments a second. Events inside a
-moment cost their own bytes only.
+step, a breakpoint, a syscall's exit, a signal, a source line, a mark). Of a
+memory write it keeps only the bytes that differ from what it already
+holds, so a backend that reads a region again pays for what changed in it.
+It stops with `error.RecordingFull` at `max_bytes` (1 GiB): a recording is
+meant to be megabytes.
+
+What a moment costs (`zig build bench-store`; release, this machine):
+
+| each moment | bytes | ns |
+| --- | --- | --- |
+| a mark | 29 | 560 |
+| a step with registers | 57 | 1100 |
+| ... and a word pushed on the stack | 75 | 960 |
+| a word written somewhere in 1 MiB of heap | 717 | 14700 |
+| 4 KiB written again, unchanged | 376 | 24000 |
+| 4 KiB of new bytes | 12078 | 584000 |
+
+An instruction-level recording of `fib(12)` under ptrace, 142 000 moments
+with registers and the stack, is 8 MB at 197 000 moments a second; reading
+it back is 178 000 moments a second in order, a millisecond to any one.
+Scattered writes and new bulk data are what cost: each chunk of 64 bytes
+that changed is written at the next keyframe with its path in the tree.
## Depends on