Which scenario does `Oban.Plugins.Stager` for?

The doc of Oban.Plugins.Stager said:

Transition jobs to the available state when they reach their scheduled time.
This module is necessary for the execution of scheduled and retryable jobs.

In my limited experience, I think when a job is created in Oban, it is scheduled. Then, the job will run at the scheduled time.

But, the doc said “This module is necessary for the execution of scheduled and retryable jobs.”. This makes me confused – if a job is scheduled when it is created, why I need another pluigin for transforming its state?

I have no idea about which scenario does Oban.Plugins.Stager for.

Can you guys give me some tips? Thanks in advance. :wink:

1 Like

The stager is responsible for two things:

  1. Moving jobs in the scheduled state to the available state on or after their scheduled_at timestamp.
  2. Notifying queues, through pubsub, that they have available jobs. This prevents every queue from polling independently to reduce DB load.

The stager is essential to Oban functioning properly, beyond just for scheduled jobs. As such, it’s started by each Oban instance automatically unless you have plugins: false.

Edit: Oban jobs have distinct states to mark whether they are available for execution, executing currently, etc.


Thanks for your reply. It has solved my confusion.

You mentioned the distinct states.

As far as I know, all available states can be found by using Oban.Job.states():

[:scheduled, :available, :executing, :retryable, :completed, :discarded, :cancelled]

About the transition between states, I have a note:

  • :scheduled - When a job is created, its state is :scheduled.
  • :available - When a job is on or after their scheduled_at timestamp, its state will be changed to :available by Oban.Plugins.Stager.
  • :executing - When a job is :available, Oban will try to run it, and its state will changed to :executing.
  • :retryable: When a job is failed, the state will be changed to :retryable before exceeding the number of retries. Then, its state will changed to :available again by Oban.Plugins.Stager.
  • :completed: A job is completed.
  • :discarded: A job is failed, and the number of retries has reached the job’s :max_attempts.
  • :cancelled: A job is cancelled intentionally.

Is this note right?

I think this note would be helpful to the newcomers.
I want to contribute the note to the doc of Oban.Job.html#states/0. Is that fine?

That’s close. The only correction is that jobs are inserted as available unless they are scheduled in the future, then they are scheduled.

A docs contribution is absolutely welcome.

1 Like

For anyone who is interested in the PR, the link is Improve docs by c4710n · Pull Request #720 · sorentwo/oban · GitHub