Acme-Parataxis

 view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

```

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

## `await( $target )`

```perl
my $val = await($fiber_or_future);
```

Suspends the current fiber until `$target` completes. `$target` may be an `Acme::Parataxis` fiber, an
[Acme::Parataxis::Future](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3AFuture), or an [Acme::Parataxis::Monitor](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3AMonitor). Returns the resolution value or rethrows the target's
death error in the caller.

## `yield( [@args] )`

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

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

## `await_sleep( $ms )`

```
await_sleep(250);    # sleep 250 milliseconds
```

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

## `await_read( $fh, [$timeout_ms = 5000] )`

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

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

## `await_write( $fh, [$timeout_ms = 5000] )`

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

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

## `with_timeout( $ms, [$token,] $code )`

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

Runs `$code` under a strict deadline. If execution does not complete within `$ms` milliseconds, any parked wait
aborts and throws [Acme::Parataxis::Error::Timeout](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3AError%3A%3ATimeout). If an optional [Acme::Parataxis::CancellationToken](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3ACancellationToken) is pro...
cancelling the token interrupts the block early with [Acme::Parataxis::Error::Cancelled](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3AError%3A%3ACancelled).

## `with_cancel( sub ($token) { ... } )`

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

Executes `$code` within a scoped cancellation context. The block receives a fresh `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.

## `nursery( sub ($n) { ... } )`

```perl
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 `$n->spawn`, and guarantees
that all children finish before `nursery()` returns. If any child dies, its siblings are immediately cancelled, the
entire nursery drains, and the primary failure is rethrown as an [Acme::Parataxis::Error::Nursery](https://metacpan.org/pod/Acme%3A%3AParataxis%3A%3AError%3A%3ANursery).

## `wait_all( @futures )`

```perl
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.

## `wait_any( @futures )`

```perl
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.

## `pmap( \%opts, $code, @items )`

```perl
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 `concurrency` (default: one fiber
per item). Preserves input ordering. If any worker throws, in-flight fibers are cancelled and the error is rethrown.

# SCHEDULER & RUNTIME METHODS



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