gaffer_driver behaviour (gaffer v0.7.0)
View SourcePersistence driver behaviour for gaffer.
Summary
Types
Options for claiming jobs.
A driver reference: either a registered name or a {module, state} tuple.
Opaque driver state, defined by each implementation.
Fields to update when transitioning a job.
Options for pruning jobs.
Errors returned by queue operations.
Callbacks
Atomically claims available jobs for execution.
Deletes a job by ID.
Fetches a job by ID.
Lists jobs matching the given filter options.
Prunes jobs in terminal states for a queue and returns the pruned IDs.
Writes a list of jobs to storage atomically.
Removes a queue name from storage.
Checks whether a queue name is registered in storage.
Registers a queue name in storage.
Lists all queue names registered in storage.
Starts the driver.
Stops the driver.
Types
-type claim_opts() :: #{queue := gaffer:queue(), limit := pos_integer() | infinity, global_max_workers := gaffer:max_workers()}.
Options for claiming jobs.
-type driver() :: atom() | {module(), driver_state()}.
A driver reference: either a registered name or a {module, state} tuple.
-type driver_state() :: term().
Opaque driver state, defined by each implementation.
-type job_changes() :: #{state := gaffer:job_state(), attempted_at := gaffer:timestamp()}.
Fields to update when transitioning a job.
-type prune_opts() :: #{gaffer:job_state() => gaffer:timestamp() | all}.
Options for pruning jobs.
A map from job state to a cutoff time or all. Jobs matching the state whose
state-specific timestamp is older than the cutoff time are deleted. all deletes
every job in that state regardless of age.
-type queue_error() :: not_found | has_jobs.
Errors returned by queue operations.
Callbacks
-callback job_claim(claim_opts(), job_changes(), driver_state()) -> [gaffer:job()].
Atomically claims available jobs for execution.
-callback job_delete(gaffer:job_id(), driver_state()) -> ok | not_found.
Deletes a job by ID.
-callback job_get(gaffer:job_id(), driver_state()) -> gaffer:job() | not_found.
Fetches a job by ID.
-callback job_list(gaffer:job_filter(), driver_state()) -> [gaffer:job()].
Lists jobs matching the given filter options.
-callback job_prune(gaffer:queue(), prune_opts(), driver_state()) -> [gaffer:job_id()].
Prunes jobs in terminal states for a queue and returns the pruned IDs.
-callback job_write([gaffer:job()], driver_state()) -> [gaffer:job()].
Writes a list of jobs to storage atomically.
The driver determines insert-vs-update per job internally. Returns the written jobs in input order.
-callback queue_delete(gaffer:queue(), driver_state()) -> ok | {error, queue_error()}.
Removes a queue name from storage.
Returns {error, not_found} if the queue name is not registered, or
{error, has_jobs} if the queue still has associated jobs in storage.
-callback queue_exists(gaffer:queue(), driver_state()) -> boolean().
Checks whether a queue name is registered in storage.
Used to validate on_discard references when creating or updating queues.
-callback queue_insert(gaffer:queue(), driver_state()) -> ok.
Registers a queue name in storage.
This operation is idempotent: if the queue name is already registered, the call must succeed without error.
-callback queue_list(driver_state()) -> [gaffer:queue()].
Lists all queue names registered in storage.
-callback start(Opts :: map()) -> driver_state().
Starts the driver.
-callback stop(driver_state()) -> any().
Stops the driver.