Update README, add max_execution and expires_at support for jobs

Author: quinnj

README.md

@@ -1,8 +1,82 @@
-Example Julia package repo.
+# Tempus.jl
 
-[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaLang.github.io/Example.jl/stable)
-[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaLang.github.io/Example.jl/dev)
+[![Build Status](https://github.com/JuliaServices/Tempus.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/JuliaServices/Tempus.jl/actions)
+[![Coverage](https://codecov.io/gh/JuliaServices/Tempus.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaServices/Tempus.jl)
+[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaServices.github.io/Tempus.jl/stable/)
 
-GitHub Actions : [![Build Status](https://github.com/JuliaLang/Example.jl/workflows/CI/badge.svg)](https://github.com/JuliaLang/Example.jl/actions?query=workflow%3ACI+branch%3Amaster)
+## Overview
+**Tempus.jl** is a lightweight, Quartz-inspired job scheduling library for Julia. It provides an easy-to-use API for defining cron-like schedules and executing jobs at specified times.
 
-[![codecov.io](http://codecov.io/github/JuliaLang/Example.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaLang/Example.jl?branch=master)
+### Features
+- Define jobs using cron-style scheduling expressions
+- Support for job execution policies (overlap handling, retries, failure strategies)
+- In-memory and file-based job storage backends
+- Thread-safe scheduling with concurrency-aware execution
+- Dynamic job control (enable, disable, unschedule jobs)
+- Supports retry policies with exponential backoff
+
+## Installation
+Tempus.jl is not yet registered in the Julia General registry. You can install it directly from GitHub:
+
+```julia
+using Pkg
+Pkg.add(url="https://github.com/JuliaServices/Tempus.jl")
+```
+
+## Quick Start
+
+### Defining and Scheduling a Job
+```julia
+using Tempus
+
+# Define a job that prints a message every minute
+job = Tempus.Job("example_job", "* * * * *", () -> println("Hello from Tempus!"))
+
+# Create an in-memory scheduler
+scheduler = Tempus.Scheduler()
+
+# Add the job to the scheduler
+push!(scheduler, job)
+
+# Start the scheduler (runs in a background thread)
+Tempus.run!(scheduler)
+```
+
+### Disabling and Enabling Jobs
+```julia
+Tempus.disable!(job)  # Prevents the job from running
+Tempus.enable!(job)   # Allows it to run again
+```
+
+### Removing a Job
+```julia
+Tempus.unschedule!(scheduler, job)
+```
+
+### Using a File-Based Job Store
+To persist job execution history across restarts, use a file-based store:
+```julia
+store = Tempus.FileStore("jobs.dat")
+scheduler = Tempus.Scheduler(store)
+```
+
+## Cron Syntax
+Tempus.jl uses a familiar cron syntax for scheduling:
+```
+* * * * *  → Every minute
+0 12 * * * → Every day at noon
+*/5 * * * * → Every 5 minutes
+# also supports second-level precision
+* * * * * * → Every second
+```
+
+## Contributing
+Contributions are welcome! To contribute:
+1. Fork the repository.
+2. Create a new branch with your feature or bugfix.
+3. Submit a pull request with your changes.
+
+Make sure to include tests for any new functionality.
+
+## License
+Tempus.jl is licensed under the MIT License.

src/Tempus.jl

@@ -31,13 +31,17 @@ Defines options for job execution behavior.
 - `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`).
 - `on_fail_policy::Union{Tuple{Symbol, Int}, Nothing}`: Determines job failure handling (`:ignore`, `:disable`, `:unschedule`), with a threshold for consecutive failures.
+- `max_executions::Union{Int, Nothing}`: Maximum number of executions allowed for a job.
+- `expires_at::Union{DateTime, Nothing}`: Expiration time for a job.
 """
 @kwdef struct JobOptions
     overlap_policy::Union{Symbol, Nothing} = nothing # :skip, :queue, :concurrent
     retries::Int = 0
     retry_delays::Union{Base.ExponentialBackOff, Nothing} = retries > 0 ? Base.ExponentialBackOff(; n=retries) : nothing # see Base.ExponentialBackOff
     retry_check = nothing # see Base.retry `check` keyword argument
     on_fail_policy::Union{Tuple{Symbol, Int}, Nothing} = nothing # :ignore, :disable, :unschedule + max consecutive failures for disable/unschedule
+    max_executions::Union{Int, Nothing} = nothing # max number of executions job is allowed to run
+    expires_at::Union{DateTime, Nothing} = nothing # expiration time for job
 end
 
 """
@@ -53,16 +57,15 @@ Represents a scheduled job in the Tempus scheduler.
 - `disabledAt::Union{DateTime, Nothing}`: Timestamp when the job was disabled (if applicable).
 """
 mutable struct Job
+    const action::Function
     const name::String
     const schedule::Cron
-    const action::Function
     const options::JobOptions
     # fields managed by scheduler
     disabledAt::Union{DateTime, Nothing}
 end
 
-Job(name, schedule, action::Function; kw...) = Job(string(name), schedule isa Cron ? schedule : parseCron(schedule), action, JobOptions(kw...), nothing)
-Job(action::Function, name, schedule; kw...) = Job(name, schedule, action; kw...)
+Job(action::Function, name, schedule; kw...) = Job(action, string(name), schedule isa Cron ? schedule : parseCron(schedule), JobOptions(kw...), nothing)
 
 """
     disable!(job::Job)
@@ -325,6 +328,25 @@ function checkDisable!(scheduler::Scheduler, store::Store, job::Job, on_fail_pol
     return
 end
 
+function checkExpirationAndMaxExecutions!(scheduler::Scheduler, job::Job)
+    max_executions = _some(job.options.max_executions, scheduler.jobOptions.max_executions)
+    expires_at = _some(job.options.expires_at, scheduler.jobOptions.expires_at)
+    if max_executions !== nothing
+        execs = getNMostRecentJobExecutions(scheduler.store, job.name, max_executions)
+        if length(execs) >= max_executions
+            unschedule!(scheduler, job)
+            @info "Unscheduling job $(job.name) after reaching maximum executions of $(max_executions)."
+            return true
+        end
+    end
+    if expires_at !== nothing && expires_at < Dates.now(UTC)
+        unschedule!(scheduler, job)
+        @info "Unscheduling job $(job.name) after expiration at $(expires_at)."
+        return true
+    end
+    return false
+end
+
 """
     run!(scheduler::Scheduler)
 
@@ -371,8 +393,10 @@ function run!(scheduler::Scheduler)
                                 @warn "Job $(je.job.name) already executing, keeping scheduled execution queued until current execution finishes. There are $nexecs queued for this job."
                                 # check if we need to schedule the next execution
                                 next = getnext(je.job.schedule)
-                                if any(j -> j.job.name == je.job.name && j.scheduledStart == next, scheduler.jobExecutions)
-                                    # we've already scheduled this execution, skip
+                                # check job expiration and max executions
+                                unscheduled = checkExpirationAndMaxExecutions!(scheduler, je.job)
+                                if unscheduled || any(j -> j.job.name == je.job.name && j.scheduledStart == next, scheduler.jobExecutions)
+                                    # job is unscheduled or we've already scheduled this execution, skip
                                 else
                                     push!(scheduler.jobExecutions, JobExecution(je.job, next))
                                 end
@@ -390,6 +414,8 @@ function run!(scheduler::Scheduler)
                     for (i, toSkip, je) in readyToExecute
                         deleteat!(scheduler.jobExecutions, i)
                         next = getnext(je.job.schedule)
+                        # check job expiration and max executions
+                        checkExpirationAndMaxExecutions!(scheduler, je.job) && continue
                         newje = JobExecution(je.job, next)
                         push!(scheduler.jobExecutions, newje)
                         if je.job.disabledAt !== nothing
@@ -466,18 +492,23 @@ function executeJob!(scheduler::Scheduler, jobExecution::JobExecution)
     return
 end
 
-currentlyExecutionJobs(sch::Scheduler) = [je.jobExecutionId for je in sch.executingJobExecutions]
-
 """
     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.
 """
-function Base.close(scheduler::Scheduler)
-    @info "Closing scheduler and stopping job execution."
+function Base.close(scheduler::Scheduler; timeout::Real=5)
+    @info "Closing scheduler and waiting $(timeout)s for job executions to stop."
     @lock scheduler.lock begin
         scheduler.running = false
     end
+    # we use a Timer here to notify jobExecutionFinished ourself if the scheduler
+    # or last executing job doesn't do it themselves in time
+    Timer(timeout) do t
+        @warn "Scheduler closing timeout reached, returning without waiting for job executions to finish."
+        notify(scheduler.jobExecutionFinished)
+    end
     wait(scheduler.jobExecutionFinished)
     @info "Scheduler closed and job execution stopped."
     return

test/runtests.jl

@@ -232,7 +232,7 @@ executed = DateTime[]
 
 @testset "Scheduler Scheduling and Execution" begin
     # We'll create a simple job that records its execution time.
-    test_job = Tempus.Job(:testjob, "* * * * * *") do
+    test_job = Tempus.Job("testjob", "* * * * * *") do
         global executed
         push!(executed, Dates.now(UTC))
     end
@@ -262,7 +262,7 @@ executed = DateTime[]
     # overlap policy
     # skip
     # job that takes 2 seconds to run, but runs every second
-    sleep_job = Tempus.Job(:sleepjob, "* * * * * *") do
+    sleep_job = Tempus.Job("sleepjob", "* * * * * *") do
         sleep(2)
         push!(executed, Dates.now(UTC))
     end
@@ -288,7 +288,7 @@ executed = DateTime[]
     @test length(executed) == 2
     # retry settings
     # retry n times
-    fail_job = Tempus.Job(:failjob, "* * * * * *") do
+    fail_job = Tempus.Job("failjob", "* * * * * *") do
         println("length(executed): ", length(executed))
         if length(executed) < 2
             push!(executed, Dates.now(UTC))
@@ -322,7 +322,7 @@ executed = DateTime[]
     @test toggle[] == false
     # on_fail_policy
     # ignore
-    always_fail_job = Tempus.Job(:failjob, "* * * * * *") do
+    always_fail_job = Tempus.Job("failjob", "* * * * * *") do
         push!(executed, Dates.now(UTC))
         error("always fail job")
     end