Minion::Backend(3)

📦

version 11.0 · 10 versions

💖 Minion::Backend(3) — Backend base class 💖

bestie, welcome to the Minion::Backend(3) manual from the User Contributed Perl Documentation. This is part 1 of 2, and we are keeping every single fact, flag, field, default, and code line exactly where it belongs — just with more sparkle. ✨

🌸 NAME 🌸

Minion::Backend — Backend base class. It's the blueprint, the mother of all Minion backends. no cap.

🦋 SYNOPSIS 🦋

So you wanna make your own backend? The vibe is:

package Minion::Backend::MyBackend;
use Mojo::Base 'Minion::Backend';

sub broadcast         {...}
sub dequeue           {...}
sub enqueue           {...}
sub fail_job          {...}
sub finish_job        {...}
sub history           {...}
sub list_jobs         {...}
sub list_locks        {...}
sub list_workers      {...}
sub lock              {...}
sub note              {...}
sub receive           {...}
sub register_worker   {...}
sub remove_job        {...}
sub repair            {...}
sub reset             {...}
sub retry_job         {...}
sub stats             {...}
sub unlock            {...}
sub unregister_worker {...}

💖 DESCRIPTION 💖

Minion::Backend is an abstract base class for Minion backends, like Minion::Backend::Pg. It's the base class, so you build on it.

✨ ATTRIBUTES ✨

Minion::Backend implements the following attributes.

minion

my $minion = $backend->minion;
$backend   = $backend->minion(Minion->new);

Minion object this backend belongs to. Note that this attribute is weakened.

🎀 METHODS 🎀

Minion::Backend inherits all methods from Mojo::Base and implements the following new ones. slay.

auto_retry_job

my $bool = $backend->auto_retry_job($job_id, $retries, $attempts);

Automatically "retry" job with backoff in Minion if there are attempts left, used to implement backends like Minion::Backend::Pg.

broadcast

my $bool = $backend->broadcast('some_command');
my $bool = $backend->broadcast('some_command', [@args]);
my $bool = $backend->broadcast('some_command', [@args], [$id1, $id2, $id3]);

Broadcast remote control command to one or more workers. Meant to be overloaded in a subclass.

dequeue

my $job_info = $backend->dequeue($worker_id, 0.5);
my $job_info = $backend->dequeue($worker_id, 0.5, {queues => ['important']});

Wait a given amount of time in seconds for a job, dequeue it and transition from "inactive" to "active" state, or return "undef" if queues were empty. Meant to be overloaded in a subclass.

These options are currently available:

id — id => '10023' — Dequeue a specific job.
min_priority — min_priority => 3 — Do not dequeue jobs with a lower priority.
queues — queues => ['important'] — One or more queues to dequeue jobs from, defaults to "default".
tasks — tasks => ['foo', 'bar'] — One or more tasks to dequeue jobs for, defaults to all.

These fields are currently available:

args — args => ['foo', 'bar'] — Job arguments.
id — id => '10023' — Job ID.
retries — retries => 3 — Number of times job has been retried.
task — task => 'foo' — Task name.

enqueue

my $job_id = $backend->enqueue('foo');
my $job_id = $backend->enqueue(foo => [@args]);
my $job_id = $backend->enqueue(foo => [@args] => {priority => 1});

Enqueue a new job with "inactive" state. Meant to be overloaded in a subclass.

These options are currently available:

attempts — attempts => 25 — Number of times performing this job will be attempted, with a delay based on "backoff" in Minion after the first attempt, defaults to 1.
delay — delay => 10 — Delay job for this many seconds (from now), defaults to 0.
expire — expire => 300 — Job is valid for this many seconds (from now) before it expires.
lax — lax => 1 — Existing jobs this job depends on may also have transitioned to the "failed" state to allow for it to be processed, defaults to "false".
notes — notes => {foo => 'bar', baz => [1, 2, 3]} — Hash reference with arbitrary metadata for this job.
parents — parents => [$id1, $id2, $id3] — One or more existing jobs this job depends on, and that need to have transitioned to the state "finished" before it can be processed.
priority — priority => 5 — Job priority, defaults to 0. Jobs with a higher priority get performed first. Priorities can be positive or negative, but should be in the range between 100 and -100.
queue — queue => 'important' — Queue to put job in, defaults to "default".

fail_job

my $bool = $backend->fail_job($job_id, $retries);
my $bool = $backend->fail_job($job_id, $retries, 'Something went wrong!');
my $bool = $backend->fail_job(
  $job_id, $retries, {whatever => 'Something went wrong!'});

