View Source Oban.Engine behaviour (Oban v2.18.0)
Defines an Engine for job orchestration.
Engines are responsible for all non-plugin database interaction, from inserting through executing jobs.
Oban ships with three Engine implementations:
Basic— The default engine for development, production, and manual testing mode.Inline— Designed specifically for testing, it executes jobs immediately, in-memory, as they are inserted.Lite- The engine for running Oban using SQLite3.
🌟 SmartEngine
The Basic engine lacks advanced functionality such as global limits, rate limits, and unique bulk insert. For those features and more, see the
Smartengine in Oban Pro.
Summary
Callbacks
Mark many executing, available, scheduled or retryable job as cancelled to prevent them
from running.
Mark an executing, available, scheduled or retryable job as cancelled to prevent it
from running.
Check for a list of queues with available jobs.
Format engine meta in a digestible format for queue inspection.
Record that a job completed successfully.
Transition a job to discarded and record an optional reason that it shouldn't be ran again.
Record an executing job's errors and either retry or discard it, depending on whether it has exhausted its available attempts.
Fetch available jobs for the given queue, up to configured limits.
Initialize metadata for a queue engine.
Insert multiple jobs into the database.
Insert a job into the database.
Delete completed, cancelled and discarded jobs.
Store the given key/value pair in the engine meta.
Refresh a queue to indicate that it is still alive.
Mark many jobs as available, adding attempts if already maxed out. Any jobs currently
available, executing or scheduled should be ignored.
Mark a job as available, adding attempts if already maxed out. If the job is currently
available, executing or scheduled it should be ignored.
Prepare a queue engine for shutdown.
Reschedule an executing job to run some number of seconds in the future.
Transition scheduled or retryable jobs to available prior to execution.
Types
@type conf() :: Oban.Config.t()
@type job() :: Oban.Job.t()
@type meta() :: map()
@type opts() :: Keyword.t()
@type queryable() :: Ecto.Queryable.t()
@type running() :: map()
@type seconds() :: non_neg_integer()
Callbacks
@callback cancel_all_jobs(conf(), queryable()) :: {:ok, [Oban.Job.t()]}
Mark many executing, available, scheduled or retryable job as cancelled to prevent them
from running.
@callback cancel_job(conf(), Oban.Job.t()) :: :ok
Mark an executing, available, scheduled or retryable job as cancelled to prevent it
from running.
Check for a list of queues with available jobs.
Format engine meta in a digestible format for queue inspection.
@callback complete_job(conf(), Oban.Job.t()) :: :ok
Record that a job completed successfully.
@callback discard_job(conf(), Oban.Job.t()) :: :ok
Transition a job to discarded and record an optional reason that it shouldn't be ran again.
@callback error_job(conf(), Oban.Job.t(), seconds()) :: :ok
Record an executing job's errors and either retry or discard it, depending on whether it has exhausted its available attempts.
@callback fetch_jobs(conf(), meta(), running()) :: {:ok, {meta(), [Oban.Job.t()]}} | {:error, term()}
Fetch available jobs for the given queue, up to configured limits.
Initialize metadata for a queue engine.
Queue metadata is used to identify and track subsequent actions such as fetching or staging jobs.
@callback insert_all_jobs(conf(), [Oban.Job.changeset()], opts()) :: [Oban.Job.t()]
Insert multiple jobs into the database.
@callback insert_all_jobs( conf(), Ecto.Multi.t(), Ecto.Multi.name(), [Oban.Job.changeset()], opts() ) :: Ecto.Multi.t()
@callback insert_job(conf(), Oban.Job.changeset(), opts()) :: {:ok, Oban.Job.t()} | {:error, term()}
Insert a job into the database.
@callback insert_job( conf(), Ecto.Multi.t(), Ecto.Multi.name(), [Oban.Job.changeset()], opts() ) :: Ecto.Multi.t()
@callback prune_jobs(conf(), queryable(), opts()) :: {:ok, [Oban.Job.t()]}
Delete completed, cancelled and discarded jobs.
Store the given key/value pair in the engine meta.
Refresh a queue to indicate that it is still alive.
@callback retry_all_jobs(conf(), queryable()) :: {:ok, [Oban.Job.t()]}
Mark many jobs as available, adding attempts if already maxed out. Any jobs currently
available, executing or scheduled should be ignored.
@callback retry_job(conf(), Oban.Job.t()) :: :ok
Mark a job as available, adding attempts if already maxed out. If the job is currently
available, executing or scheduled it should be ignored.
Prepare a queue engine for shutdown.
The queue process is expected to stop processing new jobs after shutdown starts, though it may continue executing jobs that are already running.
@callback snooze_job(conf(), Oban.Job.t(), seconds()) :: :ok
Reschedule an executing job to run some number of seconds in the future.
@callback stage_jobs(conf(), queryable(), opts()) :: {:ok, [Oban.Job.t()]}
Transition scheduled or retryable jobs to available prior to execution.