--- name: "Minion::Job" section: "3pm" platform: "linux" package: "libminion-perl" version: "10.31+dfsg-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Minion::Job" --- # Minion::Job(3pm) Minion job ## NAME Minion::Job - Minion job ## SYNOPSIS ``` package MyApp::Task::Foo; use Mojo::Base 'Minion::Job', -signatures; sub run ($self, @args) { # Magic here! :) } ``` ## DESCRIPTION Minion::Job is a container for Minion jobs. ## EVENTS Minion::Job inherits all events from Mojo::EventEmitter and can emit the following new ones. ### cleanup ``` $job->on(cleanup => sub ($job) { ... }); ``` Emitted in the process performing this job right before the process will exit. ``` $job->on(cleanup => sub ($job) { $job->app->log->debug("Process $$ is about to exit"); }); ``` ### failed ``` $job->on(failed => sub ($job, $err) { ... }); ``` Emitted in the worker process managing this job or the process performing it, after it has transitioned to the `"failed"` state. ``` $job->on(failed => sub ($job, $err) { say "Something went wrong: $err"; }); ``` ### finish ``` $job->on(finish => sub ($job) { ... }); ``` Emitted in the process performing this job if the task was successful. ``` $job->on(finish => sub ($job) { my $id = $job->id; my $task = $job->task; $job->app->log->debug(qq{Job "$id" was performed with task "$task"}); }); ``` ### finished ``` $job->on(finished => sub ($job, $result) { ... }); ``` Emitted in the worker process managing this job or the process performing it, after it has transitioned to the `"finished"` state. ``` $job->on(finished => sub ($job, $result) { my $id = $job->id; say "Job $id is finished."; }); ``` ### reap ``` $job->on(reap => sub ($job, $pid) { ... }); ``` Emitted in the worker process managing this job, after the process performing it has exited. ``` $job->on(reap => sub ($job, $pid) { my $id = $job->id; say "Job $id ran in process $pid"; }); ``` ### spawn ``` $job->on(spawn => sub ($job, $pid) { ... }); ``` Emitted in the worker process managing this job, after a new process has been spawned for processing. ``` $job->on(spawn => sub ($job, $pid) { my $id = $job->id; say "Job $id running in process $pid"; }); ``` ### start ``` $job->on(start => sub ($job) { ... }); ``` Emitted in the process performing this job, after it has been spawned. ``` $job->on(start => sub ($job) { $0 = $job->id; }); ``` ## ATTRIBUTES Minion::Job implements the following attributes. ### args ``` my $args = $job->args; $job = $job->args([]); ``` Arguments passed to task. ### id ``` my $id = $job->id; $job = $job->id($id); ``` Job id. ### minion ``` my $minion = $job->minion; $job = $job->minion(Minion->new); ``` Minion object this job belongs to. ### retries ``` my $retries = $job->retries; $job = $job->retries(5); ``` Number of times job has been retried. ### task ``` my $task = $job->task; $job = $job->task('foo'); ``` Task name. ## METHODS Minion::Job inherits all methods from Mojo::EventEmitter and implements the following new ones. ### app ``` my $app = $job->app; ``` Get application from "app" in Minion. ``` # Longer version my $app = $job->minion->app; ``` ### execute ``` my $err = $job->execute; ``` Perform job in this process and return `"undef"` if the task was successful or an exception otherwise. Note that this method should only be used to implement custom workers. ``` # Perform job in foreground if (my $err = $job->execute) { $job->fail($err) } else { $job->finish } ``` ### fail ``` my $bool = $job->fail; my $bool = $job->fail('Something went wrong!'); my $bool = $job->fail({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. ### finish ``` my $bool = $job->finish; my $bool = $job->finish('All went well!'); my $bool = $job->finish({whatever => 'All went well!'}); ``` Transition from `"active"` to `"finished"` state with or without a result. ### info ``` my $info = $job->info; ``` Get job information. ``` # Check job state my $state = $job->info->{state}; # Get job metadata my $progress = $job->info->{notes}{progress}; # Get job result my $result = $job->info->{result}; ``` 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. - 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 => 784111777 ``` Server time. - worker ``` worker => '154' ``` Id of worker that is processing the job. ### is\_finished ``` my $bool = $job->is_finished; ``` Check if job performed with "start" is finished. Note that this method should only be used to implement custom workers. ### kill ``` $job->kill('INT'); ``` Send a signal to job performed with "start". Note that this method should only be used to implement custom workers. ### note ``` my $bool = $job->note(mojo => 'rocks', minion => 'too'); ``` Change one or more metadata fields for this job. Setting a value to `"undef"` will remove the field. The new values will get serialized by "backend" in Minion (often with Mojo::JSON), so you shouldn't send objects and be careful with binary data, nested data structures with hash and array references are fine though. ``` # Share progress information $job->note(progress => 95); # Share stats $job->note(stats => {utime => '0.012628', stime => '0.002429'}); ``` ### parents ``` my $parents = $job->parents; ``` Return a Mojo::Collection object containing all jobs this job depends on as Minion::Job objects. ``` # Check parent state for my $parent ($job->parents->each) { my $info = $parent->info; say "$info->{id}: $info->{state}"; } ``` ### perform ``` $job->perform; ``` Perform job in new process and wait for it to finish. Note that this method should only be used to implement custom workers. ### pid ``` my $pid = $job->pid; ``` Process id of the process spawned by "start" if available. Note that this method should only be used to implement custom workers. ### remove ``` my $bool = $job->remove; ``` Remove `"failed"`, `"finished"` or `"inactive"` job from queue. ### retry ``` my $bool = $job->retry; my $bool = $job->retry({delay => 10}); ``` Transition job back to `"inactive"` state, already `"inactive"` jobs may also be retried to change options. 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"`. Note that this option is **EXPERIMENTAL** and might change without warning! - parents ``` parents => [$id1, $id2, $id3] ``` Jobs this job depends on. - priority ``` priority => 5 ``` Job priority. - queue ``` queue => 'important' ``` Queue to put job in. ### run ``` $job->run(@args); ``` Task to perform by this job. Meant to be overloaded in a subclass to create a custom task class. Note that this method is **EXPERIMENTAL** and might change without warning! ### start ``` $job = $job->start; ``` Perform job in new process, but do not wait for it to finish. Note that this method should only be used to implement custom workers. ``` # Perform two jobs concurrently $job1->start; $job2->start; my ($first, $second); sleep 1 until $first ||= $job1->is_finished and $second ||= $job2->is_finished; ``` ### stop ``` $job->stop; ``` Stop job performed with "start" immediately. Note that this method should only be used to implement custom workers. ## SEE ALSO Minion, Minion::Guide, \, Mojolicious::Guides, \.