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 )