Struct Jobs 

pub struct Jobs { /* private fields */ }

Primary entry point for interacting with the Job crate. Provides APIs to register job handlers, manage configuration, and control scheduling and execution.

Implementations

impl Jobs

pub async fn init(config: JobSvcConfig) -> Result<Self, JobError>

Initialize the service using a JobSvcConfig for connection and runtime settings.

pub async fn start_poll(&mut self) -> Result<(), JobError>

Start the background poller that fetches and dispatches jobs from Postgres.

Call this only after registering every job initializer. The call consumes the internal registry; attempting to register additional initializers or starting the poller again afterwards will panic with Registry has been consumed by executor.

Errors

Returns JobError::Sqlx if the poller cannot initialise its database listeners or supporting tasks.

Panics

Panics if invoked more than once, or if Jobs::add_initializer is called after the poller has started.

Examples

Register any initializers and then start the poller:

use job::{
    Jobs, JobSvcConfig, Job, JobId, JobInitializer, JobRunner, JobType, JobCompletion,
    CurrentJob, JobSpawner
};
use job::error::JobError;
use async_trait::async_trait;
use serde::{Serialize, Deserialize};
use sqlx::postgres::PgPoolOptions;
use std::error::Error;

#[derive(Debug, Serialize, Deserialize)]
struct MyConfig {
    value: i32,
}

struct MyInitializer;

impl JobInitializer for MyInitializer {
    type Config = MyConfig;

    fn job_type(&self) -> JobType {
        JobType::new("example")
    }

    fn init(&self, _job: &Job, _: JobSpawner<Self::Config>) -> Result<Box<dyn JobRunner>, Box<dyn Error>> {
        Ok(Box::new(MyRunner))
    }
}

struct MyRunner;

#[async_trait]
impl JobRunner for MyRunner {
    async fn run(
        &self,
        _current_job: CurrentJob,
    ) -> Result<JobCompletion, Box<dyn Error>> {
        Ok(JobCompletion::Complete)
    }
}

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:password@localhost/postgres")?;
let config = JobSvcConfig::builder().pool(pool).build().unwrap();
let mut jobs = Jobs::init(config).await?;

// Registration returns a type-safe spawner
let spawner: JobSpawner<MyConfig> = jobs.add_initializer(MyInitializer);

jobs.start_poll().await?;

// Use the spawner to create jobs
spawner.spawn(JobId::new(), MyConfig { value: 42 }).await?;

Calling start_poll again, or attempting to register a new initializer afterwards, results in a panic:

use job::{
    Jobs, JobSvcConfig, Job, JobInitializer, JobRunner, JobType, JobCompletion, CurrentJob,
    JobSpawner,
};
use job::error::JobError;
use async_trait::async_trait;
use serde::{Serialize, Deserialize};
use sqlx::postgres::PgPoolOptions;
use std::error::Error;

#[derive(Debug, Serialize, Deserialize)]
struct MyConfig {
    value: i32,
}

struct MyInitializer;

impl JobInitializer for MyInitializer {
    type Config = MyConfig;

    fn job_type(&self) -> JobType {
        JobType::new("example")
    }

    fn init(&self, _job: &Job, _spawner: JobSpawner<Self::Config>) -> Result<Box<dyn JobRunner>, Box<dyn Error>> {
        Ok(Box::new(MyRunner))
    }
}

struct MyRunner;

#[async_trait]
impl JobRunner for MyRunner {
    async fn run(
        &self,
        _current_job: CurrentJob,
    ) -> Result<JobCompletion, Box<dyn Error>> {
        Ok(JobCompletion::Complete)
    }
}

let pool = PgPoolOptions::new()
    .connect_lazy("postgres://postgres:password@localhost/postgres")?;
let config = JobSvcConfig::builder().pool(pool).build().unwrap();
let mut jobs = Jobs::init(config).await?;

let _spawner = jobs.add_initializer(MyInitializer);

jobs.start_poll().await?;

// Panics with "Registry has been consumed by executor".
// jobs.start_poll().await.unwrap();

// Also panics because the registry moved into the poller.
// jobs.add_initializer(MyInitializer);

pub fn add_initializer<I: JobInitializer>( &mut self, initializer: I, ) -> JobSpawner<I::Config>

Register a JobInitializer and return a JobSpawner for creating jobs.

Examples

let spawner = jobs.add_initializer(MyInitializer);
spawner.spawn(JobId::new(), MyConfig { value: 42 }).await?;

Panics

Panics if called after start_poll.

pub async fn find(&self, id: JobId) -> Result<Job, JobError>

Fetch the current snapshot of a job entity by identifier.

pub fn clock(&self) -> &ClockHandle

Returns a reference to the clock used by this job service.

pub async fn shutdown(&self) -> Result<(), JobError>

Gracefully shut down the job poller.

This method is idempotent and can be called multiple times safely. It will send a shutdown signal to all running jobs, wait briefly for them to complete, and reschedule any jobs still running.

If not called manually, shutdown will be automatically triggered when the Jobs instance is dropped.

Trait Implementations

impl Clone for Jobs

fn clone(&self) -> Jobs

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.