Rust API

The complete API documentation is on docs.rs. This page maps the crates and their main types, so you know where to look.

MSRV: Rust 1.94 (edition 2024) for every crate.

cronoq

Building a scheduler

Scheduler::builder() returns a Builder<P, O> (P = payload type, O = output type).

Pool<P, O>:

Scheduler<P, O>

A cheap-to-clone handle. Every method is async and returns Result<_, Error>, except events(), pools() and clock(), which are synchronous and return their value directly, and stopped(), which is async and returns ().

With a persistent store, submit, enqueue, submit_batch, cancel, add_recurring and remove_recurring return only after the change is durable.

TaskHandle<O> is a Future<Output = Result<Arc<O>, TaskFailure>> with id(), is_duplicate() and cancel().

Tasks and schedules

Task<P>: Task::new(payload) (or from_arc), then priority, pool, kind, key, deadline_in / deadline_at, start_in / start_at, start_tolerance, on_miss, duration_hint, timeout, retry, no_retry, after(target), dep(Dep), resource(name, units), tag(key, value), label(name, value) (a required worker label), tenant(name) (fair sharing). Builder order does not matter. Strings must not contain NUL characters.

Recurring<P>: Recurring::new(name, cron, template), then tz, overlap(OverlapPolicy) (Skip, Allow, Queue, QueueOnSuccess), tolerance, on_miss. The template's deadline_in applies per occurrence and its key is a prefix (<key>@<start>); it may not set an absolute deadline, a fixed start or dependencies.

Executors

A panicking executor fails its attempt permanently (panic: ...); the scheduler and other attempts keep running.

Errors

See Errors and status codes.

Capacity and persistence

Blocking facade

BlockingScheduler<P, O> (from Builder::build_blocking) has the same operations without async: submit, enqueue, enqueue_many, submit_batch, task_handle, cancel, status, snapshot, set_capacity, add_recurring, remove_recurring, events, scheduler, shutdown(grace). BlockingHandle<O> has id(), cancel(), wait() and wait_timeout(d).

Re-exports and features

Engine types are re-exported from cronoq-core: AutoscaleConfig, Bounds, Dep, EdgeCond, MissPolicy, OverflowPolicy, OverlapPolicy, PoolConfig, PoolSnapshot, Priority, PriorityConfig, ResourceConfig, ResourceKind, RetryPolicy, Snapshot, StatusEvent, SubmitError, Submitted, TaskId, TaskRef, TaskStatus, UnknownDependency, UrgencyConfig, and more. The whole engine is cronoq::core.

cronoq-core

Core<P> is a deterministic state machine with no I/O, threads or clocks. Every method takes the current Time, so tests and simulations run thousands of virtual hours per second.

CoreConfig fields: pools, resources, priority, urgency, global_bounds, retention, retention_max, persist, epoch_unix_nanos, id_epoch, id_shard (default None; when set, task ids carry the shard number in their top 8 bits), metrics_window (default 60 s), seed.

cronoq-store-postgres

cronoq-store-sqlite

See Durability and high availability.

cronoq-server::worker

use cronoq_server::worker::{WorkerOptions, run_worker};

let opts = WorkerOptions::new("http://127.0.0.1:7070", "default").slots(8).token(token);
run_worker(opts, |lease| async move { Ok(lease.payload) }, shutdown_signal).await?;

The handler receives a LeaseInfo (lease, task_id, attempt, pool, payload, content_type, kind, key, tags, timeout, deadline, cancel) and returns Result<Bytes, TaskError>. run_worker enforces the granted slots, heartbeats each lease, cancels lease.cancel on Abort, turns a panicking handler into a retryable failure, and returns an error only for problems retrying cannot fix (bad credentials, unknown pool).