Trait JobKind 

pub trait JobKind:
    Send
    + Sync
    + Sized
    + 'static {
    type Order: Clone + Debug + Send + Sync + 'static;
    type Report: Clone + Debug + Default + Send + Sync + 'static;

    const NAME: &'static str;
    const FINISHED_RETENTION: Duration = DEFAULT_FINISHED_RETENTION;
    const FINISHED_KEPT: usize = DEFAULT_FINISHED_KEPT;

    // Required methods
    fn key(order: &Self::Order) -> &str;
    fn run(
        &self,
        order: &Self::Order,
        progress: &Reporter<Self>,
    ) -> Result<(), String>;

    // Provided methods
    fn settle(
        &self,
        _order: &Self::Order,
        outcome: Result<(), String>,
        _progress: &Reporter<Self>,
    ) -> (JobState, Option<String>) { ... }
    fn shutdown_error(&self) -> String { ... }
    fn spawn_error(&self, err: &dyn Display) -> String { ... }
}

A kind of job. The only thing a new kind has to write.

The queue owns waiting, ordering, dedup, the worker, the retention and the instruments. The kind owns what the work is and — if it took something while it ran — what has to be given back when it ends.

Required Associated Constants

const NAME: &'static str

The kind’s short name. It is the job-id prefix (gc-7, purge-12, mirror-3), the jera lane’s job kind (gc), and the noun in every message this module writes — so an operator reading a stack dump or a FAILED job knows what it was without a lookup.

Provided Associated Constants

const FINISHED_RETENTION: Duration = DEFAULT_FINISHED_RETENTION

How long a finished job of this kind stays readable.

Overridable rather than a shared constant because the two queues holding the same number today is a coincidence and not a contract — a purge’s result is the more valuable of the two to still have when somebody looks back, and a kind that decides so should be able to say it here rather than by editing a number every kind shares.

const FINISHED_KEPT: usize = DEFAULT_FINISHED_KEPT

Finished jobs of this kind kept regardless of age.

Required Associated Types

type Order: Clone + Debug + Send + Sync + 'static

What was asked for, carried on the job so the worker can hand it back to JobKind::run minutes later.

The whole order and not just the subject: a purge’s remove_principal and expect_empty change what the job is, and a queue that kept them in a side map keyed by subject would be a second place the two could disagree — with the more destructive reading winning whenever they did.

type Report: Clone + Debug + Default + Send + Sync + 'static

What the job produced, in the kind’s own words: a gc’s bytes, a purge’s stores and gate, a mirror’s objects.

The queue never looks inside it. It starts at Default::default — which is why a job that never ran, or was refused, reports zeroes rather than nothing.

Required Methods

fn key(order: &Self::Order) -> &str

The subject, and therefore the dedup key and the status key.

A repository path for a gc or a mirror, an account for a purge. Both questions the queue answers are per subject — “is there already one for this” on enqueue, “how is mine going” on status — so this is the only key it keeps.

fn run( &self, order: &Self::Order, progress: &Reporter<Self>, ) -> Result<(), String>

Do the work. Runs on the lane’s blocking thread, outside the queue’s lock, inside a std::panic::catch_unwind.

Report through progress as you go rather than in the return value: a job of this sort runs for minutes with a console polling the whole time, and a return value can only be read once the work is over — which is precisely when nobody needs it any more.

Provided Methods

fn settle( &self, _order: &Self::Order, outcome: Result<(), String>, _progress: &Reporter<Self>, ) -> (JobState, Option<String>)

How the job settles — and the hook for anything that must come back.

Called on every path out of JobKind::run: after Ok, after Err, and after a caught panic. That is the whole reason it is the queue’s job and not the runner’s. A purge takes a total lockout on an account before it is even enqueued and something has to lift it; a runner that returned early, failed, or blew up would each be a different missed unlock, and “release it in the error path too” is a rule that holds until the next early return somebody adds.

The default is the whole story for a kind that took nothing: Ok is JobState::Done, Err is JobState::Failed carrying the reason.

fn shutdown_error(&self) -> String

What a job refused by a shutting-down queue says.

A shutting-down queue answers by name rather than accepting a job it will never run: a console button lit for ever is worse than a refusal that says why. Overridden by a kind whose caller has already paid something for the job — a purge’s caller is holding a lockout that nothing is now going to lift, and has to be told so.

fn spawn_error(&self, err: &dyn Display) -> String

What a job says when the kind’s lane could not be started (no runtime).

The queue cannot run anything without its lane, and a job that sits QUEUED for ever is a console button that never goes down. Said on the job itself.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl JobKind for Gc

const NAME: &'static str = "gc"

type Order = String

type Report = GcReport

impl JobKind for Mirror

const NAME: &'static str = "mirror"

type Order = MirrorOrder

type Report = MirrorReport

impl JobKind for Purge

const NAME: &'static str = "purge"

type Order = PurgeOrder

type Report = PurgeReport