1Reaper(3)             User Contributed Perl Documentation            Reaper(3)
2
3
4

NAME

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

SYNOPSIS

9         use Reaper qw( reaper reapPid pidStatus );
10
11         my $pid = fork;
12         if ( $pid == 0 ) { # child
13           exec $some_command;
14         }
15         reapPid ( $pid );
16
17         ...
18
19         if ( defined(my $exit = pidStatus($pid)) ) {
20           # child exited, check the code...
21         }
22

DESCRIPTION

24       perl has an annoying little problem with child processes -- well, it is
25       not actually a problem specific to perl, but it is somewhat more
26       difficult with perl: reaping child processes after they exit so they
27       don't hang around as zombies forever, and doing it in a way that
28       accurately captures the exit code of the child.
29
30       The right way to do it is to install a $SIG{CHLD} handler which calls
31       waitpid to reap the child process and store $? at that point.  But the
32       problem is that different modules may step on each other in installing
33       their own version of the handler, there's no uniform way of doing this.
34
35       For some situations, a local $SIG{CHLD} handler is sufficient, but
36       often times the handler is no longer in scope at the time the child
37       process exits -- since the child may exit at any time.  The local
38       handler is dynamically scoped, not lexically, so it depends entirely on
39       what subroutine is being executed at the time the signal is caught.
40
41       So the Reaper module provides a $SIG{CHLD} handler that can be
42       installed globally as well as locally.  It also supports chaining of
43       signal handlers, meaning it will not just replace an existing
44       $SIG{CHLD} handler.  It still requires applications to do the right
45       thing in using this module and not installing their own versions.  At
46       least it provides a consistent implementation that can be shared
47       between various modules.
48

FUNCTIONS IN DETAIL

50           * reaper BLOCK
51
52           Install a local $SIG{CHLD} handler for a block of code, e.g.:
53
54              reaper {
55                do_something();
56                ...
57              };
58
59           Any children that exit while the block is being executed (whether
60           started within that block or not) will cause the local $SIG{CHLD}
61           to be executed.  The child exit status will be saved, and will be
62           available via the pidStatus() call.
63
64           * reapPid PIDLIST
65
66           Register one or more PIDs to be reaped.  The reaper will only try
67           to reap PIDs that have been registered, so that it does not steal
68           the exit status for a pid from another handler.
69
70           * pidStatus PID
71
72           Return the exit status of a specific PID.  If no status for the PID
73           is available (i.e. the process is still running), returns undef.
74

AUTHOR

76       Jeremy Slade <jeremy@jkslade.net>
77

POD ERRORS

79       Hey! The above document had some coding errors, which are explained
80       below:
81
82       Around line 55:
83           You can't have =items (as at line 151) unless the first thing after
84           the =over is an =item
85
86
87
88perl v5.30.0                      2019-07-26                         Reaper(3)