Reaper(3)

🦋 Reaper(3) — the User Contributed Perl Documentation bestie you didn't know you needed 💅

okay so. this is the manual page for Reaper, and it lives in the User Contributed Perl Documentation section, section 3, and honestly? it's giving "underrated hero." let's get into it ✨

---

🌸 NAME 🌸

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

like. it reaps. children. no cap. 🫶

---

✨ SYNOPSIS ✨

here's the vibe, look at this:

  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...
  }

iconic. gorgeous. register the pid, then later go check if it dipped and what it said on the way out. periodt 💖

---

💜 DESCRIPTION 💜

okay so here's the tea, bestie: perl has an annoying little problem with child processes. and like — technically it's not a perl-specific problem, it's just that with perl it's somewhat more difficult. the struggle is 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. zombie children? in this economy?? no thank you 😭

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. clean. elegant. correct. but here's the problem — different modules may step on each other in installing their own version of the handler, and there's no uniform way of doing this. it's giving chaos. it's giving "everyone's yelling at once." 💀

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. like, the handler could be gone by then. gone gone. 🙈

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 plays nice, it shares, it's a good citizen 🎀

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. so like... cooperate, bestie. it's a group project. 😌

---

🔥 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. so it's not picky about who the parent is, it just handles business 👑

• 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. consent-first reaping, we love to see it 💅
• 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), it returns undef. so undef = "they're still out there living their life," basically 🌈

---

🌟 AUTHOR 🌟

Jeremy Slade <jeremy@jkslade.net>

thank you for your service, king 🫶

---

😭 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

not the pod being messy in public 💀 the documentation itself has a lil formatting oopsie and honestly? relatable. we've all been there. moving on ✨

---

and that's the whole page, bestie! this one came to you via perl v5.42.0, dated 2025-07-25, and yes it really is titled Reaper(3) — go forth and reap responsibly 🎀🦋💖