Behaviour for alarm scheduling backends.
Implementations must handle:
- Scheduling alarms for future execution
- Cancelling pending alarms
- Resurrecting alarms after process/node crashes
Built-in Implementations
DurableObject.Scheduler.Polling- Database-backed polling scheduler (default)DurableObject.Scheduler.Oban- Oban-based scheduler (requires oban dependency)
Configuration
Polling Scheduler (default)
config :durable_object,
scheduler: DurableObject.Scheduler.Polling,
scheduler_opts: [
repo: MyApp.Repo,
polling_interval: :timer.seconds(30)
]Oban Scheduler
For applications already using Oban, the Oban scheduler leverages your existing Oban infrastructure for alarm delivery.
config :durable_object,
scheduler: DurableObject.Scheduler.Oban,
scheduler_opts: [oban_queue: :durable_object_alarms]You must also add the queue to your Oban configuration:
config :my_app, Oban,
repo: MyApp.Repo,
queues: [durable_object_alarms: 5]If your app uses a custom Oban instance name, specify it with oban_instance:
scheduler_opts: [oban_instance: MyApp.Oban, oban_queue: :durable_object_alarms]Summary
Callbacks
Cancel a pending alarm. Returns :ok even if the alarm doesn't exist.
Cancel all alarms for an object.
Child spec for the scheduler's supervision tree (poller, etc). Return an empty list if no children are needed.
List all pending alarms for an object. Returns a list of {alarm_name, scheduled_at} tuples.
Schedule an alarm to fire after delay_ms milliseconds.
If an alarm with the same name already exists, it should be replaced.
Types
Callbacks
@callback cancel(object_ref(), alarm_name(), opts :: keyword()) :: :ok | {:error, term()}
Cancel a pending alarm. Returns :ok even if the alarm doesn't exist.
@callback cancel_all(object_ref(), opts :: keyword()) :: :ok | {:error, term()}
Cancel all alarms for an object.
@callback child_spec(opts :: keyword()) :: [Supervisor.child_spec()]
Child spec for the scheduler's supervision tree (poller, etc). Return an empty list if no children are needed.
@callback list(object_ref(), opts :: keyword()) :: {:ok, [{alarm_name(), DateTime.t()}]} | {:error, term()}
List all pending alarms for an object. Returns a list of {alarm_name, scheduled_at} tuples.
@callback schedule(object_ref(), alarm_name(), delay_ms(), opts :: keyword()) :: :ok | {:error, term()}
Schedule an alarm to fire after delay_ms milliseconds.
If an alarm with the same name already exists, it should be replaced.