summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:19:14 -0300
committerGabriel Schneider <[email protected]>2026-11-10 11:19:14 -0300
commit8d91ecf978b99a79e3ff237cda14daa3d666509f (patch)
treee0bd33a24916162f1cfa83d58760e0b4313ea3c7 /README.md
parent0b29354e1ddf6cf75ac4c426a00dd3435ace5069 (diff)
downloadcomputeranim-8d91ecf978b99a79e3ff237cda14daa3d666509f.tar.gz
computeranim-8d91ecf978b99a79e3ff237cda14daa3d666509f.zip
recorder: moments in batches, and the heap, the stack, variables, lines and mappings in each
A transaction a moment cost 10 µs and 1 KB before the moment's own data: the list's path copied each time. Moments now gather 256 to a transaction, each frozen by its own cursor so the list grows in place, and a thread's fields sit in the moment's map instead of two maps down: a small moment is 284 bytes and 1 µs, an instruction step with registers 780 bytes. A moment also folds alloc/free into the live heap, call/ret into each thread's stack, variable into the live variables (a local leaves with its call), line, and map/unmap, so a viewer reads any of them at any moment without replaying.
Diffstat (limited to 'README.md')
-rw-r--r--README.md31
1 files changed, 22 insertions, 9 deletions
diff --git a/README.md b/README.md
index 07b0571..dfc0fb1 100644
--- a/README.md
+++ b/README.md
@@ -38,18 +38,31 @@ is another, with the recorder at its far end.
## A recording
-An xitdb file: a history of immutable **moments**. A moment is the state
-then (registers per thread, every byte of memory seen so far, the strings
-defined), 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: 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.
+
+| `Moment` | from the events |
+| --- | --- |
+| `regs(tid)` | any event carrying `Regs` as its payload |
+| `read(addr, buf, known)` | `mem_write`: every byte seen so far, and which are known |
+| `heap()`, `allocation(addr)` | `alloc`, `free`: the live allocations |
+| `stack(tid)` | `call`, `ret`: the calls a thread is inside |
+| `variables()` | `variable`: the live named variables; a local goes with its call |
+| `line(tid)` | `line` |
+| `mappings()`, `mapping(addr)` | `map`, `unmap` |
+| `string(id)` | `string` |
+| `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. Measured (release, this
-machine): a moment costs about 10 µs and 1 KB before its own data; an
-instruction-level recording of `fib(12)`, 145 000 moments, is 245 MB at
-56 000 moments a second; events inside a moment cost their own bytes only.
+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.
## Depends on