Skip to content
PITO MDdocs

pito-jobs

A terminal: the demo example starts three jobs that write their records while a reader draws them once a second: an encode moves through probe, encode and mux and a render through build, trace and encode, each with a bar, a count and a rate, until both finish with a check mark, and a fetch stops halfway with its error, connection reset by peer.

pito-jobs is a small Rust crate that lets a command-line tool or an app say what it is doing, so another program can show it live: a render’s stage and frame count, an encode’s rate, an app’s frame times. It is part of PITO MD, where every tool writes through it and a monitor reads it back.

  • 26.5 ns to record a frame in an app’s heartbeat: no lock, no allocation, 0.00016% of a 16.7 ms frame at 60 fps.
  • 292 ns a progress call, safe to make every frame or every item: the file is rewritten at most once a second, atomically, and stays under 4 KiB (a typical record is 454 bytes).
  • Never in the way: a write error never fails, blocks or slows the tool. A job starts no thread; a heartbeat keeps one low-priority thread.
  • Small: three dependencies (serde, serde_json and, on unix, libc), and the crate itself compiles in 1.1 s.

How these are measured is in Measure the cost.

Three forms

Section titled “Three forms”

All three are JSON, all are written best-effort, and all are specified in Formats:

  • A job record: one file per running job, with its stage, progress, rate, device, output and how it ended. See Report a job’s progress and Read jobs back.
  • An app heartbeat: one file per running app with its fps, frame times (p50, p95, p99, max), GPU time and missed frames. See Publish an app heartbeat.
  • Progress lines: the --progress json lines an op prints on stdout, one object per line, with a writer and a tolerant reader. See Stream progress lines.

The files live in RAM where the OS offers it ($XDG_RUNTIME_DIR is cleared at logout), and nothing is kept as history: a reader that wants history keeps its own.

Where to go next

Section titled “Where to go next”