ergon_new_job (ergon v0.5.0)

The specification for a job that has not been inserted yet.

Build one with new/1,2 and the setters rather than writing the map literally, so adding a future tuning knob never breaks an existing call site:

Job = ergon_new_job:unique_for(
        ergon_new_job:with_max_attempts(
          ergon_new_job:on_queue(
            ergon_new_job:new(~"send_email", #{~"to" => ~"a@b.com"}),
            ~"mailers"),
          5),
        60),
{ok, Inserted} = ergon:enqueue(Job).

No id, no state, no fingerprint: all three belong to the database. The fingerprint in particular is a generated column over (queue, worker, payload), so it can never disagree with the row it identifies.

Summary

Types

new_job()

uniqueness()

Functions

dedup_seconds/1

The dedup window in seconds, as ergon.enqueue expects it.

new(Worker)

A job for Worker with an empty payload.

new(Worker, Payload)

Start building a job for Worker carrying Payload.

on_queue(Job, Queue)

Place the job on a specific queue.

unique_for(Job, Seconds)

Make the job unique for Seconds.

with_max_attempts(Job, MaxAttempts)

Set how many times the job may be attempted before it is marked failed.

Types

new_job()

-type new_job() ::
          #{queue := binary(),
            worker := binary(),
            payload := json:encode_value(),
            max_attempts := pos_integer(),
            uniqueness := uniqueness()}.

uniqueness()

-type uniqueness() :: not_unique | {unique_for, pos_integer()}.

Functions

dedup_seconds/1

-spec dedup_seconds(new_job()) -> non_neg_integer().

The dedup window in seconds, as ergon.enqueue expects it.

Zero means non-unique, which the function turns into an empty dedup_period. Empty ranges never overlap, so duplicates always insert.

new(Worker)

-spec new(binary()) -> new_job().

A job for Worker with an empty payload.

new(Worker, Payload)

-spec new(binary(), json:encode_value()) -> new_job().

Start building a job for Worker carrying Payload.

Payload is encoded as JSON on insert, so it must be a term json:encode/1 accepts. Defaults to the default queue, 20 attempts, and no uniqueness.

on_queue(Job, Queue)

-spec on_queue(new_job(), binary()) -> new_job().

Place the job on a specific queue.

unique_for(Job, Seconds)

-spec unique_for(new_job(), pos_integer()) -> new_job().

Make the job unique for Seconds.

Enqueuing a second job with the same (queue, worker, payload) fingerprint inside that window returns the incumbent instead of inserting a duplicate. The window is a dedup_period separate from valid_period, so a unique job stays checkoutable for its whole lifetime.

with_max_attempts(Job, MaxAttempts)

-spec with_max_attempts(new_job(), pos_integer()) -> new_job().

Set how many times the job may be attempted before it is marked failed.