1Minion::Backend(3) User Contributed Perl Documentation Minion::Backend(3)
2
3
4
6 Minion::Backend - Backend base class
7
9 package Minion::Backend::MyBackend;
10 use Mojo::Base 'Minion::Backend';
11
12 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
40 minion
41 my $minion = $backend->minion;
42 $backend = $backend->minion(Minion->new);
43
44 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
51 auto_retry_job
52 my $bool = $backend->auto_retry_job($job_id, $retries, $attempts);
53
54 Automatically "retry" job with "backoff" in Minion if there are
55 attempts left, used to implement backends like Minion::Backend::Pg.
56
57 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
62 Broadcast remote control command to one or more workers. Meant to be
63 overloaded in a subclass.
64
65 dequeue
66 my $job_info = $backend->dequeue($worker_id, 0.5);
67 my $job_info = $backend->dequeue($worker_id, 0.5, {queues => ['important']});
68
69 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
73 These options are currently available:
74
75 id
76 id => '10023'
77
78 Dequeue a specific job.
79
80 min_priority
81 min_priority => 3
82
83 Do not dequeue jobs with a lower priority.
84
85 queues
86 queues => ['important']
87
88 One or more queues to dequeue jobs from, defaults to "default".
89
90 These fields are currently available:
91
92 args
93 args => ['foo', 'bar']
94
95 Job arguments.
96
97 id
98 id => '10023'
99
100 Job ID.
101
102 retries
103 retries => 3
104
105 Number of times job has been retried.
106
107 task
108 task => 'foo'
109
110 Task name.
111
112 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
117 Enqueue a new job with "inactive" state. Meant to be overloaded in a
118 subclass.
119
120 These options are currently available:
121
122 attempts
123 attempts => 25
124
125 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
128 delay
129 delay => 10
130
131 Delay job for this many seconds (from now), defaults to 0.
132
133 expire
134 expire => 300
135
136 Job is valid for this many seconds (from now) before it expires.
137
138 lax
139 lax => 1
140
141 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
146 notes
147 notes => {foo => 'bar', baz => [1, 2, 3]}
148
149 Hash reference with arbitrary metadata for this job.
150
151 parents
152 parents => [$id1, $id2, $id3]
153
154 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
157 priority
158 priority => 5
159
160 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
164 queue
165 queue => 'important'
166
167 Queue to put job in, defaults to "default".
168
169 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
175 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
180 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
186 Transition from "active" to "finished" state with or without a result.
187 Meant to be overloaded in a subclass.
188
189 history
190 my $history = $backend->history;
191
192 Get history information for job queue. Meant to be overloaded in a
193 subclass.
194
195 These fields are currently available:
196
197 daily
198 daily => [{epoch => 12345, finished_jobs => 95, failed_jobs => 2}, ...]
199
200 Hourly counts for processed jobs from the past day.
201
202 list_jobs
203 my $results = $backend->list_jobs($offset, $limit);
204 my $results = $backend->list_jobs($offset, $limit, {states => ['inactive']});
205
206 Returns the information about jobs in batches. Meant to be overloaded
207 in a subclass.
208
209 # Get the total number of results (without limit)
210 my $num = $backend->list_jobs(0, 100, {queues => ['important']})->{total};
211
212 # Check job state
213 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
214 my $state = $results->{jobs}[0]{state};
215
216 # Get job result
217 my $results = $backend->list_jobs(0, 1, {ids => [$job_id]});
218 my $result = $results->{jobs}[0]{result};
219
220 These options are currently available:
221
222 before
223 before => 23
224
225 List only jobs before this id.
226
227 ids
228 ids => ['23', '24']
229
230 List only jobs with these ids.
231
232 notes
233 notes => ['foo', 'bar']
234
235 List only jobs with one of these notes.
236
237 queues
238 queues => ['important', 'unimportant']
239
240 List only jobs in these queues.
241
242 states
243 states => ['inactive', 'active']
244
245 List only jobs in these states.
246
247 tasks
248 tasks => ['foo', 'bar']
249
250 List only jobs for these tasks.
251
252 These fields are currently available:
253
254 args
255 args => ['foo', 'bar']
256
257 Job arguments.
258
259 attempts
260 attempts => 25
261
262 Number of times performing this job will be attempted.
263
264 children
265 children => ['10026', '10027', '10028']
266
267 Jobs depending on this job.
268
269 created
270 created => 784111777
271
272 Epoch time job was created.
273
274 delayed
275 delayed => 784111777
276
277 Epoch time job was delayed to.
278
279 expires
280 expires => 784111777
281
282 Epoch time job is valid until before it expires.
283
284 finished
285 finished => 784111777
286
287 Epoch time job was finished.
288
289 id
290 id => 10025
291
292 Job id.
293
294 lax
295 lax => 0
296
297 Existing jobs this job depends on may also have failed to allow for
298 it to be processed.
299
300 notes
301 notes => {foo => 'bar', baz => [1, 2, 3]}
302
303 Hash reference with arbitrary metadata for this job.
304
305 parents
306 parents => ['10023', '10024', '10025']
307
308 Jobs this job depends on.
309
310 priority
311 priority => 3
312
313 Job priority.
314
315 queue
316 queue => 'important'
317
318 Queue name.
319
320 result
321 result => 'All went well!'
322
323 Job result.
324
325 retried
326 retried => 784111777
327
328 Epoch time job has been retried.
329
330 retries
331 retries => 3
332
333 Number of times job has been retried.
334
335 started
336 started => 784111777
337
338 Epoch time job was started.
339
340 state
341 state => 'inactive'
342
343 Current job state, usually "active", "failed", "finished" or
344 "inactive".
345
346 task
347 task => 'foo'
348
349 Task name.
350
351 time
352 time => 78411177
353
354 Server time.
355
356 worker
357 worker => '154'
358
359 Id of worker that is processing the job.
360
361 list_locks
362 my $results = $backend->list_locks($offset, $limit);
363 my $results = $backend->list_locks($offset, $limit, {names => ['foo']});
364
365 Returns information about locks in batches. Meant to be overloaded in a
366 subclass.
367
368 # Get the total number of results (without limit)
369 my $num = $backend->list_locks(0, 100, {names => ['bar']})->{total};
370
371 # Check expiration time
372 my $results = $backend->list_locks(0, 1, {names => ['foo']});
373 my $expires = $results->{locks}[0]{expires};
374
375 These options are currently available:
376
377 names
378 names => ['foo', 'bar']
379
380 List only locks with these names.
381
382 These fields are currently available:
383
384 expires
385 expires => 784111777
386
387 Epoch time this lock will expire.
388
389 name
390 name => 'foo'
391
392 Lock name.
393
394 list_workers
395 my $results = $backend->list_workers($offset, $limit);
396 my $results = $backend->list_workers($offset, $limit, {ids => [23]});
397
398 Returns information about workers in batches. Meant to be overloaded in
399 a subclass.
400
401 # Get the total number of results (without limit)
402 my $num = $backend->list_workers(0, 100)->{total};
403
404 # Check worker host
405 my $results = $backend->list_workers(0, 1, {ids => [$worker_id]});
406 my $host = $results->{workers}[0]{host};
407
408 These options are currently available:
409
410 before
411 before => 23
412
413 List only workers before this id.
414
415 ids
416 ids => ['23', '24']
417
418 List only workers with these ids.
419
420 These fields are currently available:
421
422 id
423 id => 22
424
425 Worker id.
426
427 host
428 host => 'localhost'
429
430 Worker host.
431
432 jobs
433 jobs => ['10023', '10024', '10025', '10029']
434
435 Ids of jobs the worker is currently processing.
436
437 notified
438 notified => 784111777
439
440 Epoch time worker sent the last heartbeat.
441
442 pid
443 pid => 12345
444
445 Process id of worker.
446
447 started
448 started => 784111777
449
450 Epoch time worker was started.
451
452 status
453 status => {queues => ['default', 'important']}
454
455 Hash reference with whatever status information the worker would like
456 to share.
457
458 lock
459 my $bool = $backend->lock('foo', 3600);
460 my $bool = $backend->lock('foo', 3600, {limit => 20});
461
462 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
467 These options are currently available:
468
469 limit
470 limit => 20
471
472 Number of shared locks with the same name that can be active at the
473 same time, defaults to 1.
474
475 note
476 my $bool = $backend->note($job_id, {mojo => 'rocks', minion => 'too'});
477
478 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
481 receive
482 my $commands = $backend->receive($worker_id);
483
484 Receive remote control commands for worker. Meant to be overloaded in a
485 subclass.
486
487 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
493 Register worker or send heartbeat to show that this worker is still
494 alive. Meant to be overloaded in a subclass.
495
496 These options are currently available:
497
498 status
499 status => {queues => ['default', 'important']}
500
501 Hash reference with whatever status information the worker would like
502 to share.
503
504 remove_job
505 my $bool = $backend->remove_job($job_id);
506
507 Remove "failed", "finished" or "inactive" job from queue. Meant to be
508 overloaded in a subclass.
509
510 repair
511 $backend->repair;
512
513 Repair worker registry and job queue if necessary. Meant to be
514 overloaded in a subclass.
515
516 reset
517 $backend->reset({all => 1});
518
519 Reset job queue. Meant to be overloaded in a subclass.
520
521 These options are currently available:
522
523 all
524 all => 1
525
526 Reset everything.
527
528 locks
529 locks => 1
530
531 Reset only locks.
532
533 retry_job
534 my $bool = $backend->retry_job($job_id, $retries);
535 my $bool = $backend->retry_job($job_id, $retries, {delay => 10});
536
537 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
541 These options are currently available:
542
543 attempts
544 attempts => 25
545
546 Number of times performing this job will be attempted.
547
548 delay
549 delay => 10
550
551 Delay job for this many seconds (from now), defaults to 0.
552
553 expire
554 expire => 300
555
556 Job is valid for this many seconds (from now) before it expires.
557
558 lax
559 lax => 1
560
561 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
566 parents
567 parents => [$id1, $id2, $id3]
568
569 Jobs this job depends on.
570
571 priority
572 priority => 5
573
574 Job priority.
575
576 queue
577 queue => 'important'
578
579 Queue to put job in.
580
581 stats
582 my $stats = $backend->stats;
583
584 Get statistics for the job queue. Meant to be overloaded in a subclass.
585
586 These fields are currently available:
587
588 active_jobs
589 active_jobs => 100
590
591 Number of jobs in "active" state.
592
593 active_locks
594 active_locks => 100
595
596 Number of active named locks.
597
598 active_workers
599 active_workers => 100
600
601 Number of workers that are currently processing a job.
602
603 delayed_jobs
604 delayed_jobs => 100
605
606 Number of jobs in "inactive" state that are scheduled to run at
607 specific time in the future or have unresolved dependencies.
608
609 enqueued_jobs
610 enqueued_jobs => 100000
611
612 Rough estimate of how many jobs have ever been enqueued.
613
614 failed_jobs
615 failed_jobs => 100
616
617 Number of jobs in "failed" state.
618
619 finished_jobs
620 finished_jobs => 100
621
622 Number of jobs in "finished" state.
623
624 inactive_jobs
625 inactive_jobs => 100
626
627 Number of jobs in "inactive" state.
628
629 inactive_workers
630 inactive_workers => 100
631
632 Number of workers that are currently not processing a job.
633
634 uptime
635 uptime => 1000
636
637 Uptime in seconds.
638
639 workers
640 workers => 200;
641
642 Number of registered workers.
643
644 unlock
645 my $bool = $backend->unlock('foo');
646
647 Release a named lock. Meant to be overloaded in a subclass.
648
649 unregister_worker
650 $backend->unregister_worker($worker_id);
651
652 Unregister worker. Meant to be overloaded in a subclass.
653
655 Minion, Minion::Guide, <https://minion.pm>, Mojolicious::Guides,
656 <https://mojolicious.org>.
657
658
659
660perl v5.36.0 2022-07-22 Minion::Backend(3)