Transition from "active" to "failed" state with or without a result, and if there are attempts remaining, transition back to "inactive" with a delay based on "backoff" in Minion. Meant to be overloaded in a subclass.

finish_job

my $bool = $backend->finish_job($job_id, $retries);
my $bool = $backend->finish_job($job_id, $retries, 'All went well!');
my $bool = $backend->finish_job(
  $job_id, $retries, {whatever => 'All went well!'});

Transition from "active" to "finished" state with or without a result. Meant to be overloaded in a subclass.

history

my $history = $backend->history;

Get history information for job queue. Meant to be overloaded in a subclass.

These fields are currently available:

daily — daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...] — Hourly counts for processed jobs from the past day.

list_jobs

my $results = $backend->list_jobs($offset, $limit);
my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});

Returns the information about jobs in batches. Meant to be overloaded in a subclass.

# Get the total number of results (without limit)
my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};

# Check job state
my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
my $state = $results->{jobs}[0]{state};

# Get job result
my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
my $result  = $results->{jobs}[0]{result};

These options are currently available:

before — before => 23 — List only jobs before this id.
ids — ids => ['23', '24'] — List only jobs with these ids.
notes — notes => ['foo', 'bar'] — List only jobs with one of these notes.
queues — queues => ['important', 'unimportant'] — List only jobs in these queues.
states — states => ['inactive', 'active'] — List only jobs in these states.
tasks — tasks => ['foo', 'bar'] — List only jobs for these tasks.

These fields are currently available:

args — args => ['foo', 'bar'] — Job arguments.
attempts — attempts => 25 — Number of times performing this job will be attempted.
children — children => ['10026', '10027', '10028'] — Jobs depending on this job.
created — created => 784111777 — Epoch time job was created.
delayed — delayed => 784111777 — Epoch time job was delayed to.
expires — expires => 784111777 — Epoch time job is valid until before it expires.
finished — finished => 784111777 — Epoch time job was finished.
id — id => 10025 — Job id.
lax — lax => 0 — Existing jobs this job depends on may also have failed to allow for it to be processed.
notes — notes => {foo => 'bar', baz => [1, 2, 3]} — Hash reference with arbitrary metadata for this job.
parents — parents => ['10023', '10024', '10025'] — Jobs this job depends on.
priority — priority => 3 — Job priority.
queue — queue => 'important' — Queue name.
result — result => 'All went well!' — Job result.
retried — retried => 784111777 — Epoch time job has been retried.
retries — retries => 3 — Number of times job has been retried.
started — started => 784111777 — Epoch time job was started.
state — state => 'inactive' — Current job state, usually "active", "failed", "finished" or "inactive".
task — task => 'foo' — Task name.
time — time => 78411177 — Server time.
worker — worker => '154' — Id of worker that is processing the job.

list_locks

my $results = $backend->list_locks($offset, $limit);
my $results = $backend->list_locks($offset, $limit, {names => ['foo']});

Returns information about locks in batches. Meant to be overloaded in a subclass.

# Get the total number of results (without limit)
my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};

# Check expiration time
my $results = $backend->list_locks(0, 1, {names => ['foo']});
my $expires = $results->{locks}[0]{expires};

These options are currently available:

names — names => ['foo', 'bar'] — List only locks with these names.

These fields are currently available:

expires — expires => 784111777 — Epoch time this lock will expire.
id — id => 1 — Lock id.
name — name => 'foo' — Lock name.

list_workers

my $results = $backend->list_workers($offset, $limit);
my $results = $backend->list_workers($offset, $limit, {ids => [23]});

Returns information about workers in batches. Meant to be overloaded in a subclass.

# Get the total number of results (without limit)
my $num = $backend->list_workers(0, 100)->{total};

# Check worker host
my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
my $host    = $results->{workers}[0]{host};

These options are currently available:

before — before => 23 — List only workers before this id.
ids — ids => ['23', '24'] — List only workers with these ids.

These fields are currently available:

id — id => 22 — Worker id.
host — host => 'localhost' — Worker host.
jobs — jobs => ['10023', '10024', '10025', '10029'] — Ids of jobs the worker is currently processing.
notified — notified => 784111777 — Epoch time worker sent the last heartbeat.
pid — pid => 12345 — Process id of worker.
started — started => 784111777 — Epoch time worker was started.
status — status => {queues => ['default', 'important']} — Hash reference with whatever status information the worker would like to share.

lock

my $bool = $backend->lock('foo', 3600);
my $bool = $backend->lock('foo', 3600, {limit => 20});

