1Minion::Backend(3) User Contributed Perl Documentation Minion::Backend(3)
2
6 Minion::Backend - Backend base class
7
9 package Minion::Backend::MyBackend;
10 use Mojo::Base 'Minion::Backend';
11 sub broadcast {...}
13 sub dequeue {...}
14 sub enqueue {...}
15 sub fail_job {...}
16 sub finish_job {...}
17 sub history {...}
18 sub list_jobs {...}
19 sub list_locks {...}
20 sub list_workers {...}
21 sub lock {...}
22 sub note {...}
23 sub receive {...}
24 sub register_worker {...}
25 sub remove_job {...}
26 sub repair {...}
27 sub reset {...}
28 sub retry_job {...}
29 sub stats {...}
30 sub unlock {...}
31 sub unregister_worker {...}
32
34 Minion::Backend is an abstract base class for Minion backends, like
35 Minion::Backend::Pg.
36
38 Minion::Backend implements the following attributes.
39 minion
41 my $minion = $backend->minion;
42 $backend = $backend->minion(Minion->new);
43 Minion object this backend belongs to. Note that this attribute is
45 weakened.
46
48 Minion::Backend inherits all methods from Mojo::Base and implements the
49 following new ones.
50 auto_retry_job
52 my $bool = $backend->auto_retry_job($job_id, $retries, $attempts);
53 Automatically "retry" job with "backoff" in Minion if there are
55 attempts left, used to implement backends like Minion::Backend::Pg.
56 broadcast
58 my $bool = $backend->broadcast('some_command');
59 my $bool = $backend->broadcast('some_command', [@args]);
60 my $bool = $backend->broadcast('some_command', [@args], [$id1, $id2, $id3]);
61 Broadcast remote control command to one or more workers. Meant to be
63 overloaded in a subclass.
64 dequeue
66 my $job_info = $backend->dequeue($worker_id, 0.5);
67 my $job_info = $backend->dequeue($worker_id, 0.5, {queues => ['important']});
68 Wait a given amount of time in seconds for a job, dequeue it and
70 transition from "inactive" to "active" state, or return "undef" if
71 queues were empty. Meant to be overloaded in a subclass.
72 These options are currently available:
74 id
76 id => '10023'
77 Dequeue a specific job.
79 min_priority
81 min_priority => 3
82 Do not dequeue jobs with a lower priority.
84 queues
86 queues => ['important']
87 One or more queues to dequeue jobs from, defaults to "default".
89 These fields are currently available:
91 args
93 args => ['foo', 'bar']
94 Job arguments.
96 id
98 id => '10023'
99 Job ID.
101 retries
103 retries => 3
104 Number of times job has been retried.
106 task
108 task => 'foo'
109 Task name.
111 enqueue
113 my $job_id = $backend->enqueue('foo');
114 my $job_id = $backend->enqueue(foo => [@args]);
115 my $job_id = $backend->enqueue(foo => [@args] => {priority => 1});
116 Enqueue a new job with "inactive" state. Meant to be overloaded in a
118 subclass.
119 These options are currently available:
121 attempts
123 attempts => 25
124 Number of times performing this job will be attempted, with a delay
126 based on "backoff" in Minion after the first attempt, defaults to 1.
127 delay
129 delay => 10
130 Delay job for this many seconds (from now), defaults to 0.
132 expire
134 expire => 300
135 Job is valid for this many seconds (from now) before it expires.
137 lax
139 lax => 1
140 Existing jobs this job depends on may also have transitioned to the
142 "failed" state to allow for it to be processed, defaults to "false".
143 Note that this option is EXPERIMENTAL and might change without
144 warning!
145 notes
147 notes => {foo => 'bar', baz => [1, 2, 3]}
148 Hash reference with arbitrary metadata for this job.
150 parents
152 parents => [$id1, $id2, $id3]
153 One or more existing jobs this job depends on, and that need to have
155 transitioned to the state "finished" before it can be processed.
156 priority
158 priority => 5
159 Job priority, defaults to 0. Jobs with a higher priority get
161 performed first. Priorities can be positive or negative, but should
162 be in the range between 100 and -100.
163 queue
165 queue => 'important'
166 Queue to put job in, defaults to "default".
168 fail_job
170 my $bool = $backend->fail_job($job_id, $retries);
171 my $bool = $backend->fail_job($job_id, $retries, 'Something went wrong!');
172 my $bool = $backend->fail_job(
173 $job_id, $retries, {whatever => 'Something went wrong!'});
174 Transition from "active" to "failed" state with or without a result,
176 and if there are attempts remaining, transition back to "inactive" with
177 a delay based on "backoff" in Minion. Meant to be overloaded in a
178 subclass.
179 finish_job
181 my $bool = $backend->finish_job($job_id, $retries);
182 my $bool = $backend->finish_job($job_id, $retries, 'All went well!');
183 my $bool = $backend->finish_job(
184 $job_id, $retries, {whatever => 'All went well!'});
185 Transition from "active" to "finished" state with or without a result.
187 Meant to be overloaded in a subclass.
188 history
190 my $history = $backend->history;
191 Get history information for job queue. Meant to be overloaded in a
193 subclass.
194 These fields are currently available:
196 daily
198 daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...]
199 Hourly counts for processed jobs from the past day.
201 list_jobs
203 my $results = $backend->list_jobs($offset, $limit);
204 my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});
205 Returns the information about jobs in batches. Meant to be overloaded
207 in a subclass.
208 # Get the total number of results (without limit)
210 my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};
211 # Check job state
213 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
214 my $state = $results->{jobs}[0]{state};
215 # Get job result
217 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
218 my $result = $results->{jobs}[0]{result};
219 These options are currently available:
221 before
223 before => 23
224 List only jobs before this id.
226 ids
228 ids => ['23', '24']
229 List only jobs with these ids.
231 notes
233 notes => ['foo', 'bar']
234 List only jobs with one of these notes.
236 queues
238 queues => ['important', 'unimportant']
239 List only jobs in these queues.
241 states
243 states => ['inactive', 'active']
244 List only jobs in these states.
246 tasks
248 tasks => ['foo', 'bar']
249 List only jobs for these tasks.
251 These fields are currently available:
253 args
255 args => ['foo', 'bar']
256 Job arguments.
258 attempts
260 attempts => 25
261 Number of times performing this job will be attempted.
263 children
265 children => ['10026', '10027', '10028']
266 Jobs depending on this job.
268 created
270 created => 784111777
271 Epoch time job was created.
273 delayed
275 delayed => 784111777
276 Epoch time job was delayed to.
278 expires
280 expires => 784111777
281 Epoch time job is valid until before it expires.
283 finished
285 finished => 784111777
286 Epoch time job was finished.
288 id
290 id => 10025
291 Job id.
293 lax
295 lax => 0
296 Existing jobs this job depends on may also have failed to allow for
298 it to be processed.
299 notes
301 notes => {foo => 'bar', baz => [1, 2, 3]}
302 Hash reference with arbitrary metadata for this job.
304 parents
306 parents => ['10023', '10024', '10025']
307 Jobs this job depends on.
309 priority
311 priority => 3
312 Job priority.
314 queue
316 queue => 'important'
317 Queue name.
319 result
321 result => 'All went well!'
322 Job result.
324 retried
326 retried => 784111777
327 Epoch time job has been retried.
329 retries
331 retries => 3
332 Number of times job has been retried.
334 started
336 started => 784111777
337 Epoch time job was started.
339 state
341 state => 'inactive'
342 Current job state, usually "active", "failed", "finished" or
344 "inactive".
345 task
347 task => 'foo'
348 Task name.
350 time
352 time => 78411177
353 Server time.
355 worker
357 worker => '154'
358 Id of worker that is processing the job.
360 list_locks
362 my $results = $backend->list_locks($offset, $limit);
363 my $results = $backend->list_locks($offset, $limit, {names => ['foo']});
364 Returns information about locks in batches. Meant to be overloaded in a
366 subclass.
367 # Get the total number of results (without limit)
369 my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};
370 # Check expiration time
372 my $results = $backend->list_locks(0, 1, {names => ['foo']});
373 my $expires = $results->{locks}[0]{expires};
374 These options are currently available:
376 names
378 names => ['foo', 'bar']
379 List only locks with these names.
381 These fields are currently available:
383 expires
385 expires => 784111777
386 Epoch time this lock will expire.
388 name
390 name => 'foo'
391 Lock name.
393 list_workers
395 my $results = $backend->list_workers($offset, $limit);
396 my $results = $backend->list_workers($offset, $limit, {ids => [23]});
397 Returns information about workers in batches. Meant to be overloaded in
399 a subclass.
400 # Get the total number of results (without limit)
402 my $num = $backend->list_workers(0, 100)->{total};
403 # Check worker host
405 my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
406 my $host = $results->{workers}[0]{host};
407 These options are currently available:
409 before
411 before => 23
412 List only workers before this id.
414 ids
416 ids => ['23', '24']
417 List only workers with these ids.
419 These fields are currently available:
421 id
423 id => 22
424 Worker id.
426 host
428 host => 'localhost'
429 Worker host.
431 jobs
433 jobs => ['10023', '10024', '10025', '10029']
434 Ids of jobs the worker is currently processing.
436 notified
438 notified => 784111777
439 Epoch time worker sent the last heartbeat.
441 pid
443 pid => 12345
444 Process id of worker.
446 started
448 started => 784111777
449 Epoch time worker was started.
451 status
453 status => {queues => ['default', 'important']}
454 Hash reference with whatever status information the worker would like
456 to share.
457 lock
459 my $bool = $backend->lock('foo', 3600);
460 my $bool = $backend->lock('foo', 3600, {limit => 20});
461 Try to acquire a named lock that will expire automatically after the
463 given amount of time in seconds. An expiration time of 0 can be used to
464 check if a named lock already exists without creating one. Meant to be
465 overloaded in a subclass.
466 These options are currently available:
468 limit
470 limit => 20
471 Number of shared locks with the same name that can be active at the
473 same time, defaults to 1.
474 note
476 my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});
477 Change one or more metadata fields for a job. Setting a value to
479 "undef" will remove the field. Meant to be overloaded in a subclass.
480 receive
482 my $commands = $backend->receive($worker_id);
483 Receive remote control commands for worker. Meant to be overloaded in a
485 subclass.
486 register_worker
488 my $worker_id = $backend->register_worker;
489 my $worker_id = $backend->register_worker($worker_id);
490 my $worker_id = $backend->register_worker(
491 $worker_id, {status => {queues => ['default', 'important']}});
492 Register worker or send heartbeat to show that this worker is still
494 alive. Meant to be overloaded in a subclass.
495 These options are currently available:
497 status
499 status => {queues => ['default', 'important']}
500 Hash reference with whatever status information the worker would like
502 to share.
503 remove_job
505 my $bool = $backend->remove_job($job_id);
506 Remove "failed", "finished" or "inactive" job from queue. Meant to be
508 overloaded in a subclass.
509 repair
511 $backend->repair;
512 Repair worker registry and job queue if necessary. Meant to be
514 overloaded in a subclass.
515 reset
517 $backend->reset({all => 1});
518 Reset job queue. Meant to be overloaded in a subclass.
520 These options are currently available:
522 all
524 all => 1
525 Reset everything.
527 locks
529 locks => 1
530 Reset only locks.
532 retry_job
534 my $bool = $backend->retry_job($job_id, $retries);
535 my $bool = $backend->retry_job($job_id, $retries, {delay => 10});
536 Transition job back to "inactive" state, already "inactive" jobs may
538 also be retried to change options. Meant to be overloaded in a
539 subclass.
540 These options are currently available:
542 attempts
544 attempts => 25
545 Number of times performing this job will be attempted.
547 delay
549 delay => 10
550 Delay job for this many seconds (from now), defaults to 0.
552 expire
554 expire => 300
555 Job is valid for this many seconds (from now) before it expires.
557 lax
559 lax => 1
560 Existing jobs this job depends on may also have transitioned to the
562 "failed" state to allow for it to be processed, defaults to "false".
563 Note that this option is EXPERIMENTAL and might change without
564 warning!
565 parents
567 parents => [$id1, $id2, $id3]
568 Jobs this job depends on.
570 priority
572 priority => 5
573 Job priority.
575 queue
577 queue => 'important'
578 Queue to put job in.
580 stats
582 my $stats = $backend->stats;
583 Get statistics for the job queue. Meant to be overloaded in a subclass.
585 These fields are currently available:
587 active_jobs
589 active_jobs => 100
590 Number of jobs in "active" state.
592 active_locks
594 active_locks => 100
595 Number of active named locks.
597 active_workers
599 active_workers => 100
600 Number of workers that are currently processing a job.
602 delayed_jobs
604 delayed_jobs => 100
605 Number of jobs in "inactive" state that are scheduled to run at
607 specific time in the future or have unresolved dependencies.
608 enqueued_jobs
610 enqueued_jobs => 100000
611 Rough estimate of how many jobs have ever been enqueued.
613 failed_jobs
615 failed_jobs => 100
616 Number of jobs in "failed" state.
618 finished_jobs
620 finished_jobs => 100
621 Number of jobs in "finished" state.
623 inactive_jobs
625 inactive_jobs => 100
626 Number of jobs in "inactive" state.
628 inactive_workers
630 inactive_workers => 100
631 Number of workers that are currently not processing a job.
633 uptime
635 uptime => 1000
636 Uptime in seconds.
638 workers
640 workers => 200;
641 Number of registered workers.
643 unlock
645 my $bool = $backend->unlock('foo');
646 Release a named lock. Meant to be overloaded in a subclass.
648 unregister_worker
650 $backend->unregister_worker($worker_id);
651 Unregister worker. Meant to be overloaded in a subclass.
653
655 Minion, Minion::Guide, <https://minion.pm>, Mojolicious::Guides,
656 <https://mojolicious.org>.
657perl v5.36.0 2023-01-20 Minion::Backend(3)