Trait background_jobs::Job

source ·

pub trait Job: Serialize + DeserializeOwned + 'static {
    type State: Clone + 'static;
    type Error: Into<BoxError>;
    type Future: Future<Output = Result<(), Self::Error>> + Send;

    const NAME: &'static str;
    const QUEUE: &'static str = "default";
    const MAX_RETRIES: MaxRetries = _;
    const BACKOFF: Backoff = _;
    const HEARTBEAT_INTERVAL: u64 = 5_000u64;

    // Required method
    fn run(self, state: Self::State) -> Self::Future;

    // Provided methods
    fn span(&self) -> Option<Span> { ... }
    fn queue(&self) -> &str { ... }
    fn max_retries(&self) -> MaxRetries { ... }
    fn backoff_strategy(&self) -> Backoff { ... }
    fn heartbeat_interval(&self) -> u64 { ... }
}

Expand description

The Job trait defines parameters pertaining to an instance of background job

Jobs are defnitions of work to be executed.

The simplest implementation defines the job’s State and Future types, NAME contant, and run method.

§Example

use background_jobs_core::{Job, new_job, BoxError};
use tracing::info;
use std::future::{ready, Ready};

#[derive(serde::Deserialize, serde::Serialize)]
struct MyJob {
    count: i64,
}

impl Job for MyJob {
    type State = ();
    type Error = BoxError;
    type Future = Ready<Result<(), BoxError>>;

    const NAME: &'static str = "MyJob";

    fn run(self, _: Self::State) -> Self::Future {
        info!("Processing {}", self.count);

        ready(Ok(()))
    }
}

fn main() -> Result<(), BoxError> {
    let job = new_job(MyJob { count: 1234 })?;

    Ok(())
}

Required Associated Types§

source

type State: Clone + 'static

The application state provided to this job at runtime.

source

type Future: Future<Output = Result<(), Self::Error>> + Send

The future returned by this job

Required Associated Constants§

source

const NAME: &'static str

The name of the job

This name must be unique!!!

Provided Associated Constants§

source

const QUEUE: &'static str = "default"

The name of the default queue for this job

This can be overridden on an individual-job level, but if a non-existant queue is supplied, the job will never be processed.

source

const MAX_RETRIES: MaxRetries = _

Define the default number of retries for this job

Defaults to Count(5) Jobs can override

source

const BACKOFF: Backoff = _

Define the default backoff strategy for this job

Defaults to Exponential(2) Jobs can override

source

const HEARTBEAT_INTERVAL: u64 = 5_000u64

Define how often a job should update its heartbeat timestamp

This is important for allowing the job server to reap processes that were started but never completed.

Defaults to 5 seconds Jobs can override

Required Methods§

source

fn run(self, state: Self::State) -> Self::Future

Users of this library must define what it means to run a job.

This should contain all the logic needed to complete a job. If that means queuing more jobs, sending an email, shelling out (don’t shell out), or doing otherwise lengthy processes, that logic should all be called from inside this method.

The state passed into this job is initialized at the start of the application. The state argument could be useful for containing a hook into something like r2d2, or the address of an actor in an actix-based system.