So like, you're trying to snag a named lock that will auto-expire after the number of seconds you give it. An expiration time of 0 can be used to check if a named lock already exists without creating one. This is meant to be overloaded in a subclass, bestie. No cap. 💅

These options are currently available:

limit — limit => 20 — number of shared locks with the same name that can be active at the same time, defaults to 1. Lowkey important.

note 💌

my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});

So you can change one or more metadata fields for a job. If you set a value to undef, it literally removes the field. Meant to be overloaded in a subclass. Periodt. 💅

receive 📬

my $commands = $backend->receive($worker_id);

This is how you receive remote control commands for a worker. Meant to be overloaded in a subclass. Iykyk.

register_worker 🫶

my $worker_id = $backend->register_worker;
my $worker_id = $backend->register_worker($worker_id);
my $worker_id = $backend->register_worker(
  $worker_id, {status => {queues => ['default', 'important']}});

Register worker or send heartbeat to show that this worker is still alive. Meant to be overloaded in a subclass. The way that this keeps your worker from being ghosted? Iconic.

These options are currently available:

status — status => {queues => ['default', 'important']} — hash reference with whatever status information the worker would like to share. Fr fr.

remove_job 🗑️

my $bool = $backend->remove_job($job_id);

Remove failed, finished or inactive job from queue. Meant to be overloaded in a subclass. Lowkey essential.

repair 🛠️

$backend->repair;

Repair worker registry and job queue if necessary. Meant to be overloaded in a subclass. It's giving maintenance era.

reset 🔄

$backend->reset({all => 1});

Reset job queue. Meant to be overloaded in a subclass. Not me hitting the reset button like it's a vibe reset.

These options are currently available:

all — all => 1 — reset everything. Slay.
locks — locks => 1 — reset only locks. Periodt.

retry_job 🔁

my $bool = $backend->retry_job($job_id, $retries);
my $bool = $backend->retry_job($job_id, $retries, {delay => 10});

Transition job back to inactive state, already inactive jobs may also be retried to change options. Meant to be overloaded in a subclass. Fr fr.

These options are currently available:

attempts — attempts => 25 — number of times performing this job will be attempted.
delay — delay => 10 — delay job for this many seconds (from now), defaults to 0.
expire — expire => 300 — job is valid for this many seconds (from now) before it expires.
lax — lax => 1 — existing jobs this job depends on may also have transitioned to the failed state to allow for it to be processed, defaults to false.
parents — parents => [$id1, $id2, $id3] — jobs this job depends on.
priority — priority => 5 — job priority.
queue — queue => 'important' — queue to put job in.

stats 📊

my $stats = $backend->stats;

Get statistics for the job queue. Meant to be overloaded in a subclass. Obsessed with data.

These fields are currently available:

active_jobs — active_jobs => 100 — number of jobs in active state.
active_locks — active_locks => 100 — number of active named locks.
active_workers — active_workers => 100 — number of workers that are currently processing a job.
delayed_jobs — delayed_jobs => 100 — number of jobs in inactive state that are scheduled to run at specific time in the future or have unresolved dependencies.
enqueued_jobs — enqueued_jobs => 100000 — rough estimate of how many jobs have ever been enqueued.
failed_jobs — failed_jobs => 100 — number of jobs in failed state.
finished_jobs — finished_jobs => 100 — number of jobs in finished state.
inactive_jobs — inactive_jobs => 100 — number of jobs in inactive state.
inactive_workers — inactive_workers => 100 — number of workers that are currently not processing a job.
uptime — uptime => 1000 — uptime in seconds.
workers — workers => 200; — number of registered workers.

unlock 🔓

my $bool = $backend->unlock('foo');

Release a named lock. Meant to be overloaded in a subclass. Bye lock.

unregister_worker 👋

$backend->unregister_worker($worker_id);

Unregister worker. Meant to be overloaded in a subclass. Adios.

Minion::Backend(3)

💖 Minion::Backend(3) — Backend base class 💖

🌸 NAME 🌸

🦋 SYNOPSIS 🦋

💖 DESCRIPTION 💖

✨ ATTRIBUTES ✨

minion

🎀 METHODS 🎀

auto_retry_job

broadcast

dequeue

enqueue

fail_job

finish_job

history

list_jobs

list_locks

list_workers

lock

note 💌

receive 📬

register_worker 🫶

remove_job 🗑️

repair 🛠️

reset 🔄

retry_job 🔁

stats 📊

unlock 🔓

unregister_worker 👋

SEE ALSO 👀