use IO::Async::Process;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new;
my $process = IO::Async::Process->new(
command => [ "tr", "a-z", "n-za-m" ],
stdin => {
from => "hello world\n",
},
stdout => {
on_read => sub {
my ( $stream, $buffref ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "Rot13 of 'hello world' is '$1'\n";
}
return 0;
},
},
on_finish => sub {
$loop->stop;
},
);
$loop->add( $process );
$loop->run;
Also accessible via the ``open_process'' in IO::Async::Loop method:
$loop->open_process(
command => [ "/bin/ping", "-c4", "some.host" ],
stdout => {
on_read => sub {
my ( $stream, $buffref, $eof ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "PING wrote: $1\n";
}
return 0;
},
},
on_finish => sub {
my ( $pid, $exitcode ) = @_;
my $status = ( $exitcode >> 8 );
...
},
);
Note that this has a different name and a different argument order from "Loop->open_process"'s "on_error".
If this is not provided and the process exits with an exception, then "on_finish" is invoked instead, being passed just the exit code.
Since this is just the results of the underlying "$loop->spawn_child" "on_exit" handler in a different order it is possible that the $exception field will be an empty string. It will however always be defined. This can be used to distinguish the two cases:
on_exception => sub {
my ( $self, $exception, $errno, $exitcode ) = @_;
if( length $exception ) {
print STDERR "The process died with the exception $exception " .
"(errno was $errno)\n";
}
elsif( ( my $status = W_EXITSTATUS($exitcode) ) == 255 ) {
print STDERR "The process failed to exec() - $errno\n";
}
else {
print STDERR "The process exited with exit status $status\n";
}
}
$process = IO::Async::Process->new( %args )
Constructs a new "IO::Async::Process" object and returns it.
Once constructed, the "Process" will need to be added to the "Loop" before the child process is started.
Once the "on_finish" continuation has been invoked, the "IO::Async::Process" object is removed from the containing IO::Async::Loop object.
The following parameters may be passed to "new", or to "configure" before the process has been started (i.e. before it has been added to the "Loop"). Once the process is running these cannot be changed.
Once the filehandle is set up, the "fd" method (or its shortcuts of "stdin", "stdout" or "stderr") may be used to access the IO::Async::Handle-subclassed object wrapped around it.
The value of this argument is implied by any of the following alternatives.
$prefork->( $localfd, $childfd )
$pid = $process->pid
Returns the process ID of the process, if it has been started, or "undef" if not. Its value is preserved after the process exits, so it may be inspected during the "on_finish" or "on_exception" events.
$process->kill( $signal )
$running = $process->is_running
Returns true if the Process has been started, and has not yet finished.
$exited = $process->is_exited
Returns true if the Process has finished running, and finished due to normal exit(2).
$status = $process->exitstatus
If the process exited due to normal exit(2), returns the value that was passed to exit(2). Otherwise, returns "undef".
$exception = $process->exception
If the process exited due to an exception, returns the exception that was thrown. Otherwise, returns "undef".
$errno = $process->errno
If the process exited due to an exception, returns the numerical value of $! at the time the exception was thrown. Otherwise, returns "undef".
$errstr = $process->errstr
If the process exited due to an exception, returns the string value of $! at the time the exception was thrown. Otherwise, returns "undef".
$stream = $process->fd( $fd )
Returns the IO::Async::Stream or IO::Async::Socket associated with the given FD number. This must have been set up by a "configure" argument prior to adding the "Process" object to the "Loop".
The returned object have its read or write handle set to the other end of a pipe or socket connected to that FD number in the child process. Typically, this will be used to call the "write" method on, to write more data into the child, or to set an "on_read" handler to read data out of the child.
The "on_closed" event for these streams must not be changed, or it will break the close detection used by the "Process" object and the "on_finish" event will not be invoked.
$stream = $process->stdin $stream = $process->stdout $stream = $process->stderr $stream = $process->stdio
Shortcuts for calling "fd" with 0, 1, 2 or "io" respectively, to obtain the IO::Async::Stream representing the standard input, output, error, or combined input/output streams of the child process.
my $stdout;
my $process = IO::Async::Process->new(
command => [ "writing-program", "arguments" ],
stdout => { into => \$stdout },
on_finish => sub {
print "The process has finished, and wrote:\n";
print $stdout;
}
);
$loop->add( $process );
Note that until "on_finish" is invoked, no guarantees are made about how much of the data actually written by the process is yet in the $stdout scalar.
See also the "run_child" method of IO::Async::Loop.
To handle data more interactively as it arrives, the "on_read" key can instead be used, to provide a callback function to invoke whenever more data is available from the process.
my $process = IO::Async::Process->new(
command => [ "writing-program", "arguments" ],
stdout => {
on_read => sub {
my ( $stream, $buffref ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "The process wrote a line: $1\n";
}
return 0;
},
},
on_finish => sub {
print "The process has finished\n";
}
);
$loop->add( $process );
If the code to handle data read from the process isn't available yet when the object is constructed, it can be supplied later by using the "configure" method on the "stdout" filestream at some point before it gets added to the Loop. In this case, "stdin" should be configured using "pipe_read" in the "via" key.
my $process = IO::Async::Process->new(
command => [ "writing-program", "arguments" ],
stdout => { via => "pipe_read" },
on_finish => sub {
print "The process has finished\n";
}
);
$process->stdout->configure(
on_read => sub {
my ( $stream, $buffref ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "The process wrote a line: $1\n";
}
return 0;
},
);
$loop->add( $process );
my $process = IO::Async::Process->new(
command => [ "reading-program", "arguments" ],
stdin => { from => "Here is the data to send\n" },
on_finish => sub {
print "The process has finished\n";
}
);
$loop->add( $process );
The data in this scalar will be written until it is all consumed, then the handle will be closed. This may be useful if the program waits for EOF on "STDIN" before it exits.
To have the ability to write more data into the process once it has started. the "write" method on the "stdin" stream can be used, when it is configured using the "pipe_write" value for "via":
my $process = IO::Async::Process->new(
command => [ "reading-program", "arguments" ],
stdin => { via => "pipe_write" },
on_finish => sub {
print "The process has finished\n";
}
);
$loop->add( $process );
$process->stdin->write( "Here is some more data\n" );
use Socket qw( SOL_SOCKET SO_RCVBUF );
my $process = IO::Async::Process->new(
command => [ "command-to-read-from-and-write-to", "arguments" ],
stdio => {
via => "socketpair",
prefork => sub {
my ( $parentfd, $childfd ) = @_;
# Set parent end of socket receive buffer to 3 MB
$parentfd->setsockopt(SOL_SOCKET, SO_RCVBUF, 3 * 1024 * 1024);
# Set child end of socket receive buffer to 3 MB
$childfd ->setsockopt(SOL_SOCKET, SO_RCVBUF, 3 * 1024 * 1024);
},
},
);
$loop->add( $process );