Task Scheduling¶

Introduction¶

In the past, you may have written a cron entry for each task you needed to schedule. Arvel's command scheduler offers a fresh approach: you define your task schedule in code with a fluent, readable API, and a single long-running process executes due tasks. You only need one cron entry on your server — to keep that process alive.

Registering the Provider¶

Scheduling is wired in automatically — SchedulerServiceProvider is one of the framework's baseline providers, so there's nothing to add to bootstrap/providers.py. It binds the Schedule as a container singleton, registers the scheduler CLI commands, and auto-discovers app/console/kernel.py.

Defining Schedules¶

Define your tasks in the console kernel:

from arvel.scheduling import Schedule


class Kernel:
    def schedule(self, schedule: Schedule) -> None:
        schedule.call(self.prune_old_records).daily()
        schedule.job(GenerateReports).dailyAt("02:00")
        schedule.command("cache:clear").hourly()

    async def prune_old_records(self) -> None:
        ...

Scheduling Callbacks¶

schedule.call() schedules an async callable:

schedule.call(prune_old_records).everyFifteenMinutes()

Scheduling Jobs & Commands¶

schedule.job() dispatches a queued job; schedule.command() runs a console command by name:

schedule.job(GenerateReports).daily()
schedule.command("queue:flush").weeklyOn(0, "03:00")

Schedule Frequency Options¶

Each call/job/command returns a builder with chainable frequency methods:

Set the timezone for a task with .timezone("Europe/Paris") (the default is UTC).

Preventing Task Overlaps¶

If a task runs long, the next tick could start a second copy. withoutOverlapping() prevents that — the second run is skipped until the first finishes (or the TTL expires):

schedule.call(generate_report).everyFiveMinutes().withoutOverlapping()

For multi-server deployments, onOneServer() ensures only one server runs a given task per tick.

Running the Scheduler¶

Run the long-lived scheduler process; it wakes each minute and runs whatever is due:

arvel schedule:work
arvel schedule:list      # list registered tasks