.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Minion::Job 3pm"
.TH Minion::Job 3pm "2021-03-29" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Minion::Job \- Minion job
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package MyApp::Task::Foo;
\&  use Mojo::Base \*(AqMinion::Job\*(Aq, \-signatures;
\&
\&  sub run ($self, @args) {
\&
\&    # Magic here! :)
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Minion::Job is a container for Minion jobs.
.SH "EVENTS"
.IX Header "EVENTS"
Minion::Job inherits all events from Mojo::EventEmitter and can emit the following new ones.
.SS "cleanup"
.IX Subsection "cleanup"
.Vb 3
\&  $job\->on(cleanup => sub ($job) {
\&    ...
\&  });
.Ve
.PP
Emitted in the process performing this job right before the process will exit.
.PP
.Vb 3
\&  $job\->on(cleanup => sub ($job) {
\&    $job\->app\->log\->debug("Process $$ is about to exit");
\&  });
.Ve
.SS "failed"
.IX Subsection "failed"
.Vb 3
\&  $job\->on(failed => sub ($job, $err) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process managing this job or the process performing it, after it has transitioned to the
\&\f(CW\*(C`failed\*(C'\fR state.
.PP
.Vb 3
\&  $job\->on(failed => sub ($job, $err) {
\&    say "Something went wrong: $err";
\&  });
.Ve
.SS "finish"
.IX Subsection "finish"
.Vb 3
\&  $job\->on(finish => sub ($job) {
\&    ...
\&  });
.Ve
.PP
Emitted in the process performing this job if the task was successful.
.PP
.Vb 5
\&  $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"});
\&  });
.Ve
.SS "finished"
.IX Subsection "finished"
.Vb 3
\&  $job\->on(finished => sub ($job, $result) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process managing this job or the process performing it, after it has transitioned to the
\&\f(CW\*(C`finished\*(C'\fR state.
.PP
.Vb 4
\&  $job\->on(finished => sub ($job, $result) {
\&    my $id = $job\->id;
\&    say "Job $id is finished.";
\&  });
.Ve
.SS "reap"
.IX Subsection "reap"
.Vb 3
\&  $job\->on(reap => sub ($job, $pid) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process managing this job, after the process performing it has exited.
.PP
.Vb 4
\&  $job\->on(reap => sub ($job, $pid) {
\&    my $id = $job\->id;
\&    say "Job $id ran in process $pid";
\&  });
.Ve
.SS "spawn"
.IX Subsection "spawn"
.Vb 3
\&  $job\->on(spawn => sub ($job, $pid) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process managing this job, after a new process has been spawned for processing.
.PP
.Vb 4
\&  $job\->on(spawn => sub ($job, $pid) {
\&    my $id = $job\->id;
\&    say "Job $id running in process $pid";
\&  });
.Ve
.SS "start"
.IX Subsection "start"
.Vb 3
\&  $job\->on(start => sub ($job) {
\&    ...
\&  });
.Ve
.PP
Emitted in the process performing this job, after it has been spawned.
.PP
.Vb 3
\&  $job\->on(start => sub ($job) {
\&    $0 = $job\->id;
\&  });
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Minion::Job implements the following attributes.
.SS "args"
.IX Subsection "args"
.Vb 2
\&  my $args = $job\->args;
\&  $job     = $job\->args([]);
.Ve
.PP
Arguments passed to task.
.SS "id"
.IX Subsection "id"
.Vb 2
\&  my $id = $job\->id;
\&  $job   = $job\->id($id);
.Ve
.PP
Job id.
.SS "minion"
.IX Subsection "minion"
.Vb 2
\&  my $minion = $job\->minion;
\&  $job       = $job\->minion(Minion\->new);
.Ve
.PP
Minion object this job belongs to.
.SS "retries"
.IX Subsection "retries"
.Vb 2
\&  my $retries = $job\->retries;
\&  $job        = $job\->retries(5);
.Ve
.PP
Number of times job has been retried.
.SS "task"
.IX Subsection "task"
.Vb 2
\&  my $task = $job\->task;
\&  $job     = $job\->task(\*(Aqfoo\*(Aq);
.Ve
.PP
Task name.
.SH "METHODS"
.IX Header "METHODS"
Minion::Job inherits all methods from Mojo::EventEmitter and implements the following new ones.
.SS "app"
.IX Subsection "app"
.Vb 1
\&  my $app = $job\->app;
.Ve
.PP
Get application from \*(L"app\*(R" in Minion.
.PP
.Vb 2
\&  # Longer version
\&  my $app = $job\->minion\->app;
.Ve
.SS "execute"
.IX Subsection "execute"
.Vb 1
\&  my $err = $job\->execute;
.Ve
.PP
Perform job in this process and return \f(CW\*(C`undef\*(C'\fR if the task was successful or an exception otherwise.  Note that this
method should only be used to implement custom workers.
.PP
.Vb 3
\&  # Perform job in foreground
\&  if (my $err = $job\->execute) { $job\->fail($err) }
\&  else                         { $job\->finish }
.Ve
.SS "fail"
.IX Subsection "fail"
.Vb 3
\&  my $bool = $job\->fail;
\&  my $bool = $job\->fail(\*(AqSomething went wrong!\*(Aq);
\&  my $bool = $job\->fail({whatever => \*(AqSomething went wrong!\*(Aq});
.Ve
.PP
Transition from \f(CW\*(C`active\*(C'\fR to \f(CW\*(C`failed\*(C'\fR state with or without a result, and if there are attempts remaining, transition
back to \f(CW\*(C`inactive\*(C'\fR with a delay based on \*(L"backoff\*(R" in Minion.
.SS "finish"
.IX Subsection "finish"
.Vb 3
\&  my $bool = $job\->finish;
\&  my $bool = $job\->finish(\*(AqAll went well!\*(Aq);
\&  my $bool = $job\->finish({whatever => \*(AqAll went well!\*(Aq});
.Ve
.PP
Transition from \f(CW\*(C`active\*(C'\fR to \f(CW\*(C`finished\*(C'\fR state with or without a result.
.SS "info"
.IX Subsection "info"
.Vb 1
\&  my $info = $job\->info;
.Ve
.PP
Get job information.
.PP
.Vb 2
\&  # 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};
.Ve
.PP
These fields are currently available:
.IP "args" 2
.IX Item "args"
.Vb 1
\&  args => [\*(Aqfoo\*(Aq, \*(Aqbar\*(Aq]
.Ve
.Sp
Job arguments.
.IP "attempts" 2
.IX Item "attempts"
.Vb 1
\&  attempts => 25
.Ve
.Sp
Number of times performing this job will be attempted.
.IP "children" 2
.IX Item "children"
.Vb 1
\&  children => [\*(Aq10026\*(Aq, \*(Aq10027\*(Aq, \*(Aq10028\*(Aq]
.Ve
.Sp
Jobs depending on this job.
.IP "created" 2
.IX Item "created"
.Vb 1
\&  created => 784111777
.Ve
.Sp
Epoch time job was created.
.IP "delayed" 2
.IX Item "delayed"
.Vb 1
\&  delayed => 784111777
.Ve
.Sp
Epoch time job was delayed to.
.IP "expires" 2
.IX Item "expires"
.Vb 1
\&  expires => 784111777
.Ve
.Sp
Epoch time job is valid until before it expires.
.IP "finished" 2
.IX Item "finished"
.Vb 1
\&  finished => 784111777
.Ve
.Sp
Epoch time job was finished.
.IP "lax" 2
.IX Item "lax"
.Vb 1
\&  lax => 0
.Ve
.Sp
Existing jobs this job depends on may also have failed to allow for it to be processed.
.IP "notes" 2
.IX Item "notes"
.Vb 1
\&  notes => {foo => \*(Aqbar\*(Aq, baz => [1, 2, 3]}
.Ve
.Sp
Hash reference with arbitrary metadata for this job.
.IP "parents" 2
.IX Item "parents"
.Vb 1
\&  parents => [\*(Aq10023\*(Aq, \*(Aq10024\*(Aq, \*(Aq10025\*(Aq]
.Ve
.Sp
Jobs this job depends on.
.IP "priority" 2
.IX Item "priority"
.Vb 1
\&  priority => 3
.Ve
.Sp
Job priority.
.IP "queue" 2
.IX Item "queue"
.Vb 1
\&  queue => \*(Aqimportant\*(Aq
.Ve
.Sp
Queue name.
.IP "result" 2
.IX Item "result"
.Vb 1
\&  result => \*(AqAll went well!\*(Aq
.Ve
.Sp
Job result.
.IP "retried" 2
.IX Item "retried"
.Vb 1
\&  retried => 784111777
.Ve
.Sp
Epoch time job has been retried.
.IP "retries" 2
.IX Item "retries"
.Vb 1
\&  retries => 3
.Ve
.Sp
Number of times job has been retried.
.IP "started" 2
.IX Item "started"
.Vb 1
\&  started => 784111777
.Ve
.Sp
Epoch time job was started.
.IP "state" 2
.IX Item "state"
.Vb 1
\&  state => \*(Aqinactive\*(Aq
.Ve
.Sp
Current job state, usually \f(CW\*(C`active\*(C'\fR, \f(CW\*(C`failed\*(C'\fR, \f(CW\*(C`finished\*(C'\fR or \f(CW\*(C`inactive\*(C'\fR.
.IP "task" 2
.IX Item "task"
.Vb 1
\&  task => \*(Aqfoo\*(Aq
.Ve
.Sp
Task name.
.IP "time" 2
.IX Item "time"
.Vb 1
\&  time => 784111777
.Ve
.Sp
Server time.
.IP "worker" 2
.IX Item "worker"
.Vb 1
\&  worker => \*(Aq154\*(Aq
.Ve
.Sp
Id of worker that is processing the job.
.SS "is_finished"
.IX Subsection "is_finished"
.Vb 1
\&  my $bool = $job\->is_finished;
.Ve
.PP
Check if job performed with \*(L"start\*(R" is finished. Note that this method should only be used to implement custom
workers.
.SS "kill"
.IX Subsection "kill"
.Vb 1
\&  $job\->kill(\*(AqINT\*(Aq);
.Ve
.PP
Send a signal to job performed with \*(L"start\*(R". Note that this method should only be used to implement custom workers.
.SS "note"
.IX Subsection "note"
.Vb 1
\&  my $bool = $job\->note(mojo => \*(Aqrocks\*(Aq, minion => \*(Aqtoo\*(Aq);
.Ve
.PP
Change one or more metadata fields for this job. Setting a value to \f(CW\*(C`undef\*(C'\fR will remove the field. The new values will
get serialized by \*(L"backend\*(R" 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.
.PP
.Vb 2
\&  # Share progress information
\&  $job\->note(progress => 95);
\&
\&  # Share stats
\&  $job\->note(stats => {utime => \*(Aq0.012628\*(Aq, stime => \*(Aq0.002429\*(Aq});
.Ve
.SS "parents"
.IX Subsection "parents"
.Vb 1
\&  my $parents = $job\->parents;
.Ve
.PP
Return a Mojo::Collection object containing all jobs this job depends on as Minion::Job objects.
.PP
.Vb 5
\&  # Check parent state
\&  for my $parent ($job\->parents\->each) {
\&    my $info = $parent\->info;
\&    say "$info\->{id}: $info\->{state}";
\&  }
.Ve
.SS "perform"
.IX Subsection "perform"
.Vb 1
\&  $job\->perform;
.Ve
.PP
Perform job in new process and wait for it to finish. Note that this method should only be used to implement custom
workers.
.SS "pid"
.IX Subsection "pid"
.Vb 1
\&  my $pid = $job\->pid;
.Ve
.PP
Process id of the process spawned by \*(L"start\*(R" if available. Note that this method should only be used to implement
custom workers.
.SS "remove"
.IX Subsection "remove"
.Vb 1
\&  my $bool = $job\->remove;
.Ve
.PP
Remove \f(CW\*(C`failed\*(C'\fR, \f(CW\*(C`finished\*(C'\fR or \f(CW\*(C`inactive\*(C'\fR job from queue.
.SS "retry"
.IX Subsection "retry"
.Vb 2
\&  my $bool = $job\->retry;
\&  my $bool = $job\->retry({delay => 10});
.Ve
.PP
Transition job back to \f(CW\*(C`inactive\*(C'\fR state, already \f(CW\*(C`inactive\*(C'\fR jobs may also be retried to change options.
.PP
These options are currently available:
.IP "attempts" 2
.IX Item "attempts"
.Vb 1
\&  attempts => 25
.Ve
.Sp
Number of times performing this job will be attempted.
.IP "delay" 2
.IX Item "delay"
.Vb 1
\&  delay => 10
.Ve
.Sp
Delay job for this many seconds (from now), defaults to \f(CW0\fR.
.IP "expire" 2
.IX Item "expire"
.Vb 1
\&  expire => 300
.Ve
.Sp
Job is valid for this many seconds (from now) before it expires. Note that this option is \fB\s-1EXPERIMENTAL\s0\fR and might
change without warning!
.IP "lax" 2
.IX Item "lax"
.Vb 1
\&  lax => 1
.Ve
.Sp
Existing jobs this job depends on may also have transitioned to the \f(CW\*(C`failed\*(C'\fR state to allow for it to be processed,
defaults to \f(CW\*(C`false\*(C'\fR. Note that this option is \fB\s-1EXPERIMENTAL\s0\fR and might change without warning!
.IP "parents" 2
.IX Item "parents"
.Vb 1
\&  parents => [$id1, $id2, $id3]
.Ve
.Sp
Jobs this job depends on.
.IP "priority" 2
.IX Item "priority"
.Vb 1
\&  priority => 5
.Ve
.Sp
Job priority.
.IP "queue" 2
.IX Item "queue"
.Vb 1
\&  queue => \*(Aqimportant\*(Aq
.Ve
.Sp
Queue to put job in.
.SS "run"
.IX Subsection "run"
.Vb 1
\&  $job\->run(@args);
.Ve
.PP
Task to perform by this job. Meant to be overloaded in a subclass to create a custom task class. Note that this method
is \fB\s-1EXPERIMENTAL\s0\fR and might change without warning!
.SS "start"
.IX Subsection "start"
.Vb 1
\&  $job = $job\->start;
.Ve
.PP
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.
.PP
.Vb 6
\&  # Perform two jobs concurrently
\&  $job1\->start;
\&  $job2\->start;
\&  my ($first, $second);
\&  sleep 1
\&    until $first ||= $job1\->is_finished and $second ||= $job2\->is_finished;
.Ve
.SS "stop"
.IX Subsection "stop"
.Vb 1
\&  $job\->stop;
.Ve
.PP
Stop job performed with \*(L"start\*(R" immediately. Note that this method should only be used to implement custom workers.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Minion, <https://minion.pm>, Mojolicious::Guides, <https://mojolicious.org>.