Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis.pm view on Meta::CPAN
return if $all->is_ready;
if ( defined $f->error ) {
$all->set_error( $f->error ); # reject-fast: the first failure wins, copied wholesale
return;
}
$results[$idx] = $f->result;
$all->set_result( \@results ) if --$pending == 0;
}
);
}
return $all;
}
# Aggregate a list of futures into one that settles with a wholesale copy of the first input to settle - success
# or failure (Promise.race). The losers are untouched and keep running; their eventual results are dropped by the
# is_ready guard. An already-ready input settles the aggregate inline. At least one input is required (an empty
# race would never settle) and each input must be an Acme::Parataxis::Future else croaks. Also callable as
# Acme::Parataxis->wait_any(...).
sub wait_any {
my $o = _arg_offset( $_[0] );
my @futures = @_[ $o .. $#_ ];
@_ = ();
croak 'wait_any() requires at least one Acme::Parataxis::Future input' unless @futures;
croak 'wait_any() requires Acme::Parataxis::Future inputs'
if grep { !( defined $_ && ref $_ && $_->isa('Acme::Parataxis::Future') ) } @futures;
require Acme::Parataxis::Future;
my $any = Acme::Parataxis::Future->new;
for my $f (@futures) {
$f->on_ready(
sub ($f) {
return if $any->is_ready;
if ( defined $f->error ) { $any->set_error( $f->error ) } # wholesale copy of the failure
else { $any->set_result( $f->result ) }
}
);
}
return $any;
}
sub yield {
my $is_self = _arg_offset( $_[0] );
my @deposit = ();
push @deposit, $_[$_] for ( $is_self ? 1 : 0 ) .. $#_;
if ( !$is_self && @deposit && !defined $deposit[0] ) {
shift @deposit;
}
@_ = ();
my $result = coro_yield( \@deposit );
return unless defined $result;
return ( ref $result eq 'ARRAY' ) ? ( wantarray ? @$result : $result->[-1] ) : $result;
}
# Park the current fiber in a blocking wait, recording why and where (for diagnostics and cancellation).
# $level is the caller stack depth (relative to _park) of the *user* frame whose location should be attributed:
# 1 for direct wait sites, 2 for a Semaphore down(), 3 for a Channel get()/put().
#
# The wait-reason record is [reason, file, line] plus a fourth element, a bounded backtrace of the
# user-side callchain (caller frames from just below the recorded site back to the fiber body). Capturing it
# is a short caller() loop (~100ns per frame), so it runs unconditionally; backtrace_depth(0) disables it.
# On the *re-entry* after the yield returns, a pending interrupt (set by _interrupt) is consumed and thrown, so a
# cancelled wait unwinds with Acme::Parataxis::Error::Cancelled (or ::Timeout) right here the caller of the wait
# sees the parked wait's own reason in the error's wait_reason.
#
# $dereg, when given, is a coderef that removes the *parking* fiber from whatever waiter list it is parked on
# (Semaphore/Signal/Future/child-await). It runs only when this park is interrupted, before the error is thrown, so
# a cancelled fiber never leaves a stale id behind that a later wake could fire at a reused fiber.
sub backtrace_depth {
my $invocant = shift;
if ( !defined $invocant ||
( ( ref $invocant || $invocant ) ne __PACKAGE__ && !( builtin::blessed($invocant) && $invocant->isa(__PACKAGE__) ) ) ) {
unshift @_, $invocant if defined $invocant;
$invocant = __PACKAGE__;
}
return $BACKTRACE_DEPTH unless @_;
my ($depth) = @_;
croak 'backtrace_depth must be a non-negative integer' if !defined $depth || $depth !~ /^\d+$/;
$BACKTRACE_DEPTH = $depth;
return $BACKTRACE_DEPTH;
}
sub _park ( $reason, $level = 1, $dereg = undef, $nodl = 0 ) {
my $fid = Acme::Parataxis->current_fid;
croak '_park() must be called from inside a scheduled fiber' if $fid < 0;
my $fiber = Acme::Parataxis->by_id($fid);
return unless $fiber; # already finished; nothing to park
# Fail fast: a fiber that was interrupted while it was running (not parked), then reached a wait point, throws
# at the park entry instead of parking, so a cancellation never gets stranded until some unrelated wake. The
# C job table may still have armed the sleep/read this wait was about to submit, so the run can stay alive
# until those fire - but no wait is entered after its cancellation.
if ( defined( my $pre = $fiber->[F_INTERRUPT] ) ) {
my ( $pfile, $pline ) = ( caller($level) )[ 1, 2 ];
my $pre_site = [ $pre, $pfile, $pline ];
warn sprintf "PARATAXIS_TRACE t=%.0fms fid=%d ENTRY failfast pre=%s site=%s\n", ( time - $^T ) * 1000, $fid, $pre, "$pfile:$pline"
if $ENV{PARATAXIS_TRACE};
$fiber->[F_INTERRUPT] = undef;
delete $PARKED{$fid};
if ( my $dereg = delete $PARK_REGS{$fid} ) { $dereg->() }
warn "PARATAXIS_TRACE park RE-ENTRY fail-fast fid=$fid reason=$reason pre=$pre\n" if $ENV{PARATAXIS_TRACE};
my $err = $pre eq 'timeout' ? Acme::Parataxis::Error::Timeout->new( wait_reason => $pre_site ) :
Acme::Parataxis::Error::Cancelled->new( wait_reason => $pre_site );
die $err;
}
# A cancellation scope whose token already fired makes every further wait fail fast too: once the fiber's
# pending marker has been consumed (a park threw Error::Cancelled and the user caught it), a re-park inside
# the still-active scope must not wait in vain. Same shape as the entry fail-fast above, but keyed off the
# innermost scope token's own cancelled flag instead of the fiber's interrupt slot.
if ( my $scopes = $fiber->[F_CANCEL_SCOPES] ) {
my $scope = $scopes->[-1];
if ( $scope && $scope->cancelled ) {
my ( $pfile, $pline ) = ( caller($level) )[ 1, 2 ];
delete $PARKED{$fid};
if ( my $old = delete $PARK_REGS{$fid} ) { $old->() }
$dereg->() if $dereg; # this park's waiter entry (pushed before _park) is stale: remove it too
die Acme::Parataxis::Error::Cancelled->new( wait_reason => [ 'cancel', $pfile, $pline ] );
}
}
# Enclosing with_timeout deadlines bound this park. Every with_timeout whose execution this fiber is
# inside pushed an absolute deadline (in ms) onto F_DEADLINE_SCOPES; the innermost/soonest one wins as the
# effective bound and the outermost is the backstop. Three consequences, in order:
# (a) an already-passed effective bound makes a fresh wait fail fast with Error::Timeout instead of parking
# forever - without this, a caught Timeout followed by a re-park under the same fired deadline deadlocked
# (nothing was left to interrupt the wait); the check is the bound's own cancellable token being set, not
# just the arithmetic (left <= 0), because the deadline helper's timer may fire marginally before the wall
# clock reaches abs - a re-park landing in that window would otherwise be missed by the arithmetic and
# (since the bound is armed already) would park with nothing left to interrupt it;
# (b) exactly one deadline helper is armed per fiber for its effective bound and reused across re-parks
# (F_DEADLINE_ARMED), so a re-park never stacks a second timer for the same bound; the helper cancels the
# bound's token, which interrupts the registered fiber via the usual _interrupt path and recalls its jobs;
# (c) a helper is only armed for a bound the fiber itself owns (own => 1). An *inherited* bound (an enclosing
# ancestor's with_timeout, whose token this fiber is not registered on) is always enforced by that
# ancestor's own await-park, so arming it here would be redundant - though its absolute deadline still
# participates in (a), so an inherited scope whose time has already come fails fast too.
# $nodl (now the reap re-park and other transient non-user waits) opts out: a wait whose only job is to reap a
# dying child must not fail fast nor arm, since it must linger until the child's death is observed.
if ( !$nodl && $fiber->[F_DEADLINE_SCOPES] ) {
my $eff;
for my $sc ( @{ $fiber->[F_DEADLINE_SCOPES] } ) {
next unless defined $sc->{abs};
$eff = $sc if !defined $eff || $sc->{abs} < $eff->{abs};
}
if ( defined $eff ) {
my $now = _now_ms();
my $left = $eff->{abs} - $now;
if ( $left <= 0 || $eff->{tok}->cancelled ) {
my ( $pfile, $pline ) = ( caller($level) )[ 1, 2 ];
delete $PARKED{$fid};
if ( my $old = delete $PARK_REGS{$fid} ) { $old->() }
$dereg->() if $dereg; # as above: this park's own waiter entry is stale too
warn "PARATAXIS_TRACE park DEADLINE fail-fast fid=$fid reason=$reason abs=" . $eff->{abs} . " now=$now\n"
if $ENV{PARATAXIS_TRACE};
die Acme::Parataxis::Error::Timeout->new( wait_reason => [ 'timeout', $pfile, $pline ] );
}
if ( $eff->{own} ) {
my $already = $fiber->[F_DEADLINE_ARMED];
if ( defined $already && $already == $eff->{abs} ) {
warn sprintf "PARATAXIS_TRACE t=%.0fms fid=%d park DEADLINE reuse abs=%.0f (already armed)\n", ( time - $^T ) * 1000, $fid,
$eff->{abs}
if $ENV{PARATAXIS_TRACE};
}
else {
my $tok = $eff->{tok};
warn sprintf "PARATAXIS_TRACE t=%.0fms fid=%d park DEADLINE arm abs=%.0f left=%.0f was=%s\n", ( time - $^T ) * 1000, $fid,
$eff->{abs}, $left, defined $already ? $already : 'undef'
if $ENV{PARATAXIS_TRACE};
fiber {
$tok->register;
try { await_sleep($left); $tok->cancel } catch ($e) {
}
};
$fiber->[F_DEADLINE_ARMED] = $eff->{abs};
}
}
}
}
my ( $file, $line ) = ( caller($level) )[ 1, 2 ];
my $bt = [];
if ($BACKTRACE_DEPTH) {
for ( my $i = 1; $i <= $BACKTRACE_DEPTH; $i++ ) {
my @c = caller( $level + $i );
last unless defined $c[0];
next if index( $c[0], 'Acme::Parataxis' ) == 0; # user-side frames only
push @$bt, [ $c[0], $c[1], $c[2], $c[3] ];
}
}
my $site = [ $reason, $file, $line, $bt ];
$fiber->[F_WAIT_REASON] = $site;
$PARKED{$fid} = 1;
$PARK_REGS{$fid} = $dereg if defined $dereg;
my $res = yield('WAITING');
if ( defined( my $kind = $fiber->[F_INTERRUPT] ) ) {
my $wsite = $fiber->[F_WAIT_REASON] // [ 'undef', 'undef', 'undef' ];
warn sprintf "PARATAXIS_TRACE t=%.0fms fid=%d re-entry interrupt consumed kind=%s wait_reason=%s wait_site=%s park_site=%s\n",
( time - $^T ) * 1000, $fid, $kind, $wsite->[0] // 'undef', $wsite->[1] . ':' . $wsite->[2],
( defined $site ? $site->[1] . ':' . $site->[2] : 'n/a' )
if $ENV{PARATAXIS_TRACE};
$fiber->[F_INTERRUPT] = undef;
delete $PARKED{$fid};
if ( my $dereg = delete $PARK_REGS{$fid} ) { $dereg->() }
my $err = $kind eq 'timeout' ? Acme::Parataxis::Error::Timeout->new( wait_reason => $site ) :
Acme::Parataxis::Error::Cancelled->new( wait_reason => $site );
die $err;
}
return $res;
}
# Marks a fiber as interrupted and, if it is currently parked, wakes it so the interrupt is observed at the park's
# re-entry. A fiber that is not parked keeps the marker and the first park it (re)enters afterwards throws. $kind is
# 'cancel' or 'timeout' and selects which error the fiber throws.
sub _interrupt ( $fid, $kind ) {
my $fiber = Acme::Parataxis->by_id($fid);
return unless $fiber;
return if $fiber->[F_IS_DONE];
$fiber->[F_INTERRUPT] = $kind if $kind eq 'cancel' || $kind eq 'timeout';
recall_sleep_jobs_for_fiber($fid);
_recall_virtual_timer($fid); # a virtual timer has no C job; drop it so a recalled fiber is never re-woken
_scheduler_enqueue_by_id($fid) if $PARKED{$fid};
return $fiber;
}
# On a natural wake the park's deregistrations are dropped (the park is over); on an interrupt wake they are kept
# for the throw in _park, which runs them before the fiber unwinds.
sub _resume_hooks ($fiber) {
return unless delete $PARKED{ $fiber->[F_FID] };
$fiber->[F_WAIT_REASON] = undef;
delete $PARK_REGS{ $fiber->[F_FID] } unless defined $fiber->[F_INTERRUPT];
my $hooks = $fiber->[F_WAKE_HOOKS];
$fiber->[F_WAKE_HOOKS] = undef;
if ($hooks) { $_->($fiber) for @$hooks }
}
# -- deterministic mock time. Inside run( virtual => 1, ... ) every timer-based wait (await_sleep,
# -- with_timeout deadlines, Channel bounds, select, Ticker/RateLimiter) and every wall-clock read consulted
# -- through the helpers below rides the virtual clock a test drives with advance(); outside such a run they all
# -- fall back to the real wall clock, so real runs are untouched. A virtual run never submits a TASK_SLEEP job:
# -- the armed virtual timer parks the fiber in-process and the scheduler idle path fast-forwards the clock to the
# -- earliest outstanding deadline instead of sleeping, so an hour-long timeout costs microseconds.
sub virtual_now {
my $o = _arg_offset( $_[0] );
@_ = ();
return $VIRTUAL_CLOCK; # undef when not inside a virtual run, else current virtual ms
}
sub mock_time {
my $o = _arg_offset( $_[0] );
@_ = ();
return defined $VIRTUAL_CLOCK ? $VIRTUAL_CLOCK / 1000 : Time::HiRes::time();
}
sub _now_ms { return defined $VIRTUAL_CLOCK ? $VIRTUAL_CLOCK : Time::HiRes::time() * 1000 }
# Arm a virtual-timer deadline for $fid, $ms from the current virtual clock. A fiber only ever parks in one
# timer-backed wait at a time (a wait never returns until its wake), so one deadline per fiber suffices.
sub _arm_virtual_timer ( $fid, $ms ) {
return if $fid < 0;
my $dl = $VIRTUAL_CLOCK + $ms;
$VIRTUAL_DEADLINES{$fid} = $dl;
push @VIRTUAL_TIMERS, [ $dl, $fid ];
@VIRTUAL_TIMERS = sort { $a->[0] <=> $b->[0] || $a->[1] <=> $b->[1] } @VIRTUAL_TIMERS;
return $dl;
}
# Drop a fiber's armed virtual timer (interrupt, completion, or fiber teardown). Lazy: the sorted array entry
# stays until the next fire, where the deadline-hash mismatch skips it.
sub _recall_virtual_timer ($fid) { delete $VIRTUAL_DEADLINES{$fid} }
# Wake every fiber whose virtual deadline is at or before $now. Returns how many were actually woken (recalled
# timers are popped and skipped, never woken).
sub _fire_virtual ($now) {
my $fired = 0;
while ( @VIRTUAL_TIMERS && $VIRTUAL_TIMERS[0][0] <= $now ) {
my ( $dl, $fid ) = @{ shift @VIRTUAL_TIMERS };
next unless exists $VIRTUAL_DEADLINES{$fid} && $VIRTUAL_DEADLINES{$fid} == $dl;
delete $VIRTUAL_DEADLINES{$fid};
Acme::Parataxis::_scheduler_enqueue_by_id($fid);
$fired++;
}
return $fired;
}
# The per-fiber stash behind Acme::Parataxis::Local, created lazily. Keyed by the fiber OBJECT (not its fid):
# a spawned fiber that finishes inline has its fid recycled in C with no Perl-side completion hook, so a fid key
# would survive into the recycled id and leak state into the next fiber. The object is the fiber's identity for
# as long as it lives; entries are pruned where the object's fid is released (_mark_done, is_done) and on DESTROY.
sub _fiber_locals ($fiber) { return $FIBER_LOCALS{ refaddr($fiber) } //= {} }
sub on_wake {
my $invocant = shift;
if ( !defined $invocant ||
( ( ref $invocant || $invocant ) ne __PACKAGE__ && !( builtin::blessed($invocant) && $invocant->isa(__PACKAGE__) ) ) ) {
unshift @_, $invocant if defined $invocant;
$invocant = __PACKAGE__;
}
my $code = shift;
croak 'on_wake() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
croak 'on_wake() requires a CODE ref' unless ref $code eq 'CODE';
my $fiber = Acme::Parataxis->by_id( Acme::Parataxis->current_fid );
push @{ $fiber->[F_WAKE_HOOKS] }, $code;
return $code;
}
# Runs $code as a child fiber with a deadline of $ms milliseconds and returns its value, or throws
# Acme::Parataxis::Error::Timeout when the deadline fires first. An optional Acme::Parataxis::CancellationToken
# before $code cancels the block like an external deadline. A 0 or undef $ms means no deadline.
#
# The block runs as a child fiber in the same scheduler, so cooperative waits inside it (await_sleep, ->await,
# ->wait, semaphore/signal/channel ops) suspend only the block's fiber. When a token fires, the child's parked wait
# is interrupted at its park re-entry and the child unwinds (unregistering from the tokens as it goes);
# with_timeout rethrows the resulting error (::Timeout or ::Cancelled) in this fiber, so it can be caught with
# eval/try.
#
# The deadline is enforced per-park by _park from a per-fiber scope stack (F_DEADLINE_SCOPES). This
# child pushes its bound onto that stack (inheriting the enclosing with_timeouts of the spawning fiber, so a
# nested block's parks are bounded by the whole chain, innermost/soonest first and the outermost as the backstop)
# and _park derives the effective bound, fails fast when it has already passed (a caught Timeout followed by a
# re-park under the same fired deadline throws again instead of deadlocking), and arms exactly one deadline helper
# per fiber for its bound - reused across re-parks, so no second timer is ever stacked for the same bound. When
# the block finishes (or is itself interrupted) teardown's token cancel recalls the helper's armed sleep and the
# worker is freed instead of staying occupied for the whole bound; no helper is armed at all when the block never
# parks or when $ms is 0.
sub with_timeout {
my $o = _arg_offset( $_[0] );
$o++ if $o == 0 && !defined $_[0];
my $ms = $_[$o];
croak 'with_timeout() requires a duration in milliseconds' unless defined $ms && $ms >= 0;
my $tok;
my $code;
if ( ref $_[ $o + 1 ] eq 'Acme::Parataxis::CancellationToken' ) {
$tok = $_[ $o + 1 ];
$code = $_[ $o + 2 ];
}
else {
$code = $_[ $o + 1 ];
}
croak 'with_timeout() requires a CODE ref' unless ref $code eq 'CODE';
croak 'with_timeout() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
@_ = ();
if ( $tok && $tok->cancelled ) { # the user already cancelled: fail without running the block
die Acme::Parataxis::Error::Cancelled->new;
}
state $have_token = do { require Acme::Parataxis::CancellationToken; 1; };
my $deadline = Acme::Parataxis::CancellationToken->new( kind => 'timeout' );
$tok = $deadline unless $tok; # no explicit token: the deadline alone governs the block
# The absolute (ms-clock) bound this block's parks must respect, and a shallow copy of the spawning fiber's
# enclosing scopes to seed the child's stack with (marked as inherited so the child never arms a helper for a
# token it is not registered on - the owning ancestor enforces those).
my $scope_abs = $ms > 0 ? _now_ms() + $ms : undef;
my $inherited = do {
my $pfid = Acme::Parataxis->current_fid;
my $pf = $pfid >= 0 ? Acme::Parataxis->by_id($pfid) : undef;
my $stk = $pf && $pf->[F_DEADLINE_SCOPES] ? $pf->[F_DEADLINE_SCOPES] : undef;
$stk ?
[
map {
{ %$_, own => 0 }
} @$stk
] :
[];
};
my $child = fiber {
my $cf = Acme::Parataxis->by_id( Acme::Parataxis->current_fid );
$cf->[F_DEADLINE_SCOPES] = defined $scope_abs ? [ @$inherited, { abs => $scope_abs, tok => $deadline, own => 1 } ] : $inherited;
$deadline->register;
$tok->register if $tok ne $deadline;
my $val;
my $err;
try { $val = $code->() } catch ($e) {
$err = $e
}
$deadline->unregister;
$tok->unregister if $tok ne $deadline;
pop @{ $cf->[F_DEADLINE_SCOPES] } if defined $scope_abs; # leave the stack for any enclosing scope
die $err if $err; # the ::Timeout/::Cancelled throw (or any real error) unwinds out of the child
return $val;
};
# The block finished synchronously: the value (or an inline error, already rethrown by spawn) is final. Skipping
# the deadline also means a quick inlined block never pins its run.
if ( $child->is_done ) {
die $child->error if defined $child->error;
return $child->result;
}
my $rv;
my $ok = 1;
my $err;
try { $rv = $child->await } catch ($e) {
$ok = 0;
$err = $e
}
warn "with_timeout teardown: ok=$ok child_done=" .
$child->is_done .
" child_error=" .
( defined $child->error ? ref( $child->error || '' ) || 'plain:' . $child->error : 'undef' ) .
" deadline_cancelled=" .
$deadline->cancelled .
" deadline_waiters=" .
$deadline->waiters .
" tok_waiters=" .
( $tok->waiters // 'undef' ) . " err=" .
( ref( $err || '' ) || 'plain:' . $err ) . "\n"
if $ENV{PARATAXIS_TRACE};
# The child is final, so nothing else may keep waiting under these tokens. Even if *this* fiber was just
# cancelled out from under the await (an enclosing nursery/with_timeout interrupted us, or a user token fired):
# cancel the deadline now so a still-registered grandchild (a nested block, or the deadline helper _park armed
# for our bound) is itself interrupted instead of outliving its parent and running to completion. The recall
# now wakes the helper immediately, so its abandoned sleep job aborts in sub-millisecond time and no live work
# continues past its parent.
# A grandchild woken this way dies observer-gated (its parent's await had registered _wake_waiter on it), so it
# unwinds silently rather than killing the run.
$deadline->cancel;
$tok->cancel if $tok ne $deadline;
warn sprintf "with_timeout re-park branch: fid=%d child_done=%d err=%s\n", Acme::Parataxis->current_fid, $child->is_done,
ref( $err || '' ) || 'plain:' . $err
if $ENV{PARATAXIS_TRACE};
if ( !$ok && !$child->is_done ) {
# We were cancelled out of the await while the child is still parked. It is interrupted and will die on its
# next resume. Re-park here, registered for the child's death, so the scheduler lets the child run its own
# unwind (unregistering from its tokens and running destructors) and reaps it before this frame unwinds and
# frees $child. Freeing the child mid-park no longer crashes (a C-level coroutine-lifecycle fix), so this
# branch is no longer load-bearing for safety - it is kept so an abandoned child dies by unwinding rather
# than being yanked. The interrupt marker on this fiber was consumed by the throwing await, so returning
# from this park (rather than throwing again) is certain. $nodl is set: this is a transient reap wait, not
# a user wait, so it must neither fail fast on an already-passed deadline nor arm a deadline helper.
my $fid = Acme::Parataxis->current_fid;
$child->on_ready( sub { Acme::Parataxis::_scheduler_enqueue_by_id($fid) } );
Acme::Parataxis::_park( 'fiber await', 1, undef, 1 );
$child->is_done; # reap the coroutine now that its death has been observed
}
die $err unless $ok;
return $rv;
}
# Runs $code as a cancellation *scope* on the current fiber: while the block is active, every wait it enters is
# interruptible by one token - the scope token returned here - without the caller having to thread that token
# into each primitive. Unlike with_timeout, no child fiber is spawned; the block runs on this fiber, so interior
# awaits and parks suspend only the normal way. The token registers this fiber for the block's whole duration
# (a register/unregister pair, not a per-park one), so an outer cancel() both interrupts a wait parked now and
# stamps the fiber so the *next* wait entered inside the scope fails fast. Scopes stack LIFO in a per-fiber slot
# (_park reads the innermost one); nesting with_timeout or nursery tokens shares the park, and whichever token
# fires first ends the wait while teardown drops the others' registrations.
#
# Return convention (context aware): the scope token alone in scalar/void context, the token prepended to the
# block's value(s) in list context (my ($tok, @vals) = with_cancel sub { ... }). On failure the block's own
# error propagates unchanged (the real error wins over a concurrently arriving cancel); if the scope itself was
# cancelled by an outer token while the block ran to completion, Error::Cancelled (or Timeout for a deadline)
# is thrown at the scope boundary instead of swallowing the interrupt.
sub with_cancel {
my $o = _arg_offset( $_[0] );
my $code = $_[$o];
@_ = ();
croak 'with_cancel() requires a CODE ref' unless ref $code eq 'CODE';
croak 'with_cancel() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
state $have_token = do { require Acme::Parataxis::CancellationToken; 1 };
my $tok = Acme::Parataxis::CancellationToken->new( kind => 'cancel' );
my $fiber = Acme::Parataxis->by_id( Acme::Parataxis->current_fid );
push @{ $fiber->[F_CANCEL_SCOPES] }, $tok;
$tok->register; # block-wide: this fiber stays registered while the scope is open
my @val;
my $err;
if (wantarray) {
try { @val = $code->($tok) } catch ($e) {
$err = $e
}
}
else {
try { $val[0] = $code->($tok) } catch ($e) {
$err = $e
}
}
$tok->unregister;
pop @{ $fiber->[F_CANCEL_SCOPES] };
if ($err) {
# The block's own error wins: drop any interrupt still pending so it cannot resurface at an outer scope
# after this one has already reported the real failure.
$fiber->[F_INTERRUPT] = undef;
die $err;
}
if ( my $kind = $fiber->[F_INTERRUPT] ) {
# The block returned normally but an outer token/deadline fired while it ran: consume the marker and
# convert it to the matching error so the cancellation is never silently swallowed at this boundary.
$fiber->[F_INTERRUPT] = undef;
die $kind eq 'timeout' ? Acme::Parataxis::Error::Timeout->new : Acme::Parataxis::Error::Cancelled->new;
}
return wantarray ? ( $tok, @val ) : $tok;
}
# STM (software transactional memory). atomically() runs $code as one transaction on the calling fiber: reads are
# journaled, writes stay in a write set until the outermost atomically commits (validating
# every read first, re-running on conflict), and retry() parks the fiber until a TVar it
# read changes. The block may run many times - no irreversible side effects inside it.
# See Acme::Parataxis::TVar for the semantics and the SIDE EFFECTS warning.
sub atomically : prototype(&) {
my $o = _arg_offset( $_[0] );
my $code = $_[$o];
croak 'atomically() requires a CODE ref' unless ref $code eq 'CODE';
croak 'atomically() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
@_ = ();
require Acme::Parataxis::TVar;
return Acme::Parataxis::TVar::_atomically($code);
}
# STM. Aborts the enclosing atomically block and re-runs it once a TVar the
# transaction has read changes; croaks anywhere else.
sub retry {
my $o = _arg_offset( $_[0] );
croak 'retry() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
@_ = ();
require Acme::Parataxis::TVar;
Acme::Parataxis::TVar::_retry();
}
# Structured concurrency. $code runs in the calling fiber with an Acme::Parataxis::Nursery
# as its argument; every child spawned through $n->spawn is guaranteed to finish before nursery()
# returns, and the first child that dies cancels all of its siblings. Children never run inline
# into the block (Nursery::spawn parks each at birth), so a child failure always surfaces through
# the scheduler and is aggregated as Acme::Parataxis::Error::Nursery rather than thrown here.
# If $code itself dies, its children are cancelled and drained before its error is rethrown.
sub nursery {
my $o = _arg_offset( $_[0] );
$o++ if $o == 0 && !defined $_[0];
my $code = $_[$o];
croak 'nursery() requires a CODE ref' unless ref $code eq 'CODE';
croak 'nursery() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
@_ = ();
state $have_nursery = do { require Acme::Parataxis::Nursery; 1 };
my $nursery = Acme::Parataxis::Nursery->new;
my $rv;
my $ok = 1;
my $err;
try { $rv = $code->($nursery) } catch ($e) {
$ok = 0;
$err = $e
}
# The block died: its children must not be orphaned, so cancel them and drain below.
$nursery->token->cancel unless $ok;
# All-children-join. A child failure has already cancelled the rest via the observer,
# so the drain is fast; it unwinds every sibling before control returns to the parent.
my @failures = $nursery->_join;
die $err if !$ok; # the block's own error wins over its children's
if (@failures) {
lib/Acme/Parataxis.pm view on Meta::CPAN
}
# Detach the event-loop driver, returning it and unwinding every watch/timer it still held (loops attached to a
# shared scheduler are racy at best, so a driver session is always short: attach, run, detach).
sub detach_loop {
my $o = _arg_offset( $_[0] );
@_ = ();
croak 'detach_loop() cannot run while a run is already active' if $IS_RUNNING;
my $old = $DRIVER;
$old->reset if $old;
$DRIVER = undef;
return $old;
}
# The currently attached driver (undef when the pool path is in effect). Mostly for diagnostics.
sub loop {
my $o = _arg_offset( $_[0] );
@_ = ();
return $DRIVER;
}
# -- transparent unblocking (CORE::GLOBAL overrides). Opt-in only: never
# -- installed by default. enable_transparent_unblocking() makes sleep/read/sysread
# -- cooperative inside scheduled fibers (sleep -> await_sleep, read/sysread framed
# -- on await_read) and delegates to the raw builtin outside one, so synchronous
# -- CPAN modules become cooperative once they are compiled after installation.
# -- Full coverage table and caveats live in Acme::Parataxis::Compat.
sub enable_transparent_unblocking {
my $o = _arg_offset( $_[0] );
@_ = ();
require Acme::Parataxis::Compat;
Acme::Parataxis::Compat->install;
return 1;
}
sub disable_transparent_unblocking {
my $o = _arg_offset( $_[0] );
@_ = ();
require Acme::Parataxis::Compat;
Acme::Parataxis::Compat->disable;
return 1;
}
sub transparent_unblocking {
my $o = _arg_offset( $_[0] );
@_ = ();
return 0 unless $INC{'Acme/Parataxis/Compat.pm'};
return Acme::Parataxis::Compat->installed ? 1 : 0;
}
sub _driver_sleep ( $driver, $ms ) {
my $fid = Acme::Parataxis->current_fid;
croak 'await_sleep() must be called from inside a scheduled fiber' if $fid < 0;
my $fired = 0;
my $id = $driver->timer( $ms, sub { $fired = 1; Acme::Parataxis::_scheduler_enqueue_by_id($fid) } );
my $dereg = sub { $driver->cancel_timer($id) unless $fired };
return _park( 'await_sleep', 1, $dereg );
}
# Register a read/write watch on the attached loop, arm the wait's own deadline timer, and park. Natural wake
# returns 1; the wait's own deadline swallows its ::Timeout and returns -1 like the pool path does; an *enclosing*
# with_timeout / nursery interrupt did not cancel our deadline token, so it propagates by dying.
#
my $WARNED_FD_SETSIZE = 0;
sub _driver_wait ( $driver, $fh, $dir, $timeout, $reason ) {
my $fid = Acme::Parataxis->current_fid;
croak "$reason() must be called from inside a scheduled fiber" if $fid < 0;
# A loop whose readiness comes from select() cannot name a descriptor at or past the platform's
# FD_SETSIZE - 256 on NetBSD, 64 for winsock, 1024 on Linux - and the fd_set in that case belongs to
# the loop library rather than to us, so there is nothing here to widen. Registering the watch anyway
# would either never fire or corrupt the loop's own stack, so refuse it. The worker-pool path answers
# the same way for the same reason (see worker_thread in Parataxis.c), and -1 is what a deadline
# produces too, so a caller already knows how to read it. Worth saying out loud once, because the
# limit is the platform's and a workload sized on another OS can sail past it unnoticed.
#
# fileno croaks on something that is not a handle at all, and whatever the driver says about that is a
# better message than anything invented here, so an answer of undef means "no descriptor to check" and
# the handle goes on to the driver as it always did. An in-memory file answers -1, which is under any
# ceiling, and needs no watch anyway.
my $fd;
try { $fd = fileno $fh } catch ($e) {
} # not a handle at all: no descriptor to check
if ( defined $fd && $fd >= Acme::Parataxis::fd_setsize() ) {
warn "Acme::Parataxis: $reason() refused: descriptor $fd is at or past this platform's FD_SETSIZE (" .
Acme::Parataxis::fd_setsize() .
"), which a select()-based readiness stack cannot name. Further refusals will not be reported.\n"
unless $WARNED_FD_SETSIZE++;
return -1;
}
my $wake = sub { Acme::Parataxis::_scheduler_enqueue_by_id($fid) };
if ( $dir eq 'read' ) { $driver->watch_read( $fh, $wake ) }
else { $driver->watch_write( $fh, $wake ) }
my $deadline;
my $timer_id;
$timeout //= 5000; # match the worker-pool default, which also maps 0/negative to 5000
$timeout = 5000 if $timeout <= 0;
if ( $timeout > 0 ) {
my $have_ct = do { require Acme::Parataxis::CancellationToken; 1 };
$deadline = Acme::Parataxis::CancellationToken->new( kind => 'timeout' ) if $have_ct;
$deadline->register;
$timer_id = $driver->timer( $timeout, sub { $deadline->cancel } );
}
my $out = 1;
my $dying;
my $dereg = sub {
$driver->unwatch($fh);
$driver->cancel_timer($timer_id) if defined $timer_id;
$deadline->unregister if defined $deadline;
};
my $ok = 1;
my $err;
try { Acme::Parataxis::_park( $reason, 1, $dereg ) }
catch ($e) { $ok = 0; $err = $e }
finally { $dereg->() } # idempotent: on an interrupt _park already ran it, on a natural wake this is the cleanup
if ( !$ok ) {
if ( defined $deadline && $deadline->cancelled && ref($err) && $err->isa('Acme::Parataxis::Error::Timeout') ) {
$out = -1; # this wait's own deadline expired; the pool path resumes (not throws) on timeout
}
else { $dying = $err }
}
$deadline->unregister if defined $deadline;
$deadline->cancel if defined $deadline;
die $dying if defined $dying;
return $out;
}
# Acme::Parataxis->advance($ms): inside a virtual run, jump the virtual clock forward $ms and wake everything that
# fires as of the new time. A nudge, not a wait: the calling fiber keeps running (woken fibers run on the next
# scheduler pass), so the "advance, then yield/return, then observe" test choreography in the docs is the idiom.
# Returns the new virtual time in ms. Croaks outside a virtual run - the wall clock cannot be wound forward.
sub advance {
my $o = _arg_offset( $_[0] );
my $ms = $_[$o] // 0;
@_ = ();
croak 'advance() only makes sense inside run( virtual => 1, ... )' unless defined $VIRTUAL_CLOCK;
croak 'advance() requires a non-negative number of milliseconds' if $ms < 0;
$VIRTUAL_CLOCK += $ms;
_fire_virtual($VIRTUAL_CLOCK);
return $VIRTUAL_CLOCK;
}
sub await_sleep {
my $o = _arg_offset( $_[0] );
$o++ if $o == 0 && !defined $_[0];
my $ms = $_[$o] // 0;
@_ = ();
if ( defined $VIRTUAL_CLOCK && $ms > 0 ) {
my $fid = Acme::Parataxis->current_fid;
croak 'await_sleep() must be called from inside a scheduled fiber' if $fid < 0;
_arm_virtual_timer( $fid, $ms );
return _park('await_sleep');
}
if ( $DRIVER && $ms > 0 ) {
return _driver_sleep( $DRIVER, $ms );
}
_submit_job( 0, $ms, 0 );
return _park('await_sleep');
}
sub await_core_id {
@_ = ();
_submit_job( 1, 0, 0 );
return _park('await_core_id');
}
sub await_read {
my $o = _arg_offset( $_[0] );
$o++ if $o == 0 && !defined $_[0];
my $fh = $_[$o];
my $timeout = $_[ $o + 1 ] // 5000;
@_ = ();
my $fileno = fileno($fh);
die 'Not a valid filehandle' unless defined $fileno;
if ($DRIVER) {
return _driver_wait( $DRIVER, $fh, 'read', $timeout, 'await_read' );
}
( run in 1.217 second using v1.01-cache-2.11-cpan-234fa220139 )