The event loop: Proc::Spawner::Loop (W5, post-0.10)

One event loop per process, with one interface on POSIX and on Windows. The interface is in the module's POD (lib/Proc/Spawner/Loop.pm); this page says how it works and what was checked. Decision W5: the user, 2026-11-08 ("Use the Windows' way"), 2026-11-09 ("in a separate module, with an "elegant" API which may be shared between your POSIX approach and Win32"; "Can a handler for Ctrl-C report to the loop instead?").

1. The interface, in short

my $loop = Proc::Spawner::Loop->new;                       # always the same object
my $w = $loop->read($fh, 65536, sub { my ($bytes, $errno) = @_ });   # undef at end of file
$loop->write($fh, $bytes, sub { my $errno = shift });     # all written, or the error (EPIPE: the rest dropped)
$loop->child($pid, sub { my $status = shift });           # as $?; undef if other code took it
$loop->after(2.5, sub { ... });                           # a timer
$loop->defer(sub { ... }, @args);
$w->cancel; $w->active;
$loop->wait_until(sub { $done }); $loop->poll;
my ($r, $wr) = $loop->pipe(overlapped => 'r');            # Windows: those ends overlapped

Proc::Spawner's on_read, on_write, defer, wait_until and poll are the same calls under their old names. The rules are those of the page "Child Exit Wake-up" (in pspawn-spawner.md, section 1): every callback runs from the queue, one at a time, never inside a signal or another callback (R1); a callback never waits (D2); process-wide state (SIGCHLD, the console handler) is taken only while wait_until runs (D3).

2. How it works

The front end (Loop.pm) keeps the queue, the timers and the watches; a backend waits.

POSIX (Loop/POSIX.pm): select on the fds; while wait_until runs, a C handler for SIGCHLD writes one byte into a pipe the loop selects on (D1), then waitpid(PID, WNOHANG) for each child watched. (This is the loop as it was before W5, moved.)

Windows (Loop/Win32.pm, in C: win_loop.h): one I/O completion port receives every event.

3. What was checked

| Where | What | Result | |---|---|---| | Linux | the whole suite, also without posix_spawn, through Run (RUN_AS_WIN32=1 too), with /proc hidden | pass | | Linux | the snippet library, ours alone against the table of section 7 of large-subset-state.md | no change from W5 | | Wine | the snippet library | could not run on 2026-11-09 before the shell layer's port (pspawn-spawner.md, section 8; ported later that day: pspawn-shell-windows.md), and not run there since; the parser alone over all 45,501 extracted samples gives the same trees as on Linux | | Wine, Strawberry Perl 5.38.2 | t/loop.t: every pipe kind with 300,000 bytes each way, EPIPE, cancelled reads on both kinds of handle, timers, 80 children at once, a child writing into a pipe the loop reads | 17 pass, through both primitives (system1: 60 children, Perl's own table stops at 64) | | Wine, with a console | Ctrl-C sent 0.5 s into a wait that nothing else could end before 3.5 s | %SIG{INT} handler ran at 0.54 s; without our handler only at the next event, 3.54 s | | Wine | alarm 1 during a wait | %SIG{ALRM} handler at 1.02 s | | Wine, with a console | %SIG{INT} at its default; IGNORE | the process ends with Perl's "Terminating on signal SIGINT(2)"; the loop goes on | | Wine | t/loop.t's Ctrl-C test | 18 of 18 with a console; skipped without one | | Wine | perl Makefile.PL, gmake, gmake test of t/loop.t, t/windows.t, t/parsers.t, t/programs.t with Strawberry Perl's own gcc | pass, no warning |

Wine has a console only on a terminal: these runs used a pseudo-terminal (script), and ran Perl directly, since cmd.exe gets the Ctrl-C too and ends (the tricks repository's Wine topic has the details).

Not checked: real Windows. Wine calls console handlers as Windows documents (each event on a thread of its own, the newest handler first), but only Wine was seen.

4. Known limits