1MooseX::Workers(3) User Contributed Perl Documentation MooseX::Workers(3)
2
6 MooseX::Workers - Simple sub-process management for asynchronous tasks
7
9 EXAMPLE #1:
10 package Manager;
11 # This example prints output from the children normally on both STDOUT and STDERR
12 use Moose;
14 with qw(MooseX::Workers);
15 sub run {
17 $_[0]->spawn( sub { sleep 3; print "Hello World\n" } );
18 warn "Running now ... ";
19 POE::Kernel->run();
20 }
21 # Implement our Interface
23 sub worker_stdout { shift; warn join ' ', @_; }
24 sub worker_stderr { shift; warn join ' ', @_; }
25 sub worker_manager_start { warn 'started worker manager' }
27 sub worker_manager_stop { warn 'stopped worker manager' }
28 sub max_workers_reached { warn 'maximum worker count reached' }
30 sub worker_error { shift; warn join ' ', @_; }
31 sub worker_finished { warn 'a worker has finished' }
32 sub worker_started { shift; warn join ' ', @_; }
33 sub sig_child { shift; warn join ' ', @_; }
34 sub sig_TERM { shift; warn 'Handled TERM' }
35 no Moose;
37 Manager->new->run();
39 EXAMPLE #2:
42 package Manager;
43 # This example prints output from the children normally on
45 # STDERR but uses STDOUT to returns a hashref from the child to
46 # the parent
47 use Moose;
49 with qw(MooseX::Workers);
50 use POE qw(Filter::Reference Filter::Line);
51 sub run {
53 $_[0]->spawn(
54 sub {
55 sleep 3;
56 # Return a hashref (arrayref, whatever) to the parent using P::F::Reference
58 print @{POE::Filter::Reference->new->put([ {msg => "Hello World"} ])}; # Note the [] around the return val
59 # Print normally using P::F::Line (shown for
61 # completeness; in practice, just don't bother
62 # defining the _filter method
63 #
64 print STDERR "Hey look, an error message";
65 }
66 );
67 POE::Kernel->run();
69 }
70 # Implement our Interface
72 # These two are both optional; if defined (as here), they
73 # should return a subclass of POE::Filter.
74 sub stdout_filter { POE::Filter::Reference->new }
75 sub stderr_filter { POE::Filter::Line->new }
76 sub worker_stdout {
78 my ( $self, $result ) = @_; # $result will be a hashref: {msg => "Hello World"}
79 print $result->{msg};
80 # Note that you can do more than just print the message --
82 # e.g. this is the way to return data from the children for
83 # accumulation in the parent.
84 }
85 sub worker_stderr {
86 my ( $self, $stderr_msg ) = @_; # $stderr_msg will be a string: "Hey look, an error message";
87 warn $stderr_msg;
88 }
89 # From here down, this is identical to the previous example.
91 sub worker_manager_start { warn 'started worker manager' }
92 sub worker_manager_stop { warn 'stopped worker manager' }
93 sub max_workers_reached { warn 'maximum worker count reached' }
95 sub worker_error { shift; warn join ' ', @_; }
96 sub worker_finished { warn 'a worker has finished' }
97 sub worker_started { shift; warn join ' ', @_; }
98 sub sig_child { shift; warn join ' ', @_; }
99 sub sig_TERM { shift; warn 'Handled TERM' }
100 no Moose;
102 Manager->new->run();
104
106 MooseX::Workers is a Role that provides easy delegation of long-running
107 tasks into a managed child process. Process management is taken care of
108 via POE and its POE::Wheel::Run module.
109
111 spawn ($command)
112 fork ($command)
113 run_command ($command)
114 These three methods are the whole point of this module. They pass
115 $command through to the MooseX::Worker::Engine which will take care
116 of running $command for you.
117 spawn() and fork() both invoke POE::Kernel call(), which is
119 synchronous.
120 run_command() invokes POE::Kernel yield(), which is asynchronous.
122 If max_workers() has been reached, run_command() warns and does
124 nothing. It is up to you to re-submit $command. See enqueue() if
125 you want us to run $command as soon as another worker is free.
126 enqueue($command)
128 Just like run_command(), only that if max_workers() has been set
129 and that number of workers has been reached, then we add $command
130 to a FIFO command queue. As soon as any running worker exits, the
131 first $command in queue (if any) will be run.
132 check_worker_threshold
134 This will check to see how many workers you have compared to the
135 max_workers limit. It returns true if the $num_workers is >=
136 $max_workers;
137 max_workers($count)
139 An accessor for the maximum number of workers. This is delegated to
140 the MooseX::Workers::Engine object.
141 has_workers
143 Check to see if we have *any* workers currently. This is delegated
144 to the MooseX::Workers::Engine object.
145 num_workers
147 Return the current number of workers. This is delegated to the
148 MooseX::Workers::Engine object.
149 meta
151 The Metaclass for MooseX::Workers::Engine see Moose's
152 documentation.
153
155 MooseX::Worker::Engine supports the following callbacks:
156 worker_manager_start
158 Called when the managing session is started
159 worker_manager_stop
161 Called when the managing session stops
162 max_workers_reached
164 Called when we reach the maximum number of workers
165 stdout_filter
167 OPTIONAL. If defined, this should return an object that isa
168 POE::Filter. If it doesn't, the results are undefined. Anything
169 that a child proc sends on STDOUT will be passed through the
170 relevant filter.
171 stderr_filter
173 OPTIONAL. If defined, this should return an object that isa
174 POE::Filter. If it doesn't, the results are undefined. Anything
175 that a child proc sends on STDERR will be passed through the
176 relevant filter.
177 worker_stdout
179 Called when a child prints to STDOUT. If "stdout_filter" was
180 defined, the output will be filtered appropriately, as described
181 above. This is useful to allow child processes to return data to
182 the parent (generally via POE::Filter::Reference).
183 worker_stderr
185 Called when a child prints to STDERR. Filtered through the result
186 of "stderr_filter" if that method is defined.
187 worker_error
189 Called when there is an error condition detected with the child.
190 worker_finished
192 Called when a worker completes $command.
193 If the command was a MooseX::Workers::Job, it will get the removed
195 job instance as the first parameter.
196 worker_done
198 *DEPRECATED*
199 This is called before the worker is removed, so "num_workers" and
201 "has_workers" does not reflect that a worker has just finished. Use
202 "worker_finished" instead.
203 Gets the MooseX::Workers::Job instance, if the $command was a job,
205 and the POE::Wheel::Run id otherwise.
206 worker_started
208 Called when a worker starts $command
209 sig_child
211 Called when the mangaging session recieves a SIG CHLD event
212 sig_*
214 Called when the underlying POE Kernel receives a signal; this is
215 not limited to OS signals (ie. what you'd usually handle in Perl's
216 %SIG) so will also accept arbitrary POE signals (sent via
217 POE::Kernel->signal), but does exclude SIGCHLD/SIGCHILD, which is
218 instead handled by sig_child above.
219 These interface methods are automatically inserted when
221 MooseX::Worker::Engine detects that your manager class contains any
222 methods beginning with sig_. Signals are case-sensitive, so if you
223 wish to handle a TERM signal, you must define a sig_TERM() method.
224 Note also that this action is performed upon MooseX::Worker::Engine
225 startup, so any run-time modification of your class which 'does'
226 MooseX::Workers is not likely to be detected.
227 See the sig_TERM handler in the SYNOPSIS for an example.
229 See MooseX::Workers::Engine for more details. Also see
231 MooseX::Workers::Job if you'd like to give your tasks names, or set
232 timeouts on them.
233
235 You don't need to binmode the STDIN/STDOUT/STDERR streams in your
236 coderefs, this is done for you. If you need utf8, it is safe to re-
237 binmode them to :encoding(UTF-8).
238 Coderef workers that time out are killed with a SIGINT rather than a
240 SIGTERM, because TERM does not behave compatibly (thanks Rocco!) This
241 is done with a:
242 local $SIG{INT} = sub { exit 0 };
244 that wraps the coderef.
246 You cannot catch a TERM sent to the parent process (see "kill" in
248 perlport, use INT instead.
249 External programs are run with Win32::Job by POE::Wheel::Run. They are
251 prepended with "cmd /c" so that builtin cmd commands also work. Use a
252 MooseX::Workers::Job with a string program and arrayref args for this.
253 If you are using POE::Filter::Line with an external program (which is
254 the default if you don't set the filter) the CRs from line ends will be
255 removed automatically.
256
258 Please report any bugs or feature requests to
259 "bug-moosex-workers@rt.cpan.org", or through the web interface at
260 <http://rt.cpan.org>.
261 Version control: <https://github.com/jhannah/moosex-workers>
263
265 Chris Prather "<perigrin@cpan.org>"
266 Tom Lanyon "<dec@cpan.org>"
268 Jay Hannah "<jay@jays.net>"
270 Justin Hunter "<justin.d.hunter@gmail.com>"
272 David K. Storrs "<david.storrs@gmail.com>"
274 Rafael Kitover "<rkitover@cpan.org>"
276
278 Copyright (c) 2007-2013, Chris Prather "<perigrin@cpan.org>". Some
279 rights reserved.
280 This module is free software; you can redistribute it and/or modify it
282 under the same terms as Perl itself. See perlartistic.
283
285 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
286 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
287 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
288 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
289 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
290 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
291 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
292 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
293 NECESSARY SERVICING, REPAIR, OR CORRECTION.
294 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
296 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
297 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
298 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
299 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
300 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
301 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
302 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
303 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
304 DAMAGES.
305perl v5.38.0 2023-07-21 MooseX::Workers(3)