.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Worker 3pm"
.TH Minion::Worker 3pm 2024-03-24 "perl v5.38.2" "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::Worker \- Minion worker
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Minion::Worker;
\&
\&  my $worker = Minion::Worker\->new(minion => $minion);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Minion::Worker performs jobs for Minion.
.SH "WORKER SIGNALS"
.IX Header "WORKER SIGNALS"
The Minion::Worker process can be controlled at runtime with the following signals.
.SS "INT, TERM"
.IX Subsection "INT, TERM"
Stop gracefully after finishing the current jobs.
.SS QUIT
.IX Subsection "QUIT"
Stop immediately without finishing the current jobs.
.SH "JOB SIGNALS"
.IX Header "JOB SIGNALS"
The job processes spawned by the Minion::Worker process can be controlled at runtime with the following signals.
.SS "INT, TERM"
.IX Subsection "INT, TERM"
This signal starts out with the operating system default and allows for jobs to install a custom signal handler to stop
gracefully.
.SS "USR1, USR2"
.IX Subsection "USR1, USR2"
These signals start out being ignored and allow for jobs to install custom signal handlers.
.SH EVENTS
.IX Header "EVENTS"
Minion::Worker inherits all events from Mojo::EventEmitter and can emit the following new ones.
.SS busy
.IX Subsection "busy"
.Vb 3
\&  $worker\->on(busy => sub ($worker) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process when it is performing the maximum number of jobs in parallel.
.PP
.Vb 4
\&  $worker\->on(busy => sub ($worker) {
\&    my $max = $worker\->status\->{jobs};
\&    say "Performing $max jobs.";
\&  });
.Ve
.SS dequeue
.IX Subsection "dequeue"
.Vb 3
\&  $worker\->on(dequeue => sub ($worker, $job) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process after a job has been dequeued.
.PP
.Vb 4
\&  $worker\->on(dequeue => sub ($worker, $job) {
\&    my $id = $job\->id;
\&    say "Job $id has been dequeued.";
\&  });
.Ve
.SS wait
.IX Subsection "wait"
.Vb 3
\&  $worker\->on(wait => sub ($worker) {
\&    ...
\&  });
.Ve
.PP
Emitted in the worker process before it tries to dequeue a job.
.PP
.Vb 4
\&  $worker\->on(wait => sub ($worker) {
\&    my $max = $worker\->status\->{dequeue_timeout};
\&    say "Waiting up to $max seconds for a new job.";
\&  });
.Ve
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Minion::Worker implements the following attributes.
.SS commands
.IX Subsection "commands"
.Vb 2
\&  my $commands = $worker\->commands;
\&  $worker      = $worker\->commands({jobs => sub {...}});
.Ve
.PP
Registered worker remote control commands.
.SS id
.IX Subsection "id"
.Vb 2
\&  my $id  = $worker\->id;
\&  $worker = $worker\->id($id);
.Ve
.PP
Worker id.
.SS minion
.IX Subsection "minion"
.Vb 2
\&  my $minion = $worker\->minion;
\&  $worker    = $worker\->minion(Minion\->new);
.Ve
.PP
Minion object this worker belongs to.
.SS status
.IX Subsection "status"
.Vb 2
\&  my $status = $worker\->status;
\&  $worker    = $worker\->status({queues => [\*(Aqdefault\*(Aq, \*(Aqimportant\*(Aq]);
.Ve
.PP
Status information to configure workers started with "run" and to share every time "register" is called.
.SH METHODS
.IX Header "METHODS"
Minion::Worker inherits all methods from Mojo::EventEmitter and implements the following new ones.
.SS add_command
.IX Subsection "add_command"
.Vb 1
\&  $worker = $worker\->add_command(jobs => sub {...});
.Ve
.PP
Register a worker remote control command.
.PP
.Vb 3
\&  $worker\->add_command(foo => sub ($worker, @args) {
\&    ...
\&  });
.Ve
.SS dequeue
.IX Subsection "dequeue"
.Vb 2
\&  my $job = $worker\->dequeue(0.5);
\&  my $job = $worker\->dequeue(0.5 => {queues => [\*(Aqimportant\*(Aq]});
.Ve
.PP
Wait a given amount of time in seconds for a job, dequeue Minion::Job object and transition from \f(CW\*(C`inactive\*(C'\fR to
\&\f(CW\*(C`active\*(C'\fR state, or return \f(CW\*(C`undef\*(C'\fR if queues were empty.
.PP
These options are currently available:
.IP id 2
.IX Item "id"
.Vb 1
\&  id => \*(Aq10023\*(Aq
.Ve
.Sp
Dequeue a specific job.
.IP min_priority 2
.IX Item "min_priority"
.Vb 1
\&  min_priority => 3
.Ve
.Sp
Do not dequeue jobs with a lower priority.
.IP queues 2
.IX Item "queues"
.Vb 1
\&  queues => [\*(Aqimportant\*(Aq]
.Ve
.Sp
One or more queues to dequeue jobs from, defaults to \f(CW\*(C`default\*(C'\fR.
.SS info
.IX Subsection "info"
.Vb 1
\&  my $info = $worker\->info;
.Ve
.PP
Get worker information.
.PP
.Vb 2
\&  # Check worker host
\&  my $host = $worker\->info\->{host};
.Ve
.PP
These fields are currently available:
.IP host 2
.IX Item "host"
.Vb 1
\&  host => \*(Aqlocalhost\*(Aq
.Ve
.Sp
Worker host.
.IP jobs 2
.IX Item "jobs"
.Vb 1
\&  jobs => [\*(Aq10023\*(Aq, \*(Aq10024\*(Aq, \*(Aq10025\*(Aq, \*(Aq10029\*(Aq]
.Ve
.Sp
Ids of jobs the worker is currently processing.
.IP notified 2
.IX Item "notified"
.Vb 1
\&  notified => 784111777
.Ve
.Sp
Epoch time worker sent the last heartbeat.
.IP pid 2
.IX Item "pid"
.Vb 1
\&  pid => 12345
.Ve
.Sp
Process id of worker.
.IP started 2
.IX Item "started"
.Vb 1
\&  started => 784111777
.Ve
.Sp
Epoch time worker was started.
.IP status 2
.IX Item "status"
.Vb 1
\&  status => {queues => [\*(Aqdefault\*(Aq, \*(Aqimportant\*(Aq]}
.Ve
.Sp
Hash reference with whatever status information the worker would like to share.
.SS new
.IX Subsection "new"
.Vb 3
\&  my $worker = Minion::Worker\->new;
\&  my $worker = Minion::Worker\->new(status => {foo => \*(Aqbar\*(Aq});
\&  my $worker = Minion::Worker\->new({status => {foo => \*(Aqbar\*(Aq}});
.Ve
.PP
Construct a new Minion::Worker object and subscribe to "busy" event with default handler that sleeps for one
second.
.SS process_commands
.IX Subsection "process_commands"
.Vb 1
\&  $worker = $worker\->process_commands;
.Ve
.PP
Process worker remote control commands.
.SS register
.IX Subsection "register"
.Vb 1
\&  $worker = $worker\->register;
.Ve
.PP
Register worker or send heartbeat to show that this worker is still alive.
.SS run
.IX Subsection "run"
.Vb 1
\&  $worker\->run;
.Ve
.PP
Run worker and wait for "WORKER SIGNALS".
.PP
.Vb 4
\&  # Start a worker for a special named queue
\&  my $worker = $minion\->worker;
\&  $worker\->status\->{queues} = [\*(Aqimportant\*(Aq];
\&  $worker\->run;
.Ve
.PP
These "status" options are currently available:
.IP command_interval 2
.IX Item "command_interval"
.Vb 1
\&  command_interval => 20
.Ve
.Sp
Worker remote control command interval, defaults to \f(CW10\fR.
.IP dequeue_timeout 2
.IX Item "dequeue_timeout"
.Vb 1
\&  dequeue_timeout => 5
.Ve
.Sp
Maximum amount time in seconds to wait for a job, defaults to \f(CW5\fR.
.IP heartbeat_interval 2
.IX Item "heartbeat_interval"
.Vb 1
\&  heartbeat_interval => 60
.Ve
.Sp
Heartbeat interval, defaults to \f(CW300\fR.
.IP jobs 2
.IX Item "jobs"
.Vb 1
\&  jobs => 12
.Ve
.Sp
Maximum number of jobs to perform parallel in forked worker processes (not including spare processes), defaults to \f(CW4\fR.
.IP queues 2
.IX Item "queues"
.Vb 1
\&  queues => [\*(Aqtest\*(Aq]
.Ve
.Sp
One or more queues to get jobs from, defaults to \f(CW\*(C`default\*(C'\fR.
.IP repair_interval 2
.IX Item "repair_interval"
.Vb 1
\&  repair_interval => 3600
.Ve
.Sp
Repair interval, up to half of this value can be subtracted randomly to make sure not all workers repair at the same
time, defaults to \f(CW21600\fR (6 hours).
.IP spare 2
.IX Item "spare"
.Vb 1
\&  spare => 2
.Ve
.Sp
Number of spare worker processes to reserve for high priority jobs, defaults to \f(CW1\fR.
.IP spare_min_priority 2
.IX Item "spare_min_priority"
.Vb 1
\&  spare_min_priority => 7
.Ve
.Sp
Minimum priority of jobs to use spare worker processes for, defaults to \f(CW1\fR.
.PP
These remote control "commands" are currently available:
.IP jobs 2
.IX Item "jobs"
.Vb 2
\&  $minion\->broadcast(\*(Aqjobs\*(Aq, [10]);
\&  $minion\->broadcast(\*(Aqjobs\*(Aq, [10], [$worker_id]);
.Ve
.Sp
Instruct one or more workers to change the number of jobs to perform concurrently. Setting this value to \f(CW0\fR will
effectively pause the worker. That means all current jobs will be finished, but no new ones accepted, until the number
is increased again.
.IP kill 2
.IX Item "kill"
.Vb 2
\&  $minion\->broadcast(\*(Aqkill\*(Aq, [\*(AqINT\*(Aq, 10025]);
\&  $minion\->broadcast(\*(Aqkill\*(Aq, [\*(AqINT\*(Aq, 10025], [$worker_id]);
.Ve
.Sp
Instruct one or more workers to send a signal to a job that is currently being performed. This command will be ignored
by workers that do not have a job matching the id. That means it is safe to broadcast this command to all workers.
.IP stop 2
.IX Item "stop"
.Vb 2
\&  $minion\->broadcast(\*(Aqstop\*(Aq, [10025]);
\&  $minion\->broadcast(\*(Aqstop\*(Aq, [10025], [$worker_id]);
.Ve
.Sp
Instruct one or more workers to stop a job that is currently being performed immediately. This command will be ignored
by workers that do not have a job matching the id. That means it is safe to broadcast this command to all workers.
.SS unregister
.IX Subsection "unregister"
.Vb 1
\&  $worker = $worker\->unregister;
.Ve
.PP
Unregister worker.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Minion, Minion::Guide, <https://minion.pm>, Mojolicious::Guides, <https://mojolicious.org>.