NAME

       System::Command::Reaper - Reap processes started by System::Command

SYNOPSIS

       This class is used for internal purposes.  Move along, nothing to see here.

DESCRIPTION

       The System::Command objects delegate the reaping of child processes to
       System::Command::Reaper objects. This allows a user to create a System::Command and
       discard it after having obtained one or more references to its handles connected to the
       child process.

       The typical use case looks like this:

           my $fh = System::Command->new( @cmd )->stdout();

       The child process is reaped either through a direct call to "close()" or when the command
       object and all its handles have been destroyed, thus avoiding zombies (which would be
       reaped by the system at the end of the main program).

       This is possible thanks to the following reference graph:

               System::Command
                |   |   |  ^|
                v   v   v  !|
               in out err  !|
               ^|  ^|  ^|  !|
               !v  !v  !v  !v
           System::Command::Reaper

       Legend:
           | normal ref
           ! weak ref

       The System::Command::Reaper object acts as a sentinel, that takes care of reaping the
       child process when the original System::Command and its filehandles have been destroyed
       (or when System::Command "close()" method is being called).

METHODS

       System::Command::Reaper supports the following methods:

   new
           my $reaper = System::Command::Reaper->new( $cmd, \%extra );

       Create a new System::Command::Reaper object attached to the System::Command object passed
       as a parameter.

       An optional hash reference can be used to pass extra attributes to the object.

   close
           $reaper->close();

       Close all the opened filehandles of the main System::Command object, reaps the child
       process, and updates the main object with the status information of the child process.

       "DESTROY" calls "close()" when the sentinel is being destroyed.

   is_terminated
           if ( $reaper->is_terminated ) {...}

       Returns a true value if the underlying process was terminated.

       If the process was indeed terminated, collects exit status, etc.

   Accessors
       The attributes of a System::Command::Reaper object are also accessible through a number of
       accessors.

       The object returned by "new()" will have the following attributes defined (as copied from
       the System::Command object that created the reaper):

       pid The PID of the underlying command.

       stdin
           A filehandle opened in write mode to the child process' standard input.

       stdout
           A filehandle opened in read mode to the child process' standard output.

       stderr
           A filehandle opened in read mode to the child process' standard error output.

       After the call to "close()" or after "is_terminated()" returns true, the following
       attributes will be defined:

       exit
           The exit status of the underlying command.

       core
           A boolean value indicating if the command dumped core.

       signal
           The signal, if any, that killed the command.

AUTHOR

       Philippe Bruhat (BooK), "<book at cpan.org>"

ACKNOWLEDGEMENTS

       This scheme owes a lot to Vincent Pit who on #perlfr provided the general idea (use a
       proxy to delay object destruction and child process reaping) with code examples, which I
       then adapted to my needs.

COPYRIGHT

       Copyright 2010-2016 Philippe Bruhat (BooK), all rights reserved.

LICENSE

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.