Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Blocking.pm view on Meta::CPAN
use v5.40;
package Acme::Parataxis::Blocking v0.1.3 {
use Config;
use Exporter qw[import];
use Carp qw[croak];
use Acme::Parataxis qw[fiber await_sleep await_read];
use Acme::Parataxis::Future;
use Acme::Parataxis::Semaphore;
our %EXPORT_TAGS = (
all => [
our @EXPORT_OK
= qw[
spawn_blocking set_max_blocking_threads max_blocking_threads
spawn_blocking_fork set_max_blocking_forks max_blocking_forks kill_blocking_fork
]
]
);
# spawn_blocking interpreter pool: at most $SB_MAX background interpreters run closures at once, bounded by an
# Acme::Parataxis::Semaphore created on first use (PARATAXIS_SB_THREADS overrides the default 4).
my $SB_MAX = do { my $e = $ENV{PARATAXIS_SB_THREADS}; ( defined $e && $e =~ /\A[1-9][0-9]*\z/ ) ? int($e) : 4 };
my $SB_PERMITS; # Acme::Parataxis::Semaphore, capacity $SB_MAX; down() before a thread spawn, up() at reap
# spawn_blocking_fork process pool: a separate semaphore and a separate cap, because a forked child and a cloned
# interpreter are different resources and coupling them would make one starve the other silently.
my $SBF_MAX = do { my $e = $ENV{PARATAXIS_SBF_FORKS}; ( defined $e && $e =~ /\A[1-9][0-9]*\z/ ) ? int($e) : 4 };
my $SBF_PERMITS; # Acme::Parataxis::Semaphore, capacity $SBF_MAX; down() before a fork, up() at reap
my %SBF_CHILDREN; # Future address => the pid of the child that will resolve it, so kill_blocking_fork() can find it
# Read exactly $want bytes off a pipe, parking between chunks, and return what arrived. Deliberately not built on
# await_read's return value: that is a readiness flag (1) rather than a byte count, and a closed write end reports
# readiness too, so 0 bytes off sysread here is the only honest EOF signal. A negative readiness means the child is
# simply still busy, which is not an error and never ends the read.
sub _fork_read_exactly ( $fh, $want, $timeout ) {
my $buf = '';
while ( length($buf) < $want ) {
my $ready = await_read( $fh, $timeout );
# The deadline came round with the child still running: its own runtime is the only clock that matters here
next if $ready < 0;
my $n = sysread( $fh, my $chunk, $want - length($buf) );
last if !defined($n) || $n == 0; # write end closed, or the pipe broke
$buf .= $chunk;
}
return $buf;
}
# Reap a child without blocking the run loop, and return its exit status as (exited, status, signal).
# WNOHANG in a park loop rather than a blocking waitpid: the loop's other fibers have to keep running.
sub _fork_reap ($pid) {
my $reaped = 0;
while ( ( $reaped = waitpid( $pid, POSIX::WNOHANG() ) ) == 0 ) { await_sleep(1) }
return ( 1, $? >> 8, $? & 127 ) if $reaped == $pid;
return ( 0, undef, undef ); # already reaped by something else, or not ours
}
# Index at which user arguments start in @_: 0 when it is a plain call, 1 when $_[0] is a self (package name or
# blessed object). Mirrors the dance in Acme::Parataxis: read $_[0] instead of shifting, so calling this never
# reifies the caller's pad @_. A reified @_ left behind in a parked frame trips pp_entersub's invariants when a
# different fiber later enters the same sub at the same depth.
sub _arg_offset {
my $self = $_[0];
return ( defined $self && ( ( ref $self || $self ) eq __PACKAGE__ || ( builtin::blessed($self) && $self->isa(__PACKAGE__) ) ) ) ? 1 : 0;
}
# Run a CPU-bound closure on a dedicated background Perl interpreter, with its result arriving as a normal Future.
#
# The C pool cannot do this: those workers execute C waits (sleep/read/write) only, so a real Perl closure needs a
# real ithread. Each call therefore clones the interpreter with threads->create (the whole point of Loom's
# worker_threads and the honest thread-per-task trade: the dense clone cost is paid per call, but the closure runs
# in complete isolation and the scheduler is never touched while it does). The bounds and the copy-in/copy-back
# rules are deliberate:
#
# * capacity - at most set_max_blocking_threads() interpreters run at once (default 4, PARATAXIS_SB_THREADS or a
# call before first use change it). Excess spawn_blocking calls park the *calling* fiber on a Semaphore until
# a slot frees, so the bound is a true concurrency cap like the C pool's.
# * copy-in - the closure sees only a snapshot of the caller's world taken at spawn: its args (threads->create
# args) and whatever its captured lexicals held at that instant. Threads share nothing, so in-place mutations
# and later writes to shared/holder state never leak back.
# * copy-back - the return value must survive threads::shared::shared_clone: plain scalars and nested
# arrays/hashes of them (blessed plain structures included) cross; an unshareable result (a CODE ref, a
# resource) becomes the Future's error instead. A die() in the closure likewise lands on the Future as its
# error.
# * no scheduler objects - the closure must not call back into Acme::Parataxis APIs (spawn_blocking or any
# blocking await) while it runs; the worker's interpreter is a copy and its scheduler state is read-only.
#
# The returned Future composes with await / with_timeout / with_cancel / wait_all exactly like any other, because
# the harvest is a plain scheduler fiber resolving an Acme::Parataxis::Future. Cancelling the *await* does not
# stop the closure (a real OS thread cannot be yanked); it only withdraws the waiter, and the slot is released
# when the closure actually finishes. Wall-clock only: spawn_blocking croaks inside run(virtual => 1), since real
# OS work cannot be fast-forwarded by the mock clock.
sub spawn_blocking {
my $o = _arg_offset( $_[0] );
my $code = $_[$o];
my @args = @_[ $o + 1 .. $#_ ];
@_ = ();
croak 'spawn_blocking() requires a CODE ref' unless ref $code eq 'CODE';
croak 'spawn_blocking() requires a Perl built with thread support (useithreads)'
unless defined $Config{useithreads} && $Config{useithreads} eq 'define';
croak 'spawn_blocking() must be called from inside a scheduled fiber (inside run())' if Acme::Parataxis->current_fid < 0;
croak 'spawn_blocking() is wall-clock only and cannot be driven by the mock clock of run(virtual => 1)'
if defined Acme::Parataxis->virtual_now;
state $loaded = do {
require threads;
require threads::shared;
require Thread::Queue;
1;
};
$SB_PERMITS //= Acme::Parataxis::Semaphore->new( count => $SB_MAX );
my $fut = Acme::Parataxis::Future->new;
my $q = Thread::Queue->new;
$SB_PERMITS->down('spawn_blocking capacity');
my $thr = eval {
threads->create(
# The worker's whole world is the closure: run it, marshall the return value (or capture a die() as the
# error) with shared_clone, and push one payload back. Anything unshareable fails the eval and comes
# back as the error, never a crash in the caller.
sub {
my ( $c, $a, $oq ) = @_;
my $payload = eval { [ 1, threads::shared::shared_clone( $c->(@$a) ), undef ] };
$payload = [ 0, undef, threads::shared::shared_clone($@) ] unless $payload;
$oq->enqueue($payload);
1;
},
$code,
\@args,
$q,
);
};
if ( !$thr ) {
my $err = $@ || 'thread creation failed';
$SB_PERMITS->up;
$fut->set_error($err);
return $fut;
}
# The harvester keeps the run loop awake with a 1ms poll sleep (await_sleep rides the matching wall-clock path
# - loop timers when a driver is attached, the worker poll otherwise - and the loop therefore never idles or
# false-deadlocks while an interpreter is out), then reaps the payload, resolves the Future and hands the
# capacity slot to the next waiting spawn_blocking caller. Independent of the caller's cancellation scopes, so
# an abandoned await never strands a slot beyond the closure's own runtime. The payload is enqueued as the
# worker's last act, so reaping it with $thr->join (instead of detach) returns immediately AND retires the
# interpreter before global destruction - a detached thread still registered at exit trips threads.pm's
# "Can't undef active subroutine during global destruction" on some builds and corrupts the exit status.
eval {
fiber {
while ( $q->pending == 0 ) { await_sleep(1) }
my $payload = $q->dequeue_nb; # the one queued item: the [ok, result, error] payload
$thr->join;
$SB_PERMITS->up;
if ( $payload->[0] ) { $fut->set_result( $payload->[1] ) }
else { $fut->set_error( $payload->[2] ) }
1;
};
1;
} or
do {
my $err = $@;
$thr->join;
$SB_PERMITS->up;
$fut->set_error($err);
};
return $fut;
}
# Run a CPU-bound closure in a forked child process and return its result as a normal Future.
#
# This is the same promise spawn_blocking makes, for a perl with no thread support. It is a separate entry point
# rather than a backend switch inside spawn_blocking on purpose: the two have genuinely different limits, and a
# caller should be able to see them at the call site instead of inheriting a silent per-build difference.
#
# * no threads at all - the point. Nothing here requires threads, threads::shared or Thread::Queue, so a plain
# perl gets CPU offload and keeps the property that loading this distribution acquires no threads association.
# * copy-in by fork, copy-out by Storable - the child starts as a copy of the whole parent address space, so the
# closure sees the caller's world as it was at the fork: its args, and whatever its captured lexicals held
# then. Nothing the child does to memory comes back; the only thing that travels is the frozen result. A
# result Storable cannot store (a CODE ref, a resource) becomes the Future's error, as does a die().
# * the closure must not call back into Acme::Parataxis - the child's interpreter is a copy whose scheduler state
# is meaningless, and it holds copies of the parent's descriptors (including any attached driver's sockets), so
# a closure that reads or writes through one of those would act on a copy of a descriptor, not the original.
# Inherited descriptors also keep their ports busy until the child exits, which is worth knowing when a closure
# is short but a run is long.
# * cancellation kills - unlike the thread pool, this one can actually stop the work. Cancelling the *await*
# still only withdraws the waiter, exactly as with spawn_blocking, so nothing changes by accident; when you do
# want the work to stop, call kill_blocking_fork($future) and the child is signalled (TERM by default).
# * a harvester fiber always runs - it is scheduled independently of whether anyone awaits the Future, so the
# pipe is drained and the child reaped even if the caller never looks at the result. That is also what keeps a
# large result from deadlocking: a closure whose payload exceeds the pipe buffer blocks in write until the
# harvester's next chunk, which is the design working, not a hang.
# * wall-clock only, like spawn_blocking: real processes cannot be fast-forwarded, so this croaks under
# run( virtual => 1 ).
sub spawn_blocking_fork {
my $o = _arg_offset( $_[0] );
my $code = $_[$o];
my @args = @_[ $o + 1 .. $#_ ];
@_ = ();
croak 'spawn_blocking_fork() requires a CODE ref' unless ref $code eq 'CODE';
croak 'spawn_blocking_fork() is not available on this platform (no fork(2); d_fork is ' .
( defined $Config{d_fork} ? $Config{d_fork} : 'undef' ) . ')'
unless $Config{d_fork} && $Config{d_fork} eq 'define';
croak 'spawn_blocking_fork() is not available on MSWin32, where perl\'s fork() is a threads.pm emulation' if $^O eq 'MSWin32';
croak 'spawn_blocking_fork() must be called from inside a scheduled fiber (inside run())' if Acme::Parataxis->current_fid < 0;
croak 'spawn_blocking_fork() is wall-clock only and cannot be driven by the mock clock of run(virtual => 1)'
if defined Acme::Parataxis->virtual_now;
state $have_marshal = do { require POSIX; require Storable; 1 };
my $fut = Acme::Parataxis::Future->new;
pipe( my $rd, my $wr ) or do {
$fut->set_error("spawn_blocking_fork() could not create a pipe: $!");
return $fut;
};
$SBF_PERMITS //= Acme::Parataxis::Semaphore->new( count => $SBF_MAX );
$SBF_PERMITS->down('spawn_blocking_fork capacity');
# The fork itself. The child shares nothing with the parent but this pipe, and it must leave through
# POSIX::_exit rather than exit: a normal exit would run END blocks and global destruction over a heap it only
# borrowed, letting the child's destructors touch a copy of the parent's objects. _exit also means the child's
# copy of the parent's buffered STDOUT is never flushed a second time.
my $pid = CORE::fork();
if ( !defined $pid ) {
my $err = "spawn_blocking_fork() could not fork: $!";
close $rd;
close $wr;
$SBF_PERMITS->up;
$fut->set_error($err);
return $fut;
}
if ( !$pid ) { # child
close $rd;
# One tagged frame on the wire: a 1-byte tag, then a length-prefixed body. The tag is what tells the
# parent which of three things it is looking at, so the body is always a single string and exactly one
# length is ever transmitted - framing an array by its element count instead of its byte count is the
# kind of mistake that only shows up as a mystifying "Storable binary image v24.4 more recent than I am".
my ( $tag, $body );
( run in 0.964 second using v1.01-cache-2.11-cpan-234fa220139 )