summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 12:09:27 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:15:20 -0300
commita7504c6bb2ec9e906891e42bc3df28b276e67143 (patch)
treec13e680499badf341b17960341386b8199637671 /README.md
parent937b6314c4cd6fa73daeac308fbfcf69b89add56 (diff)
downloadcomputeranim-a7504c6bb2ec9e906891e42bc3df28b276e67143.tar.gz
computeranim-a7504c6bb2ec9e906891e42bc3df28b276e67143.zip
the backends together: a ring under the debugger, strings that do not collide
ztrace record and dbg take --ring, --preload and --alloc: the target gets the ring ztrace run gives it, and the debugger drains it while the target runs (polling for the stop, so a full ring cannot hold both) and before it reports a stop. A program compiled by ztrace cc, with the agent preloaded, stopped at breakpoints, is one recording in order; test-together checks it. Recording such a program showed the debugger's file names and the pass's strings both counted from 1: event.stringId (a hash, top bit set) is now what every producer without a table of its own uses.
Diffstat (limited to 'README.md')
-rw-r--r--README.md24
1 files changed, 24 insertions, 0 deletions
diff --git a/README.md b/README.md
index 8ce505d..9f94bab 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,30 @@ 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.
+## Together
+
+The backends are not modes to choose between: they feed one sink. A
+program compiled by `ztrace cc`, with the agent preloaded, run under the
+debugger, gives one recording, in order: the stops and their registers
+(ptrace), the allocations (the agent), the lines, calls, stores and named
+variables (the pass).
+
+```sh
+ztrace cc -- clang -O0 targets/instr_list.c -o list
+ztrace record --by break -b push -b reverse --alloc --preload zig-out/lib/libztrace-agent.so -- ./list
+ztrace dbg --ring -- ./list # breakpoints and time travel over what the program says of itself
+ztrace show out.ztrace 40 # the thread's line and calls, the live heap, each variable's bytes
+zig build test-together
+```
+
+`--ring` (implied by `--preload` and `--alloc`) gives a target under
+ptrace the ring `ztrace run` gives it; the debugger drains it while the
+target runs and before it reports a stop. The agent's hooks and syscall
+tracing are signals, which a debugger takes first: under ptrace, use
+breakpoints and the debugger's own syscall stops. Strings never collide:
+the pass counts its from 1, a symbol's name has its address as its id, and
+every other producer uses `event.stringId`, a hash with the top bit set.
+
## The debugger
`ztrace dbg -- PROGRAM` starts a program stopped and reads commands (from a