Tempus

Tempus provides a cron-style job scheduling framework for Julia, inspired by Quartz in Java.

Features:

• Define jobs with cron-like scheduling expressions
• Supports job execution policies (overlap handling, retries, and failure strategies)
• Multiple job stores and JobStore interface (in-memory, file-based persistence)
• Concurrency-aware execution with configurable retry logic
• Supports disabling, enabling, and unscheduling jobs dynamically
• Thread-safe scheduling with a background execution loop

FileStore <: Store

A file-based job storage backend that persists jobs to disk as JSON. Job execution history is only kept in memory (not persisted).

Fields:

• filepath::String: The file path where jobs are stored as JSON.
• store::InMemoryStore: In-memory store that handles operations before syncing to disk.

InMemoryStore <: Store

An in-memory job storage backend.

Fields:

• jobs::Set{Job}: Stores active jobs.
• jobExecutions::Dict{String, Vector{JobExecution}}: Stores execution history for each job.

Job

Represents a single job/unit of work. Can be scheduled to repeat.

Fields:

• name::String: Unique identifier for the job.
• schedule::Union{Cron, Nothing}: The cron-style schedule expression.
• action::Function: The function to execute when the job runs.
• action_ref::Union{Nothing, String}: Fully qualified function reference for persistence (e.g. "MyModule.my_handler").
• action_data::Union{Nothing, String}: JSON-encoded parameters for persistence. Splatted as kwargs: action(; JSON.parse(action_data)...).
• options::JobOptions: Execution options for retries, failures, and overlap handling.
• disabledAt::Union{DateTime, Nothing}: Timestamp when the job was disabled (if applicable).

JobExecution

Represents an instance of a job execution.

Fields:

• jobExecutionId::String: Unique identifier for this job execution.
• job::Job: The job being executed.
• scheduledStart::DateTime: When the job was scheduled to run.
• runConcurrently::Bool: Whether this execution is running concurrently with another.
• actualStart::DateTime: The actual start time.
• finish::DateTime: The completion time.
• status::Symbol: The execution result (:succeeded, :failed).

JobOptions

Defines options for job execution behavior.

Fields:

• overlap_policy::Union{Symbol, Nothing}: Determines job execution behavior when the same job is already running (:skip, :queue, :concurrent).
• retries::Int: Number of retries allowed on failure.
• retry_delays::Union{Base.ExponentialBackOff, Nothing}: Delay strategy for retries (defaults to exponential backoff if retries > 0).
• retry_check: Custom function to determine retry behavior (check argument from Base.retry).
• max_failed_executions::Union{Int, Nothing}: Maximum number of failed executions allowed for a job before it will be disabled.
• max_executions::Union{Int, Nothing}: Maximum number of executions allowed for a job.
• expires_at::Union{DateTime, Nothing}: Expiration time for a job.
• timezone::Union{Nothing, String}: IANA timezone name (e.g. "America/Denver"). When set, the job's cron schedule is interpreted in this timezone. nothing means UTC.

SQLiteStore <: Store

A SQLite-backed job storage that uses an InMemoryStore as cache. The db field holds the SQLite.DB (typed as Any to avoid hard dependency). The extension TempusSQLiteExt provides the constructor and all store methods.

Scheduler

The main scheduling engine that executes jobs according to their schedules.

Fields:

• lock::ReentrantLock: Ensures thread-safe access.
• jobExecutions::Vector{JobExecution}: List of scheduled job executions.
• store::Store: Job storage backend.
• jobExecutionFinished::Threads.Event: Signals all job executions have finished when shutting down.
• executingJobExecutions::Set{JobExecution}: Tracks currently executing jobs.
• running::Bool: Scheduler state (running/stopped).
• jobOptions::JobOptions: Default job execution options.
• max_concurrent_executions::Int: Limit on how many total executions can be running concurrently for this scheduler, defaults to Threads.nthreads()
• logging::Bool: Whether to emit log messages during scheduler operations, defaults to true.

Store

Defines an interface for job storage backends.

close(scheduler::Scheduler)

Closes the scheduler, stopping job execution; waits for any currently executing jobs to finish. Will wait timeout seconds (5 by default) for any currently executing jobs to finish before returning.

push!(scheduler::Scheduler, job::Job)

Adds a job to the scheduler and underlying Store, scheduling its next execution based on its cron schedule.

wait(scheduler::Scheduler)

Waits for the scheduler to finish executing all jobs. Note the scheduler must be explicitly closed to stop the scheduler loop or pass close_when_no_jobs=true to run! to automatically close the scheduler when no jobs are left.

Auto-extract fully qualified function reference string from a named function.

addJob!(store::Store, job::Job)

Add a new job to store.

disable!(job::Job)

Disables a job, preventing it from being scheduled for execution.

disableJob!(store::Store, job::Union{Job, String})

Disable a job in store by reference or name.

enable!(job::Job)

Enables a previously disabled job, allowing it to be scheduled again.

getJobs(store::Store) -> Collection{Job}

Retrieve all jobs stored in store, regardless of disabled status.

getNMostRecentJobExecutions(store::Store, jobName::String, n::Int) -> Vector{JobExecution}

Get the n most recent job executions for a job persisted in store.

getnext(cron::Cron, timezone::String, from::DateTime=Dates.now(UTC)) -> DateTime

Compute the next trigger time for cron interpreted in timezone (IANA name, e.g. "America/Denver"). from is a UTC DateTime. Returns a UTC DateTime. DST handling: spring-forward gaps are skipped, fall-back ambiguities use the first occurrence.

isdisabled(job::Job) -> Bool

Returns true if the job is currently disabled.

purgeJob!(store::Store, job::Union{Job, String})

Remove a job from store by reference or name. All job execution history will also be removed.

resolve_function(ref::String) -> Function

Resolve a function from its fully qualified reference string (e.g. "MyModule.my_handler"). The module must be loaded before calling this function.

run!(scheduler::Scheduler)

Starts the scheduler, executing jobs at their scheduled times.

runJobs!(store::Store, jobs; kw...)

Add each job in jobs to store, run a scheduler with kw options, wait for all jobs to finish, then close the scheduler.

storeJobExecution!(store::Store, jobExecution::JobExecution)

Store jobExecution in store.

withscheduler(f, args...; kw...)

Creates a scheduler, runs a function f with it, then calls close.