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 )