NAME

Reaper - support for reaping child processes via $SIG{CHLD}

SYNOPSIS

  use Reaper qw( reaper reapPid pidStatus );

  my $pid = fork;
  if ( $pid == 0 ) { # child
    exec $some_command;
  }
  reapPid ( $pid );

  ...

  if ( defined(my $exit = pidStatus($pid)) ) {
    # child exited, check the code...
  }

DESCRIPTION

perl has an annoying little problem with child processes -- well, it is not actually a problem specific to perl, but it is somewhat more difficult with perl: reaping child processes after they exit so they don't hang around as zombies forever, and doing it in a way that accurately captures the exit code of the child.

The right way to do it is to install a $SIG{CHLD} handler which calls waitpid to reap the child process and store $? at that point. But the problem is that different modules may step on each other in installing their own version of the handler, there's no uniform way of doing this.

For some situations, a local $SIG{CHLD} handler is sufficient, but often times the handler is no longer in scope at the time the child process exits -- since the child may exit at any time. The local handler is dynamically scoped, not lexically, so it depends entirely on what subroutine is being executed at the time the signal is caught.

So the Reaper module provides a $SIG{CHLD} handler that can be installed globally as well as locally. It also supports chaining of signal handlers, meaning it will not just replace an existing $SIG{CHLD} handler. It still requires applications to do the right thing in using this module and not installing their own versions. At least it provides a consistent implementation that can be shared between various modules.

FUNCTIONS IN DETAIL

* reaper BLOCK

Install a local $SIG{CHLD} handler for a block of code, e.g.:

   reaper {
     do_something();
     ...
   };

Any children that exit while the block is being executed (whether started within that block or not) will cause the local $SIG{CHLD} to be executed. The child exit status will be saved, and will be available via the pidStatus() call.

* reapPid PIDLIST

Register one or more PIDs to be reaped. The reaper will only try to reap PIDs that have been registered, so that it does not steal the exit status for a pid from another handler.

* pidStatus PID

Return the exit status of a specific PID. If no status for the PID is available (i.e. the process is still running), returns undef.

AUTHOR

Jeremy Slade <jeremy@jkslade.net>

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 55:: You can't have =items (as at line 151) unless the first thing after the =over is an =item