Acme-Parataxis

 view release on metacpan or  search on metacpan

lib/Acme/Parataxis/Actor.pm  view on Meta::CPAN

use v5.40;
no warnings 'experimental::class', 'recursion';
use feature 'class';

# An actor is a named or anonymous mailbox behind a single private fiber, with a handler that
# runs at most one message at a time. spawn() builds and starts it (a class-level factory, since
# perlclass instances cannot be assembled by hand); the mailbox is created in ADJUST, the fiber
# and its weak self-capture in _start, so spawn() does the checks and plumbing a factory must.
class Acme::Parataxis::Actor v0.1.3 {
    use Acme::Parataxis qw[fiber];
    use Acme::Parataxis::Channel;
    use Acme::Parataxis::Future;
    use Carp qw[croak];
    our $STOP = \do { my $x = 1 };    # envelope value that tells the loop to shut down gracefully
    field $cap  : param;              # mailbox capacity
    field $code : param;              # the handler: ($self, $value) => result, run for each message
    field $done = 0;                  # set once at teardown
    field $error;                     # what killed the actor, or undef for a graceful stop
    field $fiber;                     # the private fiber the message loop runs on
    field $mailbox;                   # the Channel the messages queue through
    field $name : param = undef;      # the registered name, or undef for an unnamed actor
    field $on_death = [];             # death hooks, fired exactly once at teardown
    field $opts : param;              # the original spawn %opts, so respawn() can reproduce them
    field $stopping = 0;              # set by stop(), refuses new send()s/ask()s
    field $supervised : param;        # a supervised handler crash stops this actor and reports it
    ADJUST {
        $mailbox = Acme::Parataxis::Channel->new( capacity => $cap );
    }

    sub spawn : prototype($\&;$\%) ( $class, $code, $capacity = 16, %opts ) {
        croak 'Actor->spawn() must be called from inside a scheduled fiber' if Acme::Parataxis->current_fid < 0;
        croak "Actor->spawn() mailbox capacity must be >= 1 (got $capacity)" unless $capacity >= 1;
        #
        my %unknown = %opts;
        #
        delete @unknown{qw[supervised name]};
        croak 'Actor->spawn(): unknown options: ' . join ', ', sort keys %unknown if %unknown;
        my $name = $opts{name};
        if ( defined $name ) {
            croak 'Actor->spawn(): the name must be a non-empty string' unless !ref $name && length $name;
            my $existing = $Acme::Parataxis::ACTOR_REGISTRY{$name};
            croak "Actor->spawn(): an actor named '$name' is already registered" if $existing && $existing->is_alive;
        }
        my $self = $class->new( code => $code, cap => $capacity, name => $name, supervised => !!$opts{supervised}, opts => \%opts );
        $self->_start;
        return $self;
    }

    # Lives in its own method so the fiber closure only ever reaches the actor through field
    # values captured as lexicals (a perlclass closure cannot touch fields directly). The fiber
    # body captures a weak copy of $self, so a done actor is collectable.
    method _start () {
        my $weak = $self;    # the fiber body captures this weak copy, so a done actor is collectable
        builtin::weaken($weak);
        my $mb  = $mailbox;
        my $srv = $supervised;
        $fiber = fiber {
            my $crash;

            # The loop is guarded so teardown is reached on *every* exit path: an interrupt (a
            # cancellation token or a with_timeout deadline landing on this fiber) thrown from a
            # parked wait inside a handler escapes the loop and must not skip the drain below.
            my $ok = 1;
            my $interrupt;
            try {
                while (1) {
                    my $env = $mb->get;    # Park it here without holding $self
                    my ( $reply, $value ) = @$env;
                    last if defined $value && ref $value && $value == $STOP;
                    #
                    my $actor = $weak;
                    last unless defined $actor;    # Handle was dropped by user
                    my $err = $actor->_dispatch( $reply, $value );
                    if ( defined $err && $srv ) { $crash = $err; last }
                }
            }
            catch ($e) { $ok = 0; $interrupt = $e }
            $crash = $interrupt unless $ok;
            if ( my $actor = $weak ) { $actor->_finish($crash) }
        };
        $Acme::Parataxis::ACTOR_REGISTRY{$name} = $self if defined $name;    # only a spawned actor is registered
        return;
    }

    method _finish ($crash) {
        return if $done;
        $done  = 1;
        $error = $crash if defined $crash;

        # Release any registered name so a dead actor never answers a lookup. The guard (entry still == $self)
        # keeps an older actor's teardown from clobbering a same-named replacement that registered since.
        delete $Acme::Parataxis::ACTOR_REGISTRY{$name} if defined $name && ( $Acme::Parataxis::ACTOR_REGISTRY{$name} // 0 ) == $self;

        # The drain is best effort: a watcher must learn about this death even if an interrupt lands
        # on this fiber mid-teardown, or whoever is waiting for the report waits forever.
        my $msg = defined $crash ? "$crash" : 'actor stopped before this message was handled!';
        try { $self->_fail_queued($msg) } catch ($e) {
            warn "Acme::Parataxis::Actor: drain failed: $e"
        }
        for my $cb ( @{ $on_death // [] } ) {
            try { $cb->( $self, $error ) }
            catch ($e) { warn "Acme::Parataxis::Actor: death hook died: $e" }
        }
        return;
    }

    # Fail every ask still outstanding: whatever sits in the mailbox, plus any sender parked in
    # put() that an earlier take released. Each take frees one mailbox slot, which is what releases
    # a parked sender, so one yield per idle stretch lets a released sender land its envelope before
    # the mailbox is declared empty. Nothing new can arrive meanwhile: done is already set, so
    # _check_alive refuses it, and a sender between that check and the push never yields.
    method _fail_queued ($msg) {
        my $mb   = $mailbox;
        my $idle = 0;
        while ( $idle < 3 ) {
            my ( $ok, $env ) = $mb->try_get;
            if ($ok) {
                $idle = 0;
                my ($reply) = @$env;
                next unless defined $reply;
                next if $reply->is_ready;
                try { $reply->set_error($msg) }
                catch ($e) { warn 'Acme::Parataxis::Actor: failed to fail a queued ask: ' . $e }
                next;
            }
            $idle++;
            Acme::Parataxis->yield if $idle == 1;
        }
        return;
    }

    # Fires exactly once when this actor is gone: $err is what killed it, or undef for a graceful stop. An actor that
    # is already done calls back immediately, so a watcher never has to check.
    method on_death : prototype($&) ($cb) {
        if ($done) { $cb->( $self, $error ); return $self }
        push $on_death->@*, $cb;
        return $self;
    }
    method error () {$error}    # why it died, or undef if it stopped gracefully

    # A fresh, already-running actor with the same handler, mailbox size and options: what a supervisor starts in
    # place of this one. The new actor owns a new mailbox, so asks still outstanding here are failed here rather than
    # answered there.
    method respawn () {
        return ref($self)->spawn( $code, $cap, $opts->%* );
    }

    method _dispatch ( $reply, $value ) {
        my $err;
        my $ok = 1;
        try {
            my $rv = $code->( $self, $value );
            $reply->set_result($rv) if defined $reply;
        }
        catch ($e) {
            $ok  = 0;
            $err = $e;
        }
        if ( !$ok ) {
            if ( defined $reply ) {
                try {
                    $reply->set_error($err);
                }
                catch ($e) {
                }
            }
            elsif ( !$supervised ) {    # a supervised actor reports this death to its supervisor instead
                warn "Acme::Parataxis::Actor: handler died: $err";
            }
        }
        return $err;                    # undef when the handler returned normally; the caller turns it into a crash if supervised
    }

    method send ($value) {
        $self->_check_alive;
        $mailbox->put( [ undef, $value ] );
        return 1;
    }

    method ask ($value) {
        $self->_check_alive;
        my $reply = Acme::Parataxis::Future->new;
        $mailbox->put( [ $reply, $value ] );
        return $reply;
    }

    method stop () {
        return $self if $done || $stopping;
        $stopping = 1;

        # Non-blocking enqueue so DESTROY never yields or parks:
        $mailbox->put_priority( [ undef, $STOP ] );
        return $self;
    }
    method is_alive () { return !$done }
    method fid ()      { return $fiber->fid }
    method name ()     { return $name }         # the registered name, or undef for an unnamed actor

    # Hot code swap: atomically replace the handler for *subsequent* messages.
    method swap : prototype($\&) ($new) {
        croak 'requires a CODE ref' unless builtin::reftype($new) // '' eq 'CODE';



( run in 0.950 second using v1.01-cache-2.11-cpan-234fa220139 )