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

Proc::Lite

COPYRIGHT

Copyright (c) 2009, 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.