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 and execution history to disk.

Fields:

• filepath::String: The file path where jobs are serialized.
• 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::Cron: The cron-style schedule expression.
• action::Function: The function to execute when the job runs.
• 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.

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()

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.

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.

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.

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.