Skip to content
calternal docs

calternal_db::cron

Cron expressions that enqueue idempotent jobs.

Source: crates/calternal-db/src/cron.rs

Structs

Section titled “Structs”

CronJobSchedule

Section titled “CronJobSchedule”
pub struct CronJobSchedule

One cron schedule owned by a crate or Plugin.

Fields

  • pub id: String: Globally unique, stable schedule id. Prefix it with the owning Plugin’s id, and keep it stable across restarts and expression edits.
  • pub expression: String: Six-field cron expression: seconds, minutes, hours, day, month, weekday. Cron 0.17 also accepts its optional year field.
  • pub kind: String: Registered handler kind.
  • pub payload: Value: Payload passed to the job handler.
  • pub timezone: Option<Tz>: Interpret the cron fields as wall-clock time in this zone. Without a zone, the scheduler keeps its historic UTC interpretation.
  • pub priority: i64: Higher values are leased first.
  • pub max_attempts: u32: Maximum handler attempts.

Implements: Clone, Debug

CronJobSchedule::new

Section titled “CronJobSchedule::new”
pub fn new(
        id: impl Into<String>,
        expression: impl Into<String>,
        kind: impl Into<String>,
        payload: Value,
    ) -> Self

Build a schedule with default priority and retry count.

CronJobSchedule::in_timezone

Section titled “CronJobSchedule::in_timezone”
pub fn in_timezone(mut self, timezone: Tz) -> Self

Evaluate the cron fields in an IANA time zone, while keeping queued run_at values as UTC instants.

Source: crates/calternal-db/src/cron.rs:15

CronScheduler

Section titled “CronScheduler”
pub struct CronScheduler

Evaluates schedules and stores each schedule’s cursor. The schedule id is also the job dedup key, so at most one copy can be pending or leased at once.

CronScheduler::new

Section titled “CronScheduler::new”
pub fn new(queue: JobQueue, schedules: Vec<CronJobSchedule>) -> Result<Self>

Parse and validate schedule definitions.

CronScheduler::enqueue_due

Section titled “CronScheduler::enqueue_due”
pub async fn enqueue_due(&self, now: DateTime<Utc>) -> Result<Vec<(String, EnqueueOutcome)>>

Enqueue due schedules through now. Unzoned schedules use UTC; zoned schedules use their configured wall-clock zone. Calling this more than once is safe: cursors persist in SQLite and each schedule has one active dedup key. If a process slept through multiple occurrences, one job is enqueued and the cursor skips older missed occurrences.

CronScheduler::run

Section titled “CronScheduler::run”
pub async fn run(
        &self,
        poll_interval: StdDuration,
        mut shutdown: watch::Receiver<bool>,
    ) -> Result<()>

Poll and enqueue schedules until shutdown. The server can run this beside its Workers and share the same shutdown signal.

Source: crates/calternal-db/src/cron.rs:87