1Minion::Backend(3)    User Contributed Perl Documentation   Minion::Backend(3)
2
3
4

NAME

6       Minion::Backend - Backend base class
7

SYNOPSIS

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

DESCRIPTION

34       Minion::Backend is an abstract base class for Minion backends, like
35       Minion::Backend::Pg.
36

ATTRIBUTES

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

METHODS

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   unlock
640         my $bool = $backend->unlock('foo');
641
642       Release a named lock. Meant to be overloaded in a subclass.
643
644   unregister_worker
645         $backend->unregister_worker($worker_id);
646
647       Unregister worker. Meant to be overloaded in a subclass.
648

SEE ALSO

650       Minion, Minion::Guide, <https://minion.pm>, Mojolicious::Guides,
651       <https://mojolicious.org>.
652
653
654
655perl v5.34.0                      2022-01-20                Minion::Backend(3)
Impressum