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 - A placeholder for an eventual computation result

=head1 SYNOPSIS

    use Acme::Parataxis::Future;

    my $future = Acme::Parataxis::Future->new;

    # Register a callback
    $future->on_ready(sub ($f) {
        say 'Result: ' . $f->result;
    });

    # Set the result (from another fiber)
    $future->set_result(42);

    # Await in a fiber (suspends until ready)
    my $value = $future->await;

=head1 DESCRIPTION

A common pattern for lightweight concurrency abstractions. A future represents a value that will be available at some
point in the future. Futures are used to coordinate between fibers: one fiber produces a result via C<set_result> or
C<set_error>, and one or more consumers retrieve it via C<result> or C<await>.

A future transitions from not-ready to ready exactly once. Attempting to set the result or error on an already-ready
future throws an exception.

=head1 CONSTRUCTOR

=head2 C<new()>

    my $future = Acme::Parataxis::Future->new();

Creates a new, not-ready Future.

=head1 METHODS

=head2 C<is_ready()>

    my $ready = $future->is_ready;

Returns true if the future has been resolved (via C<set_result> or C<set_error>).

=head2 C<result()>

    my $val = $future->result;

Returns the result value immediately. Croaks if the future is not yet ready. Use C<is_ready> to check first, or
C<await> to suspend until the value is available. Dies with the stored error if the future was resolved via
C<set_error>.

=head2 C<set_result( $value )>

    $future->set_result($val);

Resolve the future with a result value. Fires any registered C<on_ready> callbacks. Dies if the future is already