@callback query() :: [term()]

A function which returns a list of records to be updated my a given job.

Called as a way of stepping through large datasets (i.e. given an Ecto.Queryable.t() with predicates which get invalidated as update/1 is run.

Monarch jobs are deemed successful and complete once query/0 returns an empty list.

@callback scheduled_at() :: DateTime.t() | nil

The time the job should be scheduled to run at in the future in UTC.

If scheduled_at is in the past, the job will be scheduled as soon as possible the next time Monarch is run. If scheduled_at is nil, Monarch won't automatically enqueue jobs, and they will need to be manually enqueued.

@callback skip() :: boolean()

A function which returns whether or not the worker should skip the operation.

For example, this is useful when you want to run an Oban job on one environment but not another.

@callback snooze?() :: nil | false | integer()

Controls whether or not the job will snooze for a given number of seconds before running again.

This is useful for jobs that should only run within a core set of business hours, or while external services are reachable.

If snooze? is a falsey value, the job will not snooze.

Example:

@impl Monarch
def snooze? do
  if DateTime.utc_now().hour in 9..5 do
    3600 # snooze till the next hour
  end
endcopy

Note that this callback is checked on every iteration of a backfill, so the runtime of your snooze function will impact the performance of your backfill.

@callback transaction?() :: boolean()

Controls whether or not the job will run in a transaction

@callback update([term()]) :: term()

A function which takes the output of successive query/1 calls and performs the given function against it.

When used in tandem with query/0, allows stepping through large datasets (i.e. given an Ecto.Queryable.t() which invalidates predicates defined in query/0)