Module jobs 

What is running: one cancellable job with a body, which the whole system can see and which outlives the window that started it. Jobs: the long work the whole system can see.

Anything that can take longer than a breath is a job: it has a name, a subject, a progress a person can read, a way out and an outcome, and it belongs to the system, not to the window that started it. An app starts one with [start] and keeps the [Running] it gets back while its worker runs: the worker says what it is doing and how far it has got, checks whether the person stopped it and ends it exactly once. The record lives in a registry of the process, so closing the page, the panel or the window that started the work does not end it ([rows]).

One row per job (surface): its title, what it is doing now, a bar determinate when the total is known, a Stop where it can be stopped, a Show me that goes to the thing being worked on. A finished job keeps its row until it is read; a failed one states why and stands in crate::attention as well, since a failure is something a person has to decide about (crate::attention::publish).

let job = ui::jobs::start(
    ui::jobs::Spec::new("Installing LibreOffice")
        .subject(ui::jobs::Subject::new(store, "LibreOffice").opens("store/app/libreoffice"))
        .unit(ui::jobs::Unit::Bytes)
        .stoppable(|| worker.cancel()),
);
let worker_job = job.clone();
ui::background::Background::current().spawn("install", move || {
    for chunk in download() {
        if worker_job.is_stopped() { return worker_job.stopped(); }
        worker_job.progress(chunk.seen, 480_000_000);
    }
    worker_job.done("Installed LibreOffice");
});

The rule this module exists to keep: an app never improvises a progress story of its own. A spinner with no words, a percentage with no way out, a “working…” that dies with its window — all of those are this module seen from the wrong side.

Structs

Band

A jobs surface as a widget: it keeps its rows, rebuilds them when the registry moves, and reports what was pressed through its Presses.

Job

One job, as a surface reads it.

JobId

A job’s identity, unique for the life of the process.

Owner

Who is asking: an app’s identity, as the row carries it. A row always names the app as well as showing its icon.

Presses

A jobs surface’s state: the press sink its rows write to, and the registry revision it last drew.

Running

The handle a worker keeps: what it reports through, and how it hears that the person stopped it. Clones report on the same job.

Spec

What a job is when it starts.

Subject

What a job is about: the app that owns it, the thing it works on, and where pressing the row goes.

Summary

What the surface says about the whole registry at a glance.

Watch

A registered watcher; dropping it stops the wakes.

Enums

Outcome

How a job ended.

Press

What the person pressed on a jobs surface.

Progress

Where a job has got to, as its row reads it.

Unit

What a job counts: the unit its progress is read in.

Constants

CHORD

The chord that opens the Jobs surface, wherever the person is.

Functions

apply

What pressing one row’s control asks of the registry: stop, dismiss, or the subject “Show me” goes to.

band

A row per job that runs, and per job that ended and has not been read.

clear

Take every job and attention item away: a test’s clean slate, and what a session reset does.

dismiss

Read a finished job’s row: it leaves the surface, and so does the attention item a failure raised. Running jobs are not dismissed.

finished

The jobs that ended and have not been read, newest first.

is_active

Whether anything is running.

open

Ask for the Jobs surface: what CHORD and the bar’s activity pill do.

pane

The Jobs surface: every row, under the two headings that say which is which.

revision

Bumped by every change, so a surface can skip rebuilding rows that did not change.

rows

Every row the surface shows: what runs, then what ended unread.

running

The jobs running now, oldest first.

show

The subject of job id: what “Show me” opens.

start

Start a job described by spec; the returned handle is the worker’s.

stop

Ask the job id to stop. It ends as Outcome::Stopped when its worker notices; a job that cannot be stopped is left alone. Whether anything was asked of it.

summary

What the whole registry holds, at a glance.

take_opening

Whether the surface was asked for since the last call.

watch

Call wake whenever a job starts, reports or ends, until the returned guard drops: a surface that shows jobs redraws then, rather than on a timer.