1Mojo::IOLoop::ReadWriteUPsreorceCsosn(t3r)ibuted Perl DoMcoujmoe:n:tIaOtLiooonp::ReadWriteProcess(3)
2
6 Mojo::IOLoop::ReadWriteProcess - Execute external programs or internal
7 code blocks as separate process.
8
10 use Mojo::IOLoop::ReadWriteProcess;
11 # Code fork
13 my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello\n" });
14 $process->start();
15 print "Running\n" if $process->is_running();
16 $process->getline(); # Will return "Hello\n"
17 $process->pid(); # Process id
18 $process->stop();
19 $process->wait_stop(); # if you intend to wait its lifespan
20 # Methods can be chained, thus this is valid:
22 use Mojo::IOLoop::ReadWriteProcess qw(process);
23 my $output = process( sub { print "Hello\n" } )->start()->wait_stop->getline;
24 # Handles seamelessy also external processes:
26 my $process = process(execute=> '/path/to/bin' )->args(qw(foo bar baz));
27 $process->start();
28 my $line_output = $process->getline();
29 my $pid = $process->pid();
30 $process->stop();
31 my @errors = $process->error;
32 # Get process return value
34 $process = process( sub { return "256"; } )->start()->wait_stop;
35 # We need to stop it to retrieve the exit status
36 my $return = $process->return_status;
37 # We can access directly to handlers from the object:
39 my $stdout = $process->read_stream;
40 my $stdin = $process->write_stream;
41 my $stderr = $process->error_stream;
42 # So this works:
44 print $stdin "foo bar\n";
45 my @lines = <$stdout>;
46 # There is also an alternative channel of communication (just for forked processes):
48 my $channel_in = $process->channel_in; # write to the child process
49 my $channel_out = $process->channel_out; # read from the child process
50 $process->channel_write("PING"); # convenience function
51
53 Mojo::IOLoop::ReadWriteProcess is yet another process manager.
54
56 Mojo::IOLoop::ReadWriteProcess inherits all events from
57 Mojo::EventEmitter and can emit the following new ones.
58 start
60 $process->on(start => sub {
61 my ($process) = @_;
62 $process->is_running();
63 });
64 Emitted when the process starts.
66 stop
68 $process->on(stop => sub {
69 my ($process) = @_;
70 $process->restart();
71 });
72 Emitted when the process stops.
74 process_error
76 $process->on(process_error => sub {
77 my ($e) = @_;
78 my @errors = @{$e};
79 });
80 Emitted when the process produce errors.
82 process_stuck
84 $process->on(process_stuck => sub {
85 my ($self) = @_;
86 ...
87 });
88 Emitted when "blocking_stop" is set and all attempts for killing the
90 process in "max_kill_attempts" have been exhausted. The event is
91 emitted before attempting to kill it with SIGKILL and becoming
92 blocking.
93 SIG_CHLD
95 $process->on(SIG_CHLD => sub {
96 my ($self) = @_;
97 ...
98 });
99 Emitted when we receive SIG_CHLD.
101 SIG_TERM
103 $process->on(SIG_TERM => sub {
104 my ($self) = @_;
105 ...
106 });
107 Emitted when the child forked process receives SIG_TERM, before
109 exiting.
110 collected
112 $process->on(collected => sub {
113 my ($self) = @_;
114 ...
115 });
116 Emitted right after status collection.
118 collect_status
120 $process->on(collect_status => sub {
121 my ($self) = @_;
122 ...
123 });
124 Emitted when on child process waitpid. It is used internally to get
126 the child process status. Note: events attached to it are wiped when
127 process has been stopped.
128
130 Mojo::IOLoop::ReadWriteProcess inherits all attributes from
131 Mojo::EventEmitter and implements the following new ones.
132 execute
134 use Mojo::IOLoop::ReadWriteProcess;
135 my $process = Mojo::IOLoop::ReadWriteProcess->new(execute => "/usr/bin/perl");
136 $process->start();
137 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
138 $process->stop();
139 "execute" should contain the external program that you wish to run.
141 code
143 use Mojo::IOLoop::ReadWriteProcess;
144 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" } );
145 $process->start();
146 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
147 $process->stop();
148 It represent the code you want to run in background.
150 You do not need to specify "code", it is implied if no arguments is
152 given.
153 my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello" });
155 $process->start();
156 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
157 $process->stop();
158 args
160 use Mojo::IOLoop::ReadWriteProcess;
161 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".shift() }, args => "User" );
162 $process->start();
163 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
164 $process->stop();
165 # The process will print "Hello User"
167 Array or arrayref of options to pass by to the external binary or the
169 code block.
170 blocking_stop
172 use Mojo::IOLoop::ReadWriteProcess;
173 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, blocking_stop => 1 );
174 $process->start();
175 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
176 $process->stop(); # Will wait indefinitely until the process is stopped
177 Set it to 1 if you want to do blocking stop of the process.
179 channels
181 use Mojo::IOLoop::ReadWriteProcess;
182 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, channels => 0 );
183 $process->start();
184 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
185 $process->stop(); # Will wait indefinitely until the process is stopped
186 Set it to 0 if you want to disable internal channels.
188 session
190 use Mojo::IOLoop::ReadWriteProcess;
191 my $process = Mojo::IOLoop::ReadWriteProcess->new(sub { print "Hello" });
192 my $session = $process->session;
193 $session->enable_subreaper;
194 Returns the current Mojo::IOLoop::ReadWriteProcess::Session singleton.
196 subreaper
198 use Mojo::IOLoop::ReadWriteProcess;
199 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".shift() }, args => "User" );
200 $process->subreaper(1)->start();
201 $process->on( stop => sub { $_->disable_subreaper } );
202 $process->stop();
203 # The process will print "Hello User"
205 Mark the current process (not the child) as subreaper on start. It's
207 on invoker behalf to disable subreaper when process stops, as it marks
208 the current process and not the child.
209 ioloop
211 my $loop = $process->ioloop;
212 $subprocess = $process->ioloop(Mojo::IOLoop->new);
213 Event loop object to control, defaults to the global Mojo::IOLoop
215 singleton.
216 max_kill_attempts
218 use Mojo::IOLoop::ReadWriteProcess;
219 my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello" }, max_kill_attempts => 50 );
220 $process->start();
221 $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
222 $process->stop(); # It will attempt to send SIGTERM 50 times.
223 Defaults to 5, is the number of attempts before bailing out.
225 It can be used with blocking_stop, so if the number of attempts are
227 exhausted, a SIGKILL and waitpid will be tried at the end.
228 collect_status
230 Defaults to 1, If enabled it will automatically collect the status of
231 the children process. Disable it in case you want to manage your
232 process child directly, and do not want to rely on automatic collect
233 status. If you won't overwrite your "SIGCHLD" handler, the "SIG_CHLD"
234 event will be still emitted.
235 serialize
237 Defaults to 0, If enabled data returned from forked process will be
238 serialized with Storable.
239 kill_sleeptime
241 Defaults to 1, it's the seconds to wait before attempting SIGKILL when
242 blocking_stop is setted to 1.
243 separate_err
245 Defaults to 1, it will create a separate channel to intercept process
246 STDERR, otherwise it will be redirected to STDOUT.
247 verbose
249 Defaults to 1, it indicates message verbosity.
250 set_pipes
252 Defaults to 1, If enabled, additional pipes for process communication
253 are automatically set up.
254 internal_pipes
256 Defaults to 1, If enabled, additional pipes for retreiving process
257 return and errors are set up. Note: If you disable that, the only
258 information provided by the process will be the exit_status.
259 autoflush
261 Defaults to 1, If enabled autoflush of handlers is enabled
262 automatically.
263 error
265 Returns a Mojo::Collection of errors. Note: errors that can be
266 captured only at the end of the process
267
269 Mojo::IOLoop::ReadWriteProcess inherits all methods from
270 Mojo::EventEmitter and implements the following new ones.
271 start()
273 use Mojo::IOLoop::ReadWriteProcess qw(process);
274 my $p = process(sub {
275 print STDERR "Boo\n"
276 } )->start;
277 Starts the process
279 stop()
281 use Mojo::IOLoop::ReadWriteProcess qw(process);
282 my $p = process( execute => "/path/to/bin" )->start->stop;
283 Stop the process. Unless you use "wait_stop()", it will attempt to kill
285 the process without waiting the process to finish. By defaults it send
286 "SIGTERM" to the child. You can change that by defining the internal
287 attribute "_default_kill_signal". Note, if you want to be *sure* that
288 the process gets killed, you can enable the "blocking_stop" attribute,
289 that will attempt to send "SIGKILL" after "max_kill_attempts" is
290 reached.
291 restart()
293 use Mojo::IOLoop::ReadWriteProcess qw(process);
294 my $p = process( execute => "/path/to/bin" )->restart;
295 It restarts the process if stopped, or if already running, it stops it
297 first.
298 is_running()
300 use Mojo::IOLoop::ReadWriteProcess qw(process);
301 my $p = process( execute => "/path/to/bin" )->start;
302 $p->is_running;
303 Boolean, it inspect if the process is currently running or not.
305 exit_status()
307 use Mojo::IOLoop::ReadWriteProcess qw(process);
308 my $p = process( execute => "/path/to/bin" )->start;
309 $p->wait_stop->exit_status;
311 Inspect the process exit status, it does the shifting magic, to access
313 to the real value call "_status()".
314 return_status()
316 use Mojo::IOLoop::ReadWriteProcess qw(process);
317 my $p = process( sub { return 42 } )->start;
318 my $s = $p->wait_stop->return_status; # 42
320 Inspect the codeblock return.
322 enable_subreaper()
324 use Mojo::IOLoop::ReadWriteProcess qw(process);
325 my $p = process()->enable_subreaper;
326 Mark the current process (not the child) as subreaper. This is used
328 typically if you want to mark further childs as subreapers inside other
329 forks.
330 my $master_p = process(
332 sub {
333 my $p = shift;
334 $p->enable_subreaper;
335 process(sub { sleep 4; exit 1 })->start();
337 process(
338 sub {
339 sleep 4;
340 process(sub { sleep 1; })->start();
341 })->start();
342 process(sub { sleep 4; exit 0 })->start();
343 process(sub { sleep 4; die })->start();
344 my $manager
345 = process(sub { sleep 2 })->subreaper(1)->start();
346 sleep 1 for (0 .. 10);
347 $manager->stop;
348 return $manager->session->all->size;
349 });
350 $master_p->subreaper(1);
352 $master_p->on(collected => sub { $status++ });
354 # On start we setup the current process as subreaper
356 # So it's up on us to disable it after process is done.
357 $master_p->on(stop => sub { shift()->disable_subreaper });
358 $master_p->start();
359 disable_subreaper()
361 use Mojo::IOLoop::ReadWriteProcess qw(process);
362 my $p = process()->disable_subreaper;
363 Unset the current process (not the child) as subreaper.
365 prctl()
367 use Mojo::IOLoop::ReadWriteProcess qw(process);
368 my $p = process();
369 $p->prctl($option, $arg2, $arg3, $arg4, $arg5);
370 Internal function to execute and wrap the prctl syscall, accepts the
372 same arguments as prctl.
373 diag()
375 use Mojo::IOLoop::ReadWriteProcess qw(process);
376 my $p = process(sub { print "Hello\n" });
377 $p->on( stop => sub { shift->diag("Done!") } );
378 $p->start->wait_stop;
379 Internal function to print information to STDERR if verbose attribute
381 is set or either DEBUG mode enabled. You can use it if you wish to
382 display information on the process status.
383 to_ioloop()
385 use Mojo::IOLoop::ReadWriteProcess qw(process);
386 my $p = process(sub { print "Hello from first process\n"; sleep 1 });
388 $p->start(); # Start and sets the handlers
390 my $stream = $p->to_ioloop; # Get the stream and demand to IOLoop
391 my $output;
392 # Hook on Mojo::IOLoop::Stream events
394 $stream->on(read => sub { $output .= pop; $p->is_running ... });
395 Mojo::IOLoop->singleton->start() unless Mojo::IOLoop->singleton->is_running;
397 Returns a Mojo::IOLoop::Stream object and demand the wait operation to
399 Mojo::IOLoop. It needs "set_pipes" enabled. Default IOLoop can be
400 overridden in "ioloop()".
401 wait()
403 use Mojo::IOLoop::ReadWriteProcess qw(process);
404 my $p = process(sub { print "Hello\n" })->wait;
405 # ... here now you can mangle $p handlers and such
406 Waits until the process finishes, but does not performs cleanup
408 operations (until stop is called).
409 wait_stop()
411 use Mojo::IOLoop::ReadWriteProcess qw(process);
412 my $p = process(sub { print "Hello\n" })->start->wait_stop;
413 # $p is not running anymore, and all possible events have been granted to be emitted.
414 Waits until the process finishes, and perform cleanup operations.
416 errored()
418 use Mojo::IOLoop::ReadWriteProcess qw(process);
419 my $p = process(sub { die "Nooo" })->start->wait_stop;
420 $p->errored; # will return "1"
421 Returns a boolean indicating if the process had errors or not.
423 write_pidfile()
425 use Mojo::IOLoop::ReadWriteProcess qw(process);
426 my $p = process(sub { die "Nooo" } );
427 $p->pidfile("foobar");
428 $p->start();
429 $p->write_pidfile();
430 Forces writing PID of process to specified pidfile in the attributes of
432 the object. Useful only if the process have been already started,
433 otherwise if a pidfile it's supplied as attribute, it will be done
434 automatically.
435 write_stdin()
437 use Mojo::IOLoop::ReadWriteProcess qw(process);
438 my $p = process(sub { my $a = <STDIN>; print STDERR "Hello my name is $a\n"; } )->start;
439 $p->write_stdin("Larry");
440 $p->read_stderr; # process STDERR will contain: "Hello my name is Larry\n"
441 Write data to process STDIN.
443 write_channel()
445 use Mojo::IOLoop::ReadWriteProcess qw(process);
446 my $p = process(sub {
447 my $self = shift;
448 my $parent_output = $self->channel_out;
449 my $parent_input = $self->channel_in;
450 while(defined(my $line = <$parent_input>)) {
452 print $parent_output "PONG\n" if $line =~ /PING/i;
453 }
454 } )->start;
455 $p->write_channel("PING");
456 my $out = $p->read_channel;
457 # $out is PONG
458 my $child_output = $p->channel_out;
459 while(defined(my $line = <$child_output>)) {
460 print "Process is replying back with $line!\n";
461 $p->write_channel("PING");
462 }
463 Write data to process channel. Note, it's not STDIN, neither STDOUT,
465 it's a complete separate channel dedicated to parent-child
466 communication. In the parent process, you can access to the same pipes
467 (but from the opposite direction):
468 my $child_output = $self->channel_out;
470 my $child_input = $self->channel_in;
471 read_stdout()
473 use Mojo::IOLoop::ReadWriteProcess qw(process);
474 my $p = process(sub {
475 print "Boo\n"
476 } )->start;
477 $p->read_stdout;
478 Gets a single line from process STDOUT.
480 read_channel()
482 use Mojo::IOLoop::ReadWriteProcess qw(process);
483 my $p = process(sub {
484 my $self = shift;
485 my $parent_output = $self->channel_out;
486 my $parent_input = $self->channel_in;
487 print $parent_output "PONG\n";
489 } )->start;
490 $p->read_channel;
491 Gets a single line from process channel.
493 read_stderr()
495 use Mojo::IOLoop::ReadWriteProcess qw(process);
496 my $p = process(sub {
497 print STDERR "Boo\n"
498 } )->start;
499 $p->read_stderr;
500 Gets a single line from process STDERR.
502 read_all_stdout()
504 use Mojo::IOLoop::ReadWriteProcess qw(process);
505 my $p = process(sub {
506 print "Boo\n"
507 } )->start;
508 $p->read_all_stdout;
509 Gets all the STDOUT output of the process.
511 read_all_channel()
513 use Mojo::IOLoop::ReadWriteProcess qw(process);
514 my $p = process(sub {
515 shift->channel_out->write("Ping")
516 } )->start;
517 $p->read_all_channel;
518 Gets all the channel output of the process.
520 read_all_stderr()
522 use Mojo::IOLoop::ReadWriteProcess qw(process);
523 my $p = process(sub {
524 print STDERR "Boo\n"
525 } )->start;
526 $p->read_all_stderr;
527 Gets all the STDERR output of the process.
529 send_signal()
531 use Mojo::IOLoop::ReadWriteProcess qw(process);
532 use POSIX;
533 my $p = process( execute => "/path/to/bin" )->start;
534 $p->send_signal(POSIX::SIGKILL);
536 Send a signal to the process
538
540 parallel()
541 use Mojo::IOLoop::ReadWriteProcess qw(parallel);
542 my $pool = parallel sub { print "Hello\n" } => 5;
543 $pool->start();
544 $pool->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
545 $pool->stop();
546 Returns a Mojo::IOLoop::ReadWriteProcess::Pool object that represent a
548 group of processes.
549 It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess, and
551 the last one represent the number of processes to generate.
552 batch()
554 use Mojo::IOLoop::ReadWriteProcess qw(batch);
555 my $pool = batch;
556 $pool->add(sub { print "Hello\n" });
557 $pool->on(stop => sub { shift->_diag("Done!") })->start->wait_stop;
558 Returns a Mojo::IOLoop::ReadWriteProcess::Pool object generated from
560 supplied arguments. It accepts as input the same parameter of
561 Mojo::IOLoop::ReadWriteProcess::Pool constructor ( see parallel() ).
562 process()
564 use Mojo::IOLoop::ReadWriteProcess qw(process);
565 my $p = process sub { print "Hello\n" };
566 $p->start()->wait_stop;
567 or even:
569 process(sub { print "Hello\n" })->start->wait_stop;
571 Returns a Mojo::IOLoop::ReadWriteProcess object that represent a
573 process.
574 It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess.
576 queue()
578 use Mojo::IOLoop::ReadWriteProcess qw(queue);
579 my $q = queue;
580 $q->add(sub { return 42 } );
581 $q->consume;
582 Returns a Mojo::IOLoop::ReadWriteProcess::Queue object that represent a
584 queue.
585
587 You can set the MOJO_EVENTEMITTER_DEBUG environment variable to get
588 some advanced diagnostics information printed to STDERR.
589 MOJO_EVENTEMITTER_DEBUG=1
591 Also, you can set MOJO_PROCESS_DEBUG environment variable to get
593 diagnostics about the process execution.
594 MOJO_PROCESS_DEBUG=1
596
598 Copyright (C) Ettore Di Giacinto.
599 This library is free software; you can redistribute it and/or modify it
601 under the same terms as Perl itself.
602
604 Ettore Di Giacinto <edigiacinto@suse.com>
605perl v5.28.1 2019-02-02 Mojo::IOLoop::ReadWriteProcess(3)