NAME
Proc::Hevy - A heavyweight module for running processes synchronously
SYNOPSIS
use Proc::Hevy;
{
my $status = Proc::Hevy->exec(
command => 'cat',
stdin => "Useless use of cat\n",
stdout => \my $stdout,
stderr => \my $stderr,
);
}
{
my $status => Proc::Hevy->exec(
command => [qw( cat - )],
stdin => [ 'Another useless use of cat' ],
stdout => my $stdout = [ ],
stderr => my $stderr = [ ],
);
}
{
my @stdin = qw( foo bar baz );
my ( @stdout, @stderr );
my $status => Proc::Hevy->exec(
command => sub {
while( <STDIN> ) {
my ( $fh, $prefix )
= $. % 2 == 0
? ( \*STDOUT, 'even' )
: ( \*STDERR, 'odd' )
;
print {$fh} "$prefix :: $_";
}
},
stdin => sub { shift @stdin },
stdout => sub { push @stdout, $_[0] },
stderr => sub { push @stderr, $_[0] },
);
}
{
sub cat {
my ( @files ) = @_;
exec cat => '--', @files
}
my $status => Proc::Hevy->exec(
command => [ \&cat, @ARGV ],
stdin => \*STDIN,
stdout => \*STDERR,
stderr => \*STDOUT,
);
}
{
# really useless use of cat
my $status = Proc::Hevy->exec(
command => 'cat </dev/null 1>/dev/null 2>/dev/null',
);
}
{
my $status = Proc::Hevy->exec(
stdout => \*STDOUT,
stderr => \*STDERR,
priority => 10,
command => sub {
print "In child process ($$): command\n";
},
parent => sub {
my ( $pid ) = @_;
print "In parent process ($$): child=$pid\n";
},
child => sub {
my ( $ppid ) = @_;
print "In child process ($$): parent=$ppid\n";
},
);
}DESCRIPTION
Proc::Hevy is a simplistic module for spawning child processes in a synchronous manner. It provides a simple interface for passing data to a process's STDIN while also offering several methods for buffering STDOUT and STDERR output.
METHODS
exec( %args )
exec() starts a child process and buffers input and output according to the given arguments. Once the process exits, the exit status (as in $?) is returned. %args may contain the following options:
command => $command
command => \@command
command => \&code
command => [ \&code, @args ]
Specifies the command to run. The first form may expand shell meta-characters while the second form will not. Review the documentation for exec() for more information. The third form will run the given CODE reference in the child process and the fourth form does the same, but also passes in @args as arguments to the subroutine. This option is required.
stdin => $buffer
stdin => \@buffer
stdin => \&code
stdin => \*GLOB
If specified, identifies a data source that will be used to pipe data to the child process's STDIN handle. The first form simply specifies a string of bytes to write. The second form will write each array element to the child one at a time until the array is empty. The third form will write whatever string is returned by the given CODE reference until undef is returned. Both the second and third forms append the current value of $\ if defined or "\n" if not. The fourth form simply re-opens the child process's STDIN handle to the given filehandle allowing a pass-through effect.
If not specified, the child process's STDIN handle is re-opened to '/dev/null' for reading.
stdout => \$buffer
stdout => \@buffer
stdout => \&code
stdout => \*GLOB
If specified, identifies a data destination that will be used to pipe from the child process's STDOUT handle. The first form will append all input into a single string. The second form will push $/-delimited lines on the given array. The third form will call the given CODE reference for each $/-delimited line passing the line in as a single argument. The fourth form simply re-opens the child process's STDOUT handle to the given filehandle allowing a pass-through effect.
If not specified, the child process's STDOUT handle is re-opened to '/dev/null' for reading.
stderr => \$buffer
stderr => \@buffer
stderr => \&code
stderr => \*GLOB
The options specified here are similar to the stdout options except that the child process's STDERR handle is affected.
parent => \&code
If specified, the given CODE reference is called in the parent process after the fork() is performed. The child process's PID is passed in as a single argument.
child => \&code
If specified, the given CODE reference is called in the child process after the fork() is performed. The parent process's PID is passed in as a single argument.
priority => $delta
If specified, adjusts the child process's priority according to the value specified.
BUGS
None are known at this time, but if you find one, please feel free to submit a report to the author.
AUTHOR
jason hord <pravus@cpan.org>
SEE ALSO
COPYRIGHT
Copyright (c) 2009-2014, jason hord
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.