2.8 KiB
Debugging and devx: tractor.devx
Multi-process debugging that actually works: boot the tree with open_root_actor(debug_mode=True) (or pass it to open_nursery()) and any crash or explicit pause in any actor acquires a tree-global TTY lock and drops you into a pdbp-powered REPL — one actor at a time, SIGINT shielded, no garbled terminals. The top-level helpers below are the daily drivers; the rest of the toolbox lives under tractor.devx.
tractor
Pausing and post-mortems
pause
pause_from_sync
Note
pause_from_sync needs the greenback portal: boot with open_root_actor(maybe_enable_greenback=True) (mind the performance implications). With debug_mode on, the built-in breakpoint() is also remapped to a tractor-safe equivalent.
post_mortem
0.1.0a6
tractor.breakpoint() warns and simply calls pause — use tractor.pause (async) or tractor.pause_from_sync in new code.
Crash handling for CLIs and sync entrypoints
tractor.devx
open_crash_handler
maybe_open_crash_handler
Note
Both are sync context managers usable before (or without) trio.run() — wrap your CLI main() to get a post-mortem REPL on any uncaught exception instead of a bare traceback.
Runtime hang-hunting
enable_stack_on_sig
With stackscope integration enabled (also via open_root_actor(enable_stack_on_sig=True) or the TRACTOR_ENABLE_STACKSCOPE env var) a SIGUSR1 triggers a full trio task-tree dump from every actor — works on live, non-debug-mode trees too:
pkill --signal SIGUSR1 -f <part-of-your-cmd>Dumps also tee to /tmp/tractor-stackscope-<pid>.log so you still get output under captured/CI stdio.
Lower-level debug plumbing
mk_pdb
maybe_wait_for_debugger
maybe_wait_for_debugger is mainly useful in runtime/test code that must avoid tearing down a tree while a child still holds the global debug lock.
/api/errors for the boxed error types you'll inspect from the REPL, /api/core for the debug_mode / maybe_enable_greenback / enable_stack_on_sig boot flags on tractor.open_root_actor, and /guide/debugging for the guided multi-actor REPL tour.