Trait Job

Source

pub trait Job:
    Send
    + Sync
    + 'static {
    const NAME: &'static str;

    // Required methods
    fn payload(&self) -> Json;
    fn from_payload(payload: &Json) -> Result<Self>
       where Self: Sized;
    fn handle(&self) -> impl Future<Output = Result<()>> + Send;

    // Provided methods
    fn handle_with(
        &self,
        ctx: &JobContext,
    ) -> impl Future<Output = Result<()>> + Send { ... }
    fn tries(&self) -> u32 { ... }
    fn retry_after(&self) -> Duration { ... }
    fn queue(&self) -> &'static str { ... }
    fn to_queued(&self) -> QueuedJob { ... }
}

Expand description

A unit of work that can be stored and run later.

Deliberately not dyn-compatible: NAME and from_payload have no receiver, and handle returns an opaque future. Nothing needs a dyn Job, because the moment a job is queued it becomes a QueuedJob — plain data — and the way back to a type is the JobRegistry.

Required Associated Constants§

Source

const NAME: &'static str

The stable name this job is stored under.

It travels into the database and back out again, possibly across a deploy, so renaming it strands every job already queued. Choose it the way you would choose a table name.

Required Methods§

Source

fn payload(&self) -> Json

Everything from_payload needs to rebuild this job.

Source

fn from_payload(payload: &Json) -> Result<Self>
where Self: Sized,

Rebuild the job from a payload the queue handed back.

Returning an error here fails the job rather than panicking the worker, which is what you want when an old payload meets new code.

Source

fn handle(&self) -> impl Future<Output = Result<()>> + Send

Do the work.

Declared as -> impl Future + Send rather than async fn because the registry boxes the future and sends it to another task, and an async fn in a trait promises nothing about Send. An implementation is free to write async fn handle(&self) -> Result<()> instead: the compiler can see the body, so it can prove the Send this demands.

Provided Methods§

Source

fn handle_with( &self, ctx: &JobContext, ) -> impl Future<Output = Result<()>> + Send

Do the work, with somewhere to say how far along it is.

The default calls Job::handle and reports nothing, so a job that takes a second need not care. A job that takes a minute overrides this and calls ctx.progress(percent, "stage") as it goes; a request handler in the web process reads it back from the same store.

Source