gaffer_hooks behaviour (gaffer v0.7.0)

Hook behaviour for observing queue and job events.

Every hook callback receives an event path and a payload map. The payload always carries an actor field identifying which Gaffer process (or the user) caused the event. See each event's type below for its path, payload shape, and actors.

[gaffer, queue, create]: queue_create_event/0
[gaffer, queue, update]: queue_update_event/0
[gaffer, queue, pause]: queue_pause_event/0
[gaffer, queue, resume]: queue_resume_event/0
[gaffer, queue, delete]: queue_delete_event/0
[gaffer, job, insert]: job_insert_event/0
[gaffer, job, claim]: job_claim_event/0
[gaffer, job, complete]: job_complete_event/0
[gaffer, job, fail]: job_fail_event/0
[gaffer, job, cancel]: job_cancel_event/0
[gaffer, job, schedule]: job_schedule_event/0
[gaffer, job, delete]: job_delete_event/0

Summary

Types

actor()

Identifies which Gaffer process or the public API caused an event.

event()

Hook event path.

event_data()

Union of all hook event payloads.

hook()

A hook module or function.

hook_fun()

A hook callback function.

job_cancel_event()

Payload for [gaffer, job, cancel].

job_claim_event()

Payload for [gaffer, job, claim].

job_complete_event()

Payload for [gaffer, job, complete].

job_delete_event()

Payload for [gaffer, job, delete].

job_fail_event()

Payload for [gaffer, job, fail].

job_insert_event()

Payload for [gaffer, job, insert].

job_schedule_event()

Payload for [gaffer, job, schedule].

queue_create_event()

Payload for [gaffer, queue, create].

queue_delete_event()

Payload for [gaffer, queue, delete].

queue_pause_event()

Payload for [gaffer, queue, pause].

queue_resume_event()

Payload for [gaffer, queue, resume].

queue_update_event()

Payload for [gaffer, queue, update].

Callbacks

gaffer_hook/2

Called after queue and job events with event-specific payload.

Types

actor()

-type actor() :: user | worker | runner | pruner.

Identifies which Gaffer process or the public API caused an event.

event()

-type event() :: [atom()].

Hook event path.

event_data()

-type event_data() ::
          queue_create_event() |
          queue_update_event() |
          queue_pause_event() |
          queue_resume_event() |
          queue_delete_event() |
          job_insert_event() |
          job_claim_event() |
          job_complete_event() |
          job_fail_event() |
          job_cancel_event() |
          job_schedule_event() |
          job_delete_event().

Union of all hook event payloads.

hook()

-type hook() :: module() | hook_fun().

A hook module or function.

hook_fun()

-type hook_fun() :: fun((event(), event_data()) -> term()).

A hook callback function.

job_cancel_event()

-type job_cancel_event() :: #{actor := user | worker, job := gaffer:job()}.

Payload for [gaffer, job, cancel].

Triggered by actors:

user via gaffer:cancel/2.
worker when gaffer_worker:perform/1 returns {cancel, _}.

job_claim_event()

-type job_claim_event() :: #{actor := runner, queue := gaffer:queue(), jobs := [gaffer:job()]}.

Payload for [gaffer, job, claim].

Triggered by actors:

runner when claiming jobs from the storage driver.

job_complete_event()

-type job_complete_event() :: #{actor := worker, job := gaffer:job()}.

Payload for [gaffer, job, complete].

Triggered by actors:

worker when gaffer_worker:perform/1 returns complete or {complete, _}.

job_delete_event()

-type job_delete_event() ::
          #{actor := user | pruner, queue := gaffer:queue(), job_id := gaffer:job_id()}.

Payload for [gaffer, job, delete].

Triggered by actors:

user via gaffer:delete/2 or gaffer:prune/1.
pruner on its periodic prune timer.

job_fail_event()

-type job_fail_event() :: #{actor := worker | runner, job := gaffer:job()}.

Payload for [gaffer, job, fail].

Triggered by actors:

worker when gaffer_worker:perform/1 returns {fail, _} or the worker process crashes.
runner when killing the worker on timeout.

job_insert_event()

-type job_insert_event() :: #{actor := user | worker, job := gaffer:job()}.

Payload for [gaffer, job, insert].

Triggered by actors:

user via gaffer:insert/2 or gaffer:insert/3.
worker when forwarding a terminal-state job to its forward target queue.

job_schedule_event()

-type job_schedule_event() :: #{actor := worker, job := gaffer:job()}.

Payload for [gaffer, job, schedule].

Triggered by actors:

worker when gaffer_worker:perform/1 returns {schedule, _}.

queue_create_event()

-type queue_create_event() :: #{actor := user, queue := gaffer:queue(), conf := gaffer:queue_conf()}.

Payload for [gaffer, queue, create].

Triggered by actors:

user via gaffer:create_queue/1, or via gaffer:ensure_queue/1 when the queue does not yet exist.

queue_delete_event()

-type queue_delete_event() :: #{actor := user, queue := gaffer:queue()}.

Payload for [gaffer, queue, delete].

Triggered by actors:

user via gaffer:delete_queue/1 or gaffer:delete_queue/2.

queue_pause_event()

-type queue_pause_event() :: #{actor := user, queue := gaffer:queue()}.

Payload for [gaffer, queue, pause].

Triggered by actors:

user via gaffer:pause/1.

queue_resume_event()

-type queue_resume_event() :: #{actor := user, queue := gaffer:queue()}.

Payload for [gaffer, queue, resume].

Triggered by actors:

user via gaffer:resume/1.

queue_update_event()

-type queue_update_event() ::
          #{actor := user,
            queue := gaffer:queue(),
            conf := gaffer:queue_conf(),
            updates := map(),
            source := ensure | update}.

Payload for [gaffer, queue, update].

Triggered by actors:

user via gaffer:update_queue/2 (source is update), or via gaffer:ensure_queue/1 when the queue already exists (source is ensure and updates is #{}).

Callbacks

gaffer_hook/2

-callback gaffer_hook(event(), event_data()) -> term().

Called after queue and job events with event-specific payload.