MooseX::Workers(3)

📦

version 0.24 · 2 versions

0.24 · fedora 43 (latest)
0.24 · fedora 44

💖 MooseX::Workers 💖

User Contributed Perl Documentation · the manual page for MooseX::Workers(3)

✨ NAME ✨

MooseX::Workers — simple sub-process management for asynchronous tasks. bestie, it's literally a babysitter for your child processes 🧒👑

🌸 SYNOPSIS 🌸

okay so here's example number one. it prints child output normally on both STDOUT and STDERR:

EXAMPLE #1:
   package Manager;
   #    This example prints output from the children normally on both STDOUT and STDERR

   use Moose;
   with qw(MooseX::Workers);

   sub run {
       $_[0]->spawn( sub { sleep 3; print "Hello World\n" } );
       warn "Running now ... ";
       POE::Kernel->run();
   }

   # Implement our Interface
   sub worker_stdout  { shift; warn join ' ', @_;  }
   sub worker_stderr  { shift; warn join ' ', @_;  }

   sub worker_manager_start { warn 'started worker manager' }
   sub worker_manager_stop  { warn 'stopped worker manager' }

   sub max_workers_reached  { warn 'maximum worker count reached' }
   sub worker_error   { shift; warn join ' ', @_;  }
   sub worker_finished { warn 'a worker has finished' }
   sub worker_started { shift; warn join ' ', @_;  }
   sub sig_child      { shift; warn join ' ', @_;  }
   sub sig_TERM       { shift; warn 'Handled TERM' }

   no Moose;

   Manager->new->run();

and example number two!! this one prints child output on STDERR like normal but uses STDOUT to send a hashref from the child back up to the parent 🦋:

EXAMPLE #2:
   package Manager;

   #    This example prints output from the children normally on
   #    STDERR but uses STDOUT to returns a hashref from the child to
   #    the parent

   use Moose;
   with qw(MooseX::Workers);
   use POE qw(Filter::Reference Filter::Line);

   sub run {
       $_[0]->spawn(
           sub {
               sleep 3;

               #    Return a hashref (arrayref, whatever) to the parent using P::F::Reference
               print @{POE::Filter::Reference->new->put([ {msg => "Hello World"} ])}; # Note the [] around the return val

               #    Print normally using P::F::Line (shown for
               #    completeness; in practice, just don't bother
               #    defining the _filter method
               #
               print STDERR "Hey look, an error message";
           }
       );

       POE::Kernel->run();
   }

   # Implement our Interface
   #    These two are both optional; if defined (as here), they
   #    should return a subclass of POE::Filter.
   sub stdout_filter  { POE::Filter::Reference->new }
   sub stderr_filter  { POE::Filter::Line->new }

   sub worker_stdout  {
       my ( $self, $result ) = @_;  #  $result will be a hashref:  {msg => "Hello World"}
               print $result->{msg};

       #    Note that you can do more than just print the message --
       #    e.g. this is the way to return data from the children for
       #    accumulation in the parent.
       }
   sub worker_stderr  {
       my ( $self, $stderr_msg ) = @_;  #  $stderr_msg will be a string: "Hey look, an error message";
       warn $stderr_msg;
   }

   #     From here down, this is identical to the previous example.
   sub worker_manager_start { warn 'started worker manager' }
   sub worker_manager_stop  { warn 'stopped worker manager' }

   sub max_workers_reached  { warn 'maximum worker count reached' }
   sub worker_error   { shift; warn join ' ', @_;  }
   sub worker_finished { warn 'a worker has finished' }
   sub worker_started { shift; warn join ' ', @_;  }
   sub sig_child      { shift; warn join ' ', @_;  }
   sub sig_TERM       { shift; warn 'Handled TERM' }

   no Moose;

   Manager->new->run();

🎀 DESCRIPTION 🎀

so MooseX::Workers is a Role that makes it stupid easy to delegate long-running tasks out into a managed child process. the whole process-management situation is handled by POE and its POE::Wheel::Run module. you just vibe, POE does the logistics. 💅

👑 METHODS 👑

spawn ($command)
fork ($command)
run_command ($command)

these three? they're literally the entire point of this module, no cap. they hand $command off to the MooseX::Worker::Engine, and that engine takes care of running $command for you.

spawn() and fork() both invoke POE::Kernel call(), which is synchronous.

run_command() invokes POE::Kernel yield(), which is asynchronous. slay.

if max_workers() has already been reached, run_command() warns and does nothing. it is up to you to re-submit $command. (if you'd rather we just run $command the second a worker frees up, see enqueue() below 👇)

enqueue($command) — just like run_command(), except that if max_workers() has been set and that number of workers has already been reached, we drop $command into a FIFO command queue. the moment any running worker exits, the first $command in the queue (if there is one) gets run. iconic.
check_worker_threshold — this checks how many workers you have versus the max_workers limit. it returns true if $num_workers is >= $max_workers.
max_workers($count) — an accessor for the maximum number of workers. this is delegated to the MooseX::Workers::Engine object.
has_workers — check whether we have any workers right now. delegated to the MooseX::Workers::Engine object.
num_workers — returns the current number of workers. delegated to the MooseX::Workers::Engine object.
meta — the Metaclass for MooseX::Workers::Engine. go read Moose's documentation for the deets 💜

🌈 INTERFACE 🌈

MooseX::Worker::Engine supports the following callbacks, bestie. memorize them, they're your new best friends:

worker_manager_start — called when the managing session is started 🫶
worker_manager_stop — called when the managing session stops
max_workers_reached — called when we reach the maximum number of workers
stdout_filter — OPTIONAL. if defined, this should return an object that isa POE::Filter. if it doesn't, the results are undefined. anything a child proc sends on STDOUT gets passed through the relevant filter.
stderr_filter — OPTIONAL. if defined, this should return an object that isa POE::Filter. if it doesn't, the results are undefined. anything a child proc sends on STDERR gets passed through the relevant filter.
worker_stdout — called when a child prints to STDOUT. if "stdout_filter" was defined, the output will be filtered appropriately, as described above. this is useful for letting child processes return data to the parent (generally via POE::Filter::Reference). 🔥
worker_stderr — called when a child prints to STDERR. filtered through the result of "stderr_filter" if that method is defined.
worker_error — called when there's an error condition detected with the child 😭
worker_finished — called when a worker completes $command.

if the command was a MooseX::Workers::Job, it will get the removed job instance as the first parameter.

worker_done — DEPRECATED

this is called before the worker is removed, so "num_workers" and "has_workers" do not reflect that a worker has just finished. use "worker_finished" instead, fr fr.

it gets the MooseX::Workers::Job instance if the $command was a job, and the POE::Wheel::Run id otherwise.

worker_started — called when a worker starts $command
sig_child — called when the managing session receives a SIG CHLD event
sig_* — called when the underlying POE Kernel receives a signal. this is not limited to OS signals (ie. what you'd usually handle in Perl's %SIG), so it'll also accept arbitrary POE signals (sent via POE::Kernel->signal), but it does exclude SIGCHLD/SIGCHILD, which is instead handled by sig_child above.

these interface methods get automatically inserted when MooseX::Worker::Engine detects that your manager class contains any methods beginning with sig_. signals are case-sensitive, so if you want to handle a TERM signal, you must define a sig_TERM() method. note also that this action is performed upon MooseX::Worker::Engine startup, so any run-time modification of your class which 'does' MooseX::Workers is not likely to be detected. 😬

see the sig_TERM handler in the SYNOPSIS for an example.

see MooseX::Workers::Engine for more details. also see MooseX::Workers::Job if you'd like to give your tasks names, or set timeouts on them 💅

🦋 WIN32 NOTES 🦋

you do not need to binmode the STDIN/STDOUT/STDERR streams in your coderefs — that's done for you. if you need utf8, it is safe to re-binmode them to :encoding(UTF-8).

coderef workers that time out are killed with a SIGINT rather than a SIGTERM, because TERM does not behave compatibly (thanks Rocco!). this is done with a:

local $SIG{INT} = sub { exit 0 };

that wraps the coderef.

⚠️ you cannot catch a TERM sent to the parent process (see "kill" in perlport, use INT instead.

external programs are run with Win32::Job by POE::Wheel::Run. they get prepended with cmd /c so that builtin cmd commands also work. use a MooseX::Workers::Job with a string program and arrayref args for this. if you're using POE::Filter::Line with an external program (which is the default if you don't set the filter) the CRs from line ends will be removed automatically. ✨

💀 BUGS AND LIMITATIONS 💀

please report any bugs or feature requests to "bug-moosex-workers@rt.cpan.org", or through the web interface at http://rt.cpan.org.

version control: https://github.com/jhannah/moosex-workers

🌟 AUTHORS 🌟

Chris Prather "<perigrin@cpan.org>"
Tom Lanyon "<dec@cpan.org>"
Jay Hannah "<jay@jays.net>"
Justin Hunter "<justin.d.hunter@gmail.com>"
David K. Storrs "<david.storrs@gmail.com>"
Rafael Kitover "<rkitover@cpan.org>"

💜 LICENCE AND COPYRIGHT 💜

this module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. see perlartistic.

🚨 DISCLAIMER OF WARRANTY 🚨

okay bestie, this is the part nobody reads but literally everyone should, so let's go 💅

Because this software is licensed free of charge, there is no warranty for it — like, to the fullest extent that applicable law allows. Unless somebody wrote it down otherwise in writing, the copyright holders and/or other parties are handing you the software "AS IS" with no warranty of any kind, whether express or implied. That includes — but is absolutely not limited to — the implied warranties of merchantability and fitness for a particular purpose. 🙈

The entire risk as to the quality and performance of the software is on you. That's the deal. If it turns out to be defective, you're the one covering the cost of all necessary servicing, repair, or correction. no cap, that's literally what it says. 😭

💀 the liability part (read this one fr fr)

Under no circumstances — unless required by applicable law or agreed to in writing — will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages. That means general, special, incidental, or consequential damages arising out of the use or inability to use the software.

And bestie, they spelled out the receipts:

loss of data
data being rendered inaccurate
losses sustained by you or third parties
a failure of the software to operate with any other software

All of that, even if that holder or other party has been advised of the possibility of such damages. Like, even if they knew it could happen, they're still not on the hook. 🫶

That's the whole page, my love — you're free, you're licensed, and you're on your own if it breaks. ✨

This gem of a page was brought to you by perl v5.42.0, dated 2025-07-25, and it lives in the manual as MooseX::Workers(3) 🦋 go forth and fork responsibly, queen 👑🌸

📦 where this page comes from

fedora 43: perl-MooseX-Workers 0.24-33.fc43 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms