NAME
IPC::Open3::Callback - An extension to IPC::Open3 that will feed out
and err to callbacks instead of requiring the caller to handle them.
VERSION
version 1.14
SYNOPSIS
use IPC::Open3::Callback;
my $runner = IPC::Open3::Callback->new( {
out_callback => sub {
my $data = shift;
my $pid = shift;
print( "$pid STDOUT: $data\n" );
},
err_callback => sub {
my $data = shift;
my $pid = shift;
print( "$pid STDERR: $data\n" );
} } );
my $exit_code = $runner->run_command( 'echo Hello World' );
use IPC::Open3::Callback qw(safe_open3);
my ($pid, $in, $out, $err) = safe_open3( "echo", "Hello", "world" );
$buffer = '';
my $select = IO::Select->new();
$select->add( $out );
while ( my @ready = $select->can_read( 5 ) ) {
foreach my $fh ( @ready ) {
my $line;
my $bytes_read = sysread( $fh, $line, 1024 );
if ( ! defined( $bytes_read ) && !$!{ECONNRESET} ) {
die( "error in running ('echo $echo'): $!" );
}
elsif ( ! defined( $bytes_read) || $bytes_read == 0 ) {
$select->remove( $fh );
next;
}
else {
if ( $fh == $out ) {
$buffer .= $line;
}
else {
die( "impossible... somehow got a filehandle i dont know about!" );
}
}
}
}
waitpid( $pid, 0 );
my $exit_code = $? >> 8;
print( "$pid exited with $exit_code: $buffer\n" ); # 123 exited with 0: Hello World
DESCRIPTION
This module feeds output and error stream from a command to supplied
callbacks. Thus, this class removes the necessity of dealing with
IO::Select by hand and also provides a workaround for the bad
reputation associated with Microsoft Windows' IPC.
EXPORT_OK
safe_open3( $command, $arg1, ..., $argN )
Passes the command and arguments on to open3 and returns a list
containing:
pid
The process id of the forked process.
stdin
An IO::Handle to STDIN for the process.
stdout
An IO::Handle to STDOUT for the process.
stderr
An IO::Handle to STDERR for the process.
As with open3, it is the callers responsibility to waitpid to ensure
forked processes do not become zombies.
This method works for both *nix and Microsoft Windows OS's. On a
Windows system, it will use sockets per
http://www.perlmonks.org/index.pl?node_id=811150.
safe_open3_with( $in_handle, $out_handle, $err_handle, $command, $arg1,
..., $argN )
The same as safe_open3 except that you can specify the handles to be
used instead of having safe_open3 generate them. Each handle can be
undef. In fact, safe_open3 just calls safe_open3_with(undef, undef,
undef, @command). The return values are the same except that undef will
be returned for each handle corresponding to the same stream as a
supplied handle. For example, if you specify an $out_handle then undef
will be returned for the STDOUT handle.
CONSTRUCTORS
new( \%options )
The constructor creates a new Callback object and optionally sets
global callbacks for STDOUT and STDERR streams from commands that will
get run by this object (can be overridden per call to run_command). The
currently available options are:
out_callback
out_callback
err_callback
err_callback
buffer_output
buffer_output
buffer_size
buffer_size
select_timeout
select_timeout
ATTRIBUTES
get_buffer_output()
set_buffer_output( $boolean )
A boolean value, if true, will buffer output and send to callback one
line at a time (waits for '\n'). Otherwise, sends text in the same
chunks returned by sysread.
get_buffer_size()
set_buffer_size( $bytes )
The size of the read buffer (in bytes) supplied to sysread.
get_err_callback()
set_err_callback( &subroutine )
A subroutine that will be called for each chunk of text written to
STDERR. The subroutine will be called with the same 2 arguments as
out_callback.
get_last_command()
The last command run by the run_command method.
get_last_exit_code()
The exit code of the last command run by the run_command method.
get_out_callback()
set_out_callback( &subroutine )
A subroutine that will be called whenever a chunk of output is sent to
STDOUT by the opened process. The subroutine will be called with 2
arguments:
data
A chunk of text written to the stream
pid
The pid of the forked process
get_pid()
Will return the pid of the currently running process. This pid is set
by run_command and will be cleared out when the run_command completes.
get_select_timeout()
set_select_timeout( $seconds )
The timeout, in seconds, provided to IO::Select, by default 0 meaning
no timeout which will cause the loop to block until output is ready on
either STDOUT or STDERR.
METHODS
run_command( $command, $arg1, ..., $argN, \%options )
Will run the specified command with the supplied arguments by passing
them on to safe_open3. Arguments can be embedded in the command string
and are thus optional.
If the last argument to this method is a hashref (ref(@_[-1]) eq
'HASH'), then it is treated as an options hash. The supported allowed
options are the same as the constructor and will be used in preference
to the values set by the constructor or any of the setters. These
options will be used for this single call, and will not modify the
Callback object itself. run_command supports three additional options
not supported by the constructor. They are:
in_handle
An IO::Handle from which STDIN will be read.
out_handle
An IO::Handle to which STDOUT will be written.
err_handle
An IO::Handle to which STDERR will be written.
These handle options can be mixed with regular options and if multiple
are specified on the same stream, the handle version will be used
instead of the callback.
Returns the exit code from the command.
AUTHORS
* Lucas Theisen <lucastheisen@pastdev.com>
* Alceu Rodrigues de Freitas Junior <arfreitas@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Lucas Theisen.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
SEE ALSO
Please see those modules/websites for more information related to this
module.
* IPC::Open3
* IPC::Open3::Callback::Command
* IPC::Open3::Callback::CommandRunner
* https://github.com/lucastheisen/ipc-open3-callback
* http://stackoverflow.com/q/16675950/516433