/ 
Linux-Event-0.006
/ Linux::Event::Pid

NAME

Linux::Event::Pid - pidfd-backed process exit notifications for Linux::Event

SYNOPSIS

use v5.36;
use Linux::Event;

my $loop = Linux::Event->new;

my $pid = fork() // die "fork: $!";
if ($pid == 0) { exit 42 }

my $sub = $loop->pid($pid, sub ($loop, $pid, $status, $data) {
  $loop->stop;

  if (defined $status) {
    my $code = $status >> 8;
    say "child $pid exited with $code";
  }
});

$loop->run;

DESCRIPTION

This module integrates Linux pid file descriptors (pidfd) into Linux::Event. It opens a pidfd using Linux::FD::Pid and watches it via epoll. When the pidfd becomes readable, the callback is invoked.

This is a Linux-native alternative to SIGCHLD wakeups. Exit status is only available when the watched PID is a child of the current process.

CALLBACK SIGNATURE

sub ($loop, $pid, $status, $data) { ... }

Exactly four arguments are passed. $status is a raw wait status compatible with the usual POSIX wait macros (e.g. WIFEXITED, WEXITSTATUS). If exit status is unavailable, $status is undef.

SEMANTICS

  • One subscription per PID (replacement semantics).

    Registering pid() again for the same PID replaces the previous handler.

  • One-shot delivery.

    When the process exit is observed and a defined wait status is obtained (when reap => 1), the callback is invoked once and the subscription is automatically canceled.

  • Reaping.

    By default reap => 1 and Linux::Event attempts a non-blocking wait via Linux::FD::Pid->wait(WEXITED|WNOHANG). Exit status is only available for child processes; if reaping fails (for example, because the PID is not a child), an exception is thrown. Use reap => 0 to receive an exit notification without attempting to reap or obtain a status.

  • Subscription cancellation is idempotent.

METHODS

pid

my $sub = $loop->pid($pid, $cb, %opts);

Registers a handler for the given $pid. One handler per PID is allowed; registering again replaces the previous handler.

Options:

  • data => $any

    Optional user data passed to the callback.

  • reap => 1|0

    Defaults to 1. If true, Linux::Event attempts to reap the child using a non-blocking wait and passes the wait status. If false, no wait is attempted and $status will be undef.

The returned subscription supports $sub->cancel which is idempotent.

DEPENDENCIES

Requires Linux::FD::Pid and a kernel that supports pidfd_open(2).

AUTHOR

Joshua S. Day

LICENSE

Same terms as Perl itself.

VERSION

This document describes Linux::Event::Pid version 0.006.