Acme-Parataxis

 view release on metacpan or  search on metacpan

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

=pod

=encoding utf8

=head1 NAME

Acme::Parataxis::Actor - A Fiber with a Mailbox

=head1 SYNOPSIS

    use v5.40;
    use Acme::Parataxis qw[async];
    use Acme::Parataxis::Actor;

    async {
        my $upper = Acme::Parataxis::Actor->spawn( sub ( $self, $msg ) {
            return uc $msg->{text};
        } );

        # ask: queue a message and get a future for the handler's answer
        say $upper->ask( { text => 'hello' } )->await;    # HELLO

        # send: queue a message, expect no answer
        $upper->send( { text => 'nobody is reading this' } );

        # handle what is queued, then shutdown gracefully
        $upper->stop;
    };

=head1 DESCRIPTION

An actor is a private fiber with an incoming mailbox. C<spawn> starts one, binds it to a handler, and returns
immediately. The handler runs inside the actor's private fiber, processing one message at a time. Because messages are
serialized and isolated to this single fiber, internal state requires no mutexes or locking: keep your variables inside
the closure and interact with them purely via messages.

Two verbs do the talking:

=over

=item * C<ask( $msg )> queues a message and returns an L<Acme::Parataxis::Future> that resolves with the handler's return value.

=item * C<send( $msg )> queues a message and returns immediately without waiting for an answer.

=back

The handler is invoked as C<< sub ( $self, $msg ) { ... } >>. It may perform any standard cooperative action—calling
C<await_sleep>, reading from channels, awaiting other actors, or acquiring locks—and the actor will wait for it to
return before taking the next message.

The mailbox is a bounded L<Acme::Parataxis::Channel>. If producers send messages faster than the handler can process
them, the mailbox fills and subsequent senders park. Because this is a standard fiber wait, round-trips can be bounded
with L<with_timeout|Acme::Parataxis/with_timeout> or cancellation tokens.

Actors can be registered globally by name, hot-swapped while running (C<swap>), and supervised under
L<Acme::Parataxis::Supervisor>.

=head1 METHODS

=head2 C<spawn( $code, [$capacity = 16], [%opts] )>

    my $actor = Acme::Parataxis::Actor->spawn(
        sub ( $self, $msg ) { ... },



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