Scheduler
JustAPI's scheduler manages periodic tasks using cron expressions and fixed
intervals. It runs entirely in Rust with UTC-based timing, and jobs are
dispatched onto the same Rust background-task worker pool as
BackgroundTasks — so they run with the GIL released.
There are two ways to use it: the standalone Scheduler class, or the
convenience methods on JustAPIApp.
Standalone Scheduler
from justapi import Scheduler
scheduler = Scheduler()
scheduler.schedule("*/5 * * * *", my_task) # cron expression
scheduler.every(30, poll_upstream) # fixed interval
scheduler.start()
| Method | Description |
|---|---|
schedule(cron_expr, func, *args, **kwargs) |
Schedule a job with a standard 5-field cron expression |
every(seconds, func, *args, **kwargs) |
Schedule a job at a fixed interval |
remove(job) |
Remove a scheduled job |
jobs |
List registered jobs |
stats |
Job run statistics |
start() |
Start the scheduler (jobs run for the process lifetime) |
stop() |
Stop the scheduler |
schedule() — cron jobs
# Run every hour at minute 0
scheduler.schedule("0 * * * *", my_task)
# With arguments
scheduler.schedule("0 0 * * *", daily_report, "team@example.com")
| Parameter | Type | Description |
|---|---|---|
cron_expr |
str |
Standard 5-field cron expression (min hour day month weekday), evaluated in UTC |
func |
callable | Function to execute |
*args / **kwargs |
— | Passed through to func |
every() — interval jobs
# Run every 30 seconds (first fire one interval after registration)
scheduler.every(30, my_task)
| Parameter | Type | Description |
|---|---|---|
seconds |
int | Interval in seconds |
func |
callable | Function to execute |
*args / **kwargs |
— | Passed through to func |
Note: jobs are in-memory (not persisted) in the current version. The scheduler runs for the lifetime of the process.
Integration with App
The JustAPIApp methods schedule() and every() register jobs directly and
start the scheduler automatically when the server starts:
from justapi import JustAPIApp
app = JustAPIApp()
def cleanup_expired_sessions():
app.db.execute("DELETE FROM sessions WHERE expires_at < ?", ["now"])
app.schedule("0 */6 * * *", cleanup_expired_sessions) # Every 6 hours
app.every(30, poll_upstream) # Every 30 seconds
app.run("127.0.0.1:8000")
See Also
- Background Tasks — Per-request background tasks
- JustAPIApp — App configuration