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 queues
81 queues => ['important']
82 One or more queues to dequeue jobs from, defaults to "default".
84 These fields are currently available:
86 args
88 args => ['foo', 'bar']
89 Job arguments.
91 id
93 id => '10023'
94 Job ID.
96 retries
98 retries => 3
99 Number of times job has been retried.
101 task
103 task => 'foo'
104 Task name.
106 enqueue
108 my $job_id = $backend->enqueue('foo');
109 my $job_id = $backend->enqueue(foo => [@args]);
110 my $job_id = $backend->enqueue(foo => [@args] => {priority => 1});
111 Enqueue a new job with "inactive" state. Meant to be overloaded in a
113 subclass.
114 These options are currently available:
116 attempts
118 attempts => 25
119 Number of times performing this job will be attempted, with a delay
121 based on "backoff" in Minion after the first attempt, defaults to 1.
122 delay
124 delay => 10
125 Delay job for this many seconds (from now), defaults to 0.
127 expire
129 expire => 300
130 Job is valid for this many seconds (from now) before it expires. Note
132 that this option is EXPERIMENTAL and might change without warning!
133 lax
135 lax => 1
136 Existing jobs this job depends on may also have transitioned to the
138 "failed" state to allow for it to be processed, defaults to "false".
139 Note that this option is EXPERIMENTAL and might change without
140 warning!
141 notes
143 notes => {foo => 'bar', baz => [1, 2, 3]}
144 Hash reference with arbitrary metadata for this job.
146 parents
148 parents => [$id1, $id2, $id3]
149 One or more existing jobs this job depends on, and that need to have
151 transitioned to the state "finished" before it can be processed.
152 priority
154 priority => 5
155 Job priority, defaults to 0. Jobs with a higher priority get
157 performed first.
158 queue
160 queue => 'important'
161 Queue to put job in, defaults to "default".
163 fail_job
165 my $bool = $backend->fail_job($job_id, $retries);
166 my $bool = $backend->fail_job($job_id, $retries, 'Something went wrong!');
167 my $bool = $backend->fail_job(
168 $job_id, $retries, {whatever => 'Something went wrong!'});
169 Transition from "active" to "failed" state with or without a result,
171 and if there are attempts remaining, transition back to "inactive" with
172 a delay based on "backoff" in Minion. Meant to be overloaded in a
173 subclass.
174 finish_job
176 my $bool = $backend->finish_job($job_id, $retries);
177 my $bool = $backend->finish_job($job_id, $retries, 'All went well!');
178 my $bool = $backend->finish_job(
179 $job_id, $retries, {whatever => 'All went well!'});
180 Transition from "active" to "finished" state with or without a result.
182 Meant to be overloaded in a subclass.
183 history
185 my $history = $backend->history;
186 Get history information for job queue. Meant to be overloaded in a
188 subclass.
189 These fields are currently available:
191 daily
193 daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...]
194 Hourly counts for processed jobs from the past day.
196 list_jobs
198 my $results = $backend->list_jobs($offset, $limit);
199 my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});
200 Returns the information about jobs in batches. Meant to be overloaded
202 in a subclass.
203 # Get the total number of results (without limit)
205 my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};
206 # Check job state
208 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
209 my $state = $results->{jobs}[0]{state};
210 # Get job result
212 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
213 my $result = $results->{jobs}[0]{result};
214 These options are currently available:
216 before
218 before => 23
219 List only jobs before this id.
221 ids
223 ids => ['23', '24']
224 List only jobs with these ids.
226 notes
228 notes => ['foo', 'bar']
229 List only jobs with one of these notes.
231 queues
233 queues => ['important', 'unimportant']
234 List only jobs in these queues.
236 states
238 states => ['inactive', 'active']
239 List only jobs in these states.
241 tasks
243 tasks => ['foo', 'bar']
244 List only jobs for these tasks.
246 These fields are currently available:
248 args
250 args => ['foo', 'bar']
251 Job arguments.
253 attempts
255 attempts => 25
256 Number of times performing this job will be attempted.
258 children
260 children => ['10026', '10027', '10028']
261 Jobs depending on this job.
263 created
265 created => 784111777
266 Epoch time job was created.
268 delayed
270 delayed => 784111777
271 Epoch time job was delayed to.
273 expires
275 expires => 784111777
276 Epoch time job is valid until before it expires.
278 finished
280 finished => 784111777
281 Epoch time job was finished.
283 id
285 id => 10025
286 Job id.
288 lax
290 lax => 0
291 Existing jobs this job depends on may also have failed to allow for
293 it to be processed.
294 notes
296 notes => {foo => 'bar', baz => [1, 2, 3]}
297 Hash reference with arbitrary metadata for this job.
299 parents
301 parents => ['10023', '10024', '10025']
302 Jobs this job depends on.
304 priority
306 priority => 3
307 Job priority.
309 queue
311 queue => 'important'
312 Queue name.
314 result
316 result => 'All went well!'
317 Job result.
319 retried
321 retried => 784111777
322 Epoch time job has been retried.
324 retries
326 retries => 3
327 Number of times job has been retried.
329 started
331 started => 784111777
332 Epoch time job was started.
334 state
336 state => 'inactive'
337 Current job state, usually "active", "failed", "finished" or
339 "inactive".
340 task
342 task => 'foo'
343 Task name.
345 time
347 time => 78411177
348 Server time.
350 worker
352 worker => '154'
353 Id of worker that is processing the job.
355 list_locks
357 my $results = $backend->list_locks($offset, $limit);
358 my $results = $backend->list_locks($offset, $limit, {names => ['foo']});
359 Returns information about locks in batches. Meant to be overloaded in a
361 subclass.
362 # Get the total number of results (without limit)
364 my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};
365 # Check expiration time
367 my $results = $backend->list_locks(0, 1, {names => ['foo']});
368 my $expires = $results->{locks}[0]{expires};
369 These options are currently available:
371 names
373 names => ['foo', 'bar']
374 List only locks with these names.
376 These fields are currently available:
378 expires
380 expires => 784111777
381 Epoch time this lock will expire.
383 name
385 name => 'foo'
386 Lock name.
388 list_workers
390 my $results = $backend->list_workers($offset, $limit);
391 my $results = $backend->list_workers($offset, $limit, {ids => [23]});
392 Returns information about workers in batches. Meant to be overloaded in
394 a subclass.
395 # Get the total number of results (without limit)
397 my $num = $backend->list_workers(0, 100)->{total};
398 # Check worker host
400 my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
401 my $host = $results->{workers}[0]{host};
402 These options are currently available:
404 before
406 before => 23
407 List only workers before this id.
409 ids
411 ids => ['23', '24']
412 List only workers with these ids.
414 These fields are currently available:
416 id
418 id => 22
419 Worker id.
421 host
423 host => 'localhost'
424 Worker host.
426 jobs
428 jobs => ['10023', '10024', '10025', '10029']
429 Ids of jobs the worker is currently processing.
431 notified
433 notified => 784111777
434 Epoch time worker sent the last heartbeat.
436 pid
438 pid => 12345
439 Process id of worker.
441 started
443 started => 784111777
444 Epoch time worker was started.
446 status
448 status => {queues => ['default', 'important']}
449 Hash reference with whatever status information the worker would like
451 to share.
452 lock
454 my $bool = $backend->lock('foo', 3600);
455 my $bool = $backend->lock('foo', 3600, {limit => 20});
456 Try to acquire a named lock that will expire automatically after the
458 given amount of time in seconds. An expiration time of 0 can be used to
459 check if a named lock already exists without creating one. Meant to be
460 overloaded in a subclass.
461 These options are currently available:
463 limit
465 limit => 20
466 Number of shared locks with the same name that can be active at the
468 same time, defaults to 1.
469 note
471 my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});
472 Change one or more metadata fields for a job. Setting a value to
474 "undef" will remove the field. Meant to be overloaded in a subclass.
475 receive
477 my $commands = $backend->receive($worker_id);
478 Receive remote control commands for worker. Meant to be overloaded in a
480 subclass.
481 register_worker
483 my $worker_id = $backend->register_worker;
484 my $worker_id = $backend->register_worker($worker_id);
485 my $worker_id = $backend->register_worker(
486 $worker_id, {status => {queues => ['default', 'important']}});
487 Register worker or send heartbeat to show that this worker is still
489 alive. Meant to be overloaded in a subclass.
490 These options are currently available:
492 status
494 status => {queues => ['default', 'important']}
495 Hash reference with whatever status information the worker would like
497 to share.
498 remove_job
500 my $bool = $backend->remove_job($job_id);
501 Remove "failed", "finished" or "inactive" job from queue. Meant to be
503 overloaded in a subclass.
504 repair
506 $backend->repair;
507 Repair worker registry and job queue if necessary. Meant to be
509 overloaded in a subclass.
510 reset
512 $backend->reset({all => 1});
513 Reset job queue. Meant to be overloaded in a subclass.
515 These options are currently available:
517 all
519 all => 1
520 Reset everything.
522 locks
524 locks => 1
525 Reset only locks.
527 retry_job
529 my $bool = $backend->retry_job($job_id, $retries);
530 my $bool = $backend->retry_job($job_id, $retries, {delay => 10});
531 Transition job back to "inactive" state, already "inactive" jobs may
533 also be retried to change options. Meant to be overloaded in a
534 subclass.
535 These options are currently available:
537 attempts
539 attempts => 25
540 Number of times performing this job will be attempted.
542 delay
544 delay => 10
545 Delay job for this many seconds (from now), defaults to 0.
547 expire
549 expire => 300
550 Job is valid for this many seconds (from now) before it expires. Note
552 that this option is EXPERIMENTAL and might change without warning!
553 lax
555 lax => 1
556 Existing jobs this job depends on may also have transitioned to the
558 "failed" state to allow for it to be processed, defaults to "false".
559 Note that this option is EXPERIMENTAL and might change without
560 warning!
561 parents
563 parents => [$id1, $id2, $id3]
564 Jobs this job depends on.
566 priority
568 priority => 5
569 Job priority.
571 queue
573 queue => 'important'
574 Queue to put job in.
576 stats
578 my $stats = $backend->stats;
579 Get statistics for the job queue. Meant to be overloaded in a subclass.
581 These fields are currently available:
583 active_jobs
585 active_jobs => 100
586 Number of jobs in "active" state.
588 active_locks
590 active_locks => 100
591 Number of active named locks.
593 active_workers
595 active_workers => 100
596 Number of workers that are currently processing a job.
598 delayed_jobs
600 delayed_jobs => 100
601 Number of jobs in "inactive" state that are scheduled to run at
603 specific time in the future or have unresolved dependencies.
604 enqueued_jobs
606 enqueued_jobs => 100000
607 Rough estimate of how many jobs have ever been enqueued.
609 failed_jobs
611 failed_jobs => 100
612 Number of jobs in "failed" state.
614 finished_jobs
616 finished_jobs => 100
617 Number of jobs in "finished" state.
619 inactive_jobs
621 inactive_jobs => 100
622 Number of jobs in "inactive" state.
624 inactive_workers
626 inactive_workers => 100
627 Number of workers that are currently not processing a job.
629 uptime
631 uptime => 1000
632 Uptime in seconds.
634 unlock
636 my $bool = $backend->unlock('foo');
637 Release a named lock. Meant to be overloaded in a subclass.
639 unregister_worker
641 $backend->unregister_worker($worker_id);
642 Unregister worker. Meant to be overloaded in a subclass.
644
646 Minion, <https://minion.pm>, Mojolicious::Guides,
647 <https://mojolicious.org>.
648perl v5.32.0 2020-08-02 Minion::Backend(3)