1Mojo::IOLoop::ReadWriteUPsreorceCsosn(t3r)ibuted Perl DoMcoujmoe:n:tIaOtLiooonp::ReadWriteProcess(3)
2
3
4

NAME

6       Mojo::IOLoop::ReadWriteProcess - Execute external programs or internal
7       code blocks as separate process.
8

SYNOPSIS

10           use Mojo::IOLoop::ReadWriteProcess;
11
12           # 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
21           # 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
25           # 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
33           # 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
38           # 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
43           # So this works:
44           print $stdin "foo bar\n";
45           my @lines = <$stdout>;
46
47           # 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

DESCRIPTION

53       Mojo::IOLoop::ReadWriteProcess is yet another process manager.
54

EVENTS

56       Mojo::IOLoop::ReadWriteProcess inherits all events from
57       Mojo::EventEmitter and can emit the following new ones.
58
59   start
60        $process->on(start => sub {
61          my ($process) = @_;
62          $process->is_running();
63        });
64
65       Emitted when the process starts.
66
67   stop
68        $process->on(stop => sub {
69          my ($process) = @_;
70          $process->restart();
71        });
72
73       Emitted when the process stops.
74
75   process_error
76        $process->on(process_error => sub {
77          my ($e) = @_;
78          my @errors = @{$e};
79        });
80
81       Emitted when the process produce errors.
82
83   process_stuck
84        $process->on(process_stuck => sub {
85          my ($self) = @_;
86          ...
87        });
88
89       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
94   SIG_CHLD
95        $process->on(SIG_CHLD => sub {
96          my ($self) = @_;
97          ...
98        });
99
100       Emitted when we receive SIG_CHLD.
101
102   SIG_TERM
103        $process->on(SIG_TERM => sub {
104          my ($self) = @_;
105          ...
106        });
107
108       Emitted when the child forked process receives SIG_TERM, before
109       exiting.
110
111   collected
112        $process->on(collected => sub {
113          my ($self) = @_;
114          ...
115        });
116
117       Emitted right after status collection.
118
119   collect_status
120        $process->on(collect_status => sub {
121          my ($self) = @_;
122          ...
123        });
124
125       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

ATTRIBUTES

130       Mojo::IOLoop::ReadWriteProcess inherits all attributes from
131       Mojo::EventEmitter and implements the following new ones.
132
133   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
140       "execute" should contain the external program that you wish to run.
141
142   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
149       It represent the code you want to run in background.
150
151       You do not need to specify "code", it is implied if no arguments is
152       given.
153
154           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
159   args
160           use Mojo::IOLoop::ReadWriteProcess;
161           my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".$_[1] }, args => "User" );
162           $process->start();
163           $process->on( stop => sub { print "Process: ".(+shift()->pid)." finished"; } );
164           $process->stop();
165
166           # The process will print "Hello User"
167
168       Array or arrayref of options to pass by to the external binary or the
169       code block.
170
171   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
178       Set it to 1 if you want to do blocking stop of the process.
179
180   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
187       Set it to 0 if you want to disable internal channels.
188
189   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
195       Returns the current Mojo::IOLoop::ReadWriteProcess::Session singleton.
196
197   subreaper
198           use Mojo::IOLoop::ReadWriteProcess;
199           my $process = Mojo::IOLoop::ReadWriteProcess->new(code => sub { print "Hello ".$_[1] }, args => "User" );
200           $process->subreaper(1)->start();
201           $process->on( stop => sub { shift()->disable_subreaper } );
202           $process->stop();
203
204           # The process will print "Hello User"
205
206       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
210   ioloop
211         my $loop    = $process->ioloop;
212         $subprocess = $process->ioloop(Mojo::IOLoop->new);
213
214       Event loop object to control, defaults to the global Mojo::IOLoop
215       singleton.
216
217   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
224       Defaults to 5, is the number of attempts before bailing out.
225
226       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
229   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
236   serialize
237       Defaults to 0, If enabled data returned from forked process will be
238       serialized with Storable.
239
240   kill_sleeptime
241       Defaults to 1, it's the seconds to wait before attempting SIGKILL when
242       blocking_stop is setted to 1.
243
244   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
248   verbose
249       Defaults to 1, it indicates message verbosity.
250
251   set_pipes
252       Defaults to 1, If enabled, additional pipes for process communication
253       are automatically set up.
254
255   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
260   autoflush
261       Defaults to 1, If enabled autoflush of handlers is enabled
262       automatically.
263
264   error
265       Returns a Mojo::Collection of errors.  Note: errors that can be
266       captured only at the end of the process
267

METHODS

269       Mojo::IOLoop::ReadWriteProcess inherits all methods from
270       Mojo::EventEmitter and implements the following new ones.
271
272   start()
273           use Mojo::IOLoop::ReadWriteProcess qw(process);
274           my $p = process(sub {
275                                 print STDERR "Boo\n"
276                             } )->start;
277
278       Starts the process
279
280   stop()
281           use Mojo::IOLoop::ReadWriteProcess qw(process);
282           my $p = process( execute => "/path/to/bin" )->start->stop;
283
284       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
292   restart()
293           use Mojo::IOLoop::ReadWriteProcess qw(process);
294           my $p = process( execute => "/path/to/bin" )->restart;
295
296       It restarts the process if stopped, or if already running, it stops it
297       first.
298
299   is_running()
300           use Mojo::IOLoop::ReadWriteProcess qw(process);
301           my $p = process( execute => "/path/to/bin" )->start;
302           $p->is_running;
303
304       Boolean, it inspect if the process is currently running or not.
305
306   exit_status()
307           use Mojo::IOLoop::ReadWriteProcess qw(process);
308           my $p = process( execute => "/path/to/bin" )->start;
309
310           $p->wait_stop->exit_status;
311
312       Inspect the process exit status, it does the shifting magic, to access
313       to the real value call "_status()".
314
315   return_status()
316           use Mojo::IOLoop::ReadWriteProcess qw(process);
317           my $p = process( sub { return 42 } )->start;
318
319           my $s = $p->wait_stop->return_status; # 42
320
321       Inspect the codeblock return.
322
323   enable_subreaper()
324           use Mojo::IOLoop::ReadWriteProcess qw(process);
325           my $p = process()->enable_subreaper;
326
327       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
331           my $master_p = process(
332             sub {
333               my $p = shift;
334               $p->enable_subreaper;
335
336               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
351           $master_p->subreaper(1);
352
353           $master_p->on(collected => sub { $status++ });
354
355           # 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
360   disable_subreaper()
361           use Mojo::IOLoop::ReadWriteProcess qw(process);
362           my $p = process()->disable_subreaper;
363
364       Unset the current process (not the child) as subreaper.
365
366   prctl()
367           use Mojo::IOLoop::ReadWriteProcess qw(process);
368           my $p = process();
369           $p->prctl($option, $arg2, $arg3, $arg4, $arg5);
370
371       Internal function to execute and wrap the prctl syscall, accepts the
372       same arguments as prctl.
373
374   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
380       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
384   to_ioloop()
385           use Mojo::IOLoop::ReadWriteProcess qw(process);
386
387           my $p = process(sub {  print "Hello from first process\n"; sleep 1 });
388
389           $p->start(); # Start and sets the handlers
390           my $stream = $p->to_ioloop; # Get the stream and demand to IOLoop
391           my $output;
392
393           # Hook on Mojo::IOLoop::Stream events
394           $stream->on(read => sub { $output .= pop;  $p->is_running ...  });
395
396           Mojo::IOLoop->singleton->start() unless Mojo::IOLoop->singleton->is_running;
397
398       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
402   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
407       Waits until the process finishes, but does not performs cleanup
408       operations (until stop is called).
409
410   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
415       Waits until the process finishes, and perform cleanup operations.
416
417   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
422       Returns a boolean indicating if the process had errors or not.
423
424   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
431       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
436   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
442       Write data to process STDIN.
443
444   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
451                                 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
464       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
469           my $child_output = $self->channel_out;
470           my $child_input  = $self->channel_in;
471
472   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
479       Gets a single line from process STDOUT.
480
481   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
488                                 print $parent_output "PONG\n";
489                             } )->start;
490           $p->read_channel;
491
492       Gets a single line from process channel.
493
494   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
501       Gets a single line from process STDERR.
502
503   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
510       Gets all the STDOUT output of the process.
511
512   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
519       Gets all the channel output of the process.
520
521   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
528       Gets all the STDERR output of the process.
529
530   send_signal()
531           use Mojo::IOLoop::ReadWriteProcess qw(process);
532           use POSIX;
533           my $p = process( execute => "/path/to/bin" )->start;
534
535           $p->send_signal(POSIX::SIGKILL);
536
537       Send a signal to the process
538

EXPORTS

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
547       Returns a Mojo::IOLoop::ReadWriteProcess::Pool object that represent a
548       group of processes.
549
550       It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess, and
551       the last one represent the number of processes to generate.
552
553   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
559       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
563   process()
564           use Mojo::IOLoop::ReadWriteProcess qw(process);
565           my $p = process sub { print "Hello\n" };
566           $p->start()->wait_stop;
567
568       or even:
569
570           process(sub { print "Hello\n" })->start->wait_stop;
571
572       Returns a Mojo::IOLoop::ReadWriteProcess object that represent a
573       process.
574
575       It accepts the same arguments as Mojo::IOLoop::ReadWriteProcess.
576
577   queue()
578           use Mojo::IOLoop::ReadWriteProcess qw(queue);
579           my $q = queue;
580           $q->add(sub { return 42 } );
581           $q->consume;
582
583       Returns a Mojo::IOLoop::ReadWriteProcess::Queue object that represent a
584       queue.
585

DEBUGGING

587       You can set the MOJO_EVENTEMITTER_DEBUG environment variable to get
588       some advanced diagnostics information printed to STDERR.
589
590           MOJO_EVENTEMITTER_DEBUG=1
591
592       Also, you can set MOJO_PROCESS_DEBUG environment variable to get
593       diagnostics about the process execution.
594
595           MOJO_PROCESS_DEBUG=1
596

LICENSE

598       Copyright (C) Ettore Di Giacinto.
599
600       This library is free software; you can redistribute it and/or modify it
601       under the same terms as Perl itself.
602

AUTHOR

604       Ettore Di Giacinto <edigiacinto@suse.com>
605
606
607
608perl v5.30.1                      2020-01-30 Mojo::IOLoop::ReadWriteProcess(3)