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 )