Acme-Parataxis
view release on metacpan or search on metacpan
lib/Acme/Parataxis/Future.pod view on Meta::CPAN
=pod
=encoding utf8
=head1 NAME
Acme::Parataxis::Future - Single-Assignment Values for Fiber Coordination
=head1 SYNOPSIS
use v5.40;
use Acme::Parataxis qw[async fiber];
use Acme::Parataxis::Future;
my $future = Acme::Parataxis::Future->new;
async {
# Consumer: parks until the future resolves
fiber {
say 'Waiting for answer...';
my $val = $future->await;
say "Got result: $val";
};
# Producer: sets the result from another fiber
fiber {
$future->set_result(42);
};
};
=head1 DESCRIPTION
An C<Acme::Parataxis::Future> represents a value that will become available at a later time. It acts as a
single-assignment coordination point between fibers: producers fulfill the future with a result or error, and consumers
park on it until it is ready.
Key characteristics:
=over
=item *
B<Zero polling>: Calling C<< $future->await >> suspends the calling fiber in the scheduler. When C<set_result> or
C<set_error> is called, all waiting fibers are re-enqueued onto the run queue in a single pass.
=item *
B<Single resolution>: A future can be fulfilled exactly once. Attempting to call C<set_result> or C<set_error> on an
already-ready future dies immediately.
=item *
B<Cancellable waits>: Fibers parked in C<await()> can be interrupted by L<with_timeout|Acme::Parataxis/with_timeout> or
L<Acme::Parataxis::CancellationToken>. If interrupted, the fiber is safely unregistered from the future's waiter list,
preventing stale wakeups.
=item *
B<Composable>: Futures compose with L<< Acme::Parataxis->wait_all >> and L<< Acme::Parataxis->wait_any >>.
C<Acme::Parataxis> fiber objects themselves implement this same Future interface.
=back
( run in 0.361 second using v1.01-cache-2.11-cpan-234fa220139 )