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 )