summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
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