/ 
Linux-Event-Fork-0.005
/ Linux::Event::Fork

NAME

Linux::Event::Fork - Async child process management for Linux::Event

SYNOPSIS

use v5.36;
use Linux::Event;
use Linux::Event::Fork;

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

# Optional: configure bounded parallelism
my $fork = $loop->fork_helper(max_children => 4);

$loop->fork(
  cmd => [ $^X, '-we', 'print "hello\n"; exit 0' ],

  on_stdout => sub ($child, $chunk) {
    print $chunk;
  },

  on_exit => sub ($child, $exit) {
    print "exit code: " . $exit->code . "\n";
    $loop->stop;
  },
);

$loop->run;

DESCRIPTION

Linux::Event::Fork is a small policy layer built on top of Linux::Event. It provides nonblocking child process management integrated directly into the event loop.

Features include:

  • Nonblocking stdout/stderr capture

  • Streaming stdin

  • Soft timeouts

  • Tagging

  • Bounded parallelism (max_children)

  • Internal queueing

  • drain() callback

  • cancel_queued() support

  • Introspection methods

This module is intentionally minimal. It wires file descriptors, tracks lifecycle, and optionally enforces concurrency limits.

CONFIGURATION

Configuration is performed at runtime:

my $fork = $loop->fork_helper(max_children => 4);

The older compile-time idiom:

use Linux::Event::Fork max_children => 4;

is intentionally removed.

SPAWNING CHILDREN

cmd => [ ... ]

The simplest form. Forks, wires FDs, then execs immediately.

$loop->fork(cmd => [ 'ls', '-l' ]);

child => sub { ... }

Runs Perl code in the child after stdio plumbing.

$loop->fork(
  child => sub {
    exec 'sh', '-c', 'echo hello';
    exit 127;
  },
);

Returning from the callback is treated as failure.

BOUNDED PARALLELISM

my $fork = $loop->fork_helper(max_children => 4);

When the pool is full, fork() returns a Linux::Event::Fork::Request object instead of a running child. Queued requests start automatically when capacity becomes available.

DRAIN

$fork->drain(on_done => sub ($fork) {
  $loop->stop;
});

The callback fires once when:

  • No children are running

  • The queue is empty

CANCEL QUEUED

$fork->cancel_queued(sub ($req) {
  $req->tag eq 'low-priority';
});

Only queued requests are affected. Running children are not modified.

INTROSPECTION

$fork->running;
$fork->queued;
$fork->max_children;

WHAT THIS MODULE IS NOT

This is not:

  • A supervisor

  • A job scheduler

  • A framework

It extends Linux::Event; it does not replace it.

AUTHOR

Joshua S. Day

LICENSE

Same terms as Perl itself.