Module progress 

Generic, near-zero-cost progress substrate.

A Progress handle is a cheap-to-clone (Arc-bump) counter that any long-running operation can drive without knowing how — or whether — the progress is rendered. The rendering half lives behind the Sink trait, which higher layers (the CLI) implement to paint a terminal line. Domain crates only ever see the handle.

Zero-overhead null path

The overwhelmingly common case is “no one is watching” (piped output, --output json, embedded library use). For that case a handle is built with Progress::null, whose sink slot is None. Every hot-path call (Progress::inc) then costs exactly one relaxed atomic add plus a single predicted-not-taken branch on the sink slot — no snapshot allocation, no syscall, and no virtual Sink::render dispatch. The vtable is only touched when a sink is actually installed via Progress::with_sink.

Throttling (redraw at most every N ticks) is deliberately not done here: Progress::inc always calls render when active, and the Sink decides whether to actually repaint. Keeping the decision in the renderer keeps inc branch-predictable and lets each sink pick its own cadence.

Structs

Progress

A cheap-to-clone progress handle.

ProgressSnapshot

A point-in-time view of a Progress handle, handed to Sink::render.

Traits

Sink

Renders progress snapshots. Implemented by the presentation layer (the CLI’s TerminalSink), never by domain crates.