Acme-Parataxis

 view release on metacpan or  search on metacpan

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

    async {
        # scheduler starts, executes block as the root fiber, and stops when finished
    };

Convenience wrapper around C<run()>. Executes the provided code block as the initial root fiber of a new scheduler
session and stops the scheduler once the block returns or dies.

=head2 C<fiber { ... }>

    my $f = fiber {
        my $val = do_work();
        return $val;
    };

Creates and schedules a new fiber. An alias for C<spawn()>. Returns the C<Acme::Parataxis> fiber object, which
implements the Future interface (C<await>, C<result>, C<error>, C<on_ready>).

=head2 C<await( $target )>

    my $val = await($fiber_or_future);

Suspends the current fiber until C<$target> completes. C<$target> may be an C<Acme::Parataxis> fiber, an
L<Acme::Parataxis::Future>, or an L<Acme::Parataxis::Monitor>. Returns the resolution value or rethrows the target's
death error in the caller.

=head2 C<yield( [@args] )>

    yield();
    my $reply = yield('hello');

Suspends the current fiber and returns control to the scheduler. If C<@args> are passed, they are delivered to the
context that next calls or resumes this fiber.

=head2 C<await_sleep( $ms )>

    await_sleep(250);    # sleep 250 milliseconds

Cooperatively suspends the current fiber for C<$ms> milliseconds. The delay is handed to the native thread pool or
attached driver, allowing other fibers to execute.

=head2 C<await_read( $fh, [$timeout_ms = 5000] )>

    my $ready = await_read( $socket, 2000 );

Suspends the current fiber until C<$fh> is ready to read or the timeout expires. Returns C<1> on readiness, C<-1> on
timeout or unwatchable handle.

=head2 C<await_write( $fh, [$timeout_ms = 5000] )>

    my $ready = await_write( $socket, 2000 );

Suspends the current fiber until C<$fh> is ready to accept writes. Returns C<1> on readiness, C<-1> on timeout.

=head2 C<with_timeout( $ms, [$token,] $code )>

    my $val = with_timeout( 1000, sub {
        return fetch_data();
    } );

Runs C<$code> under a strict deadline. If execution does not complete within C<$ms> milliseconds, any parked wait
aborts and throws L<Acme::Parataxis::Error::Timeout>. If an optional L<Acme::Parataxis::CancellationToken> is provided,
cancelling the token interrupts the block early with L<Acme::Parataxis::Error::Cancelled>.

=head2 C<with_cancel( sub ($token) { ... } )>

    my ($token, @res) = with_cancel( sub ($t) {
        fiber { await_sleep(100); $t->cancel };
        await_sleep(10_000);
    } );

Executes C<$code> within a scoped cancellation context. The block receives a fresh C<CancellationToken>. Any wait
parked inside the scope is interrupted if the token cancels. In list context, returns the token followed by the block's
return values; in scalar or void context, returns the token alone.

=head2 C<nursery( sub ($n) { ... } )>

    nursery( sub ($n) {
        $n->spawn( sub { worker_one() } );
        $n->spawn( sub { worker_two() } );
    } );

Structured concurrency scope. Runs the block, joins every child fiber spawned through C<< $n->spawn >>, and guarantees
that all children finish before C<nursery()> returns. If any child dies, its siblings are immediately cancelled, the
entire nursery drains, and the primary failure is rethrown as an L<Acme::Parataxis::Error::Nursery>.

=head2 C<wait_all( @futures )>

    my $aggregate = wait_all( $f1, $f2 );
    my $results   = await($aggregate);    # [ $res1, $res2 ]

Takes a list of futures/fibers and returns a new Future that resolves with an arrayref of results once every input has
succeeded. If any input fails, the aggregate fails fast with that first error.

=head2 C<wait_any( @futures )>

    my $winner = await( wait_any( $f1, $f2 ) );

Returns a Future that completes as soon as the first input future settles (whether by success or failure), adopting
that winner's outcome.

=head2 C<pmap( \%opts, $code, @items )>

    my @results = pmap( { concurrency => 4 }, sub ($item) {
        return process_item($item);
    }, @items );

Maps a subroutine over a list of items using a pool of concurrent fibers bounded by C<concurrency> (default: one fiber
per item). Preserves input ordering. If any worker throws, in-flight fibers are cancelled and the error is rethrown.

=head1 SCHEDULER & RUNTIME METHODS

=head2 C<< Acme::Parataxis->run( $code, [%opts] ) >>

    my $status = Acme::Parataxis->run(
        code        => sub { ... },
        virtual     => 0,
        on_shutdown => 1
    );

Starts the scheduler event loop. Options include:



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