Expand description
ProgressTask<R> - distributed work with live cross-process
progress visibility.
Composes SharedAtomicU64 (the progress
counter), SharedAtomicU64 (the total /
denominator), SharedAtomicBool (the
done flag), and SharedCell<R> (the result
payload). The work closure receives a ProgressReporter handle
that increments the progress counter as it proceeds; any OTHER
process or thread can call fraction_complete / current_progress
/ is_done / read_result at O(1) atomic cost without blocking
or polling a result queue.
§Why this exists
Long-running jobs (ETL pipelines, batch processing, big builds) benefit from out-of-band progress visibility: a separate dashboard / CLI / supervisor wants to know “47% done, ETA 3min” without drilling into the worker’s log file or waiting on a result ring. Naive approaches use a separate progress channel, a counter file that the worker overwrites, or a stat-on-tempfile heuristic. With ProgressTask, the counter is one atomic load away in shared memory; updates are sub-nanosecond.
§Four files per task
<base>.progress.bin- SharedAtomicU64, monotonically advancing<base>.total.bin- SharedAtomicU64, the denominator<base>.done.bin- SharedAtomicBool, set true on completion<base>.result.bin-SharedCell<R>, written once at completion
Pass the BASE PATH (without extension) to create / open; the
wrapper appends the extensions.
§Composition with the scheduler
ProgressTask is INDEPENDENT of BackgroundScheduler; it works
standalone via run / spawn. To integrate with the scheduler,
a Pass closure can ProgressTask::open(base) to obtain a handle
and call begin(total) to get a reporter. The worker side only
needs the base path; the observer side only needs open + the
read APIs.
Structs§
- Progress
Reporter - Cross-process reporter handle passed to the work closure. Each
call to
advanceis a single atomic fetch_add (Relaxed ordering; progress is observational, not a synchronization point). - Progress
Task