Amphp Amp

https://github.com/amphp/amp
Admin
Amphp Amp is a non-blocking concurrency framework for PHP that provides futures and cancellations as...
Tokens:53,967
Snippets:459
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install amphp/amp and revolt/event-loop via Composer

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/README.md

Install the amphp/amp package and optionally the revolt/event-loop package to schedule events explicitly. The revolt/event-loop is a required dependency and is installed automatically.

```bash
composer require amphp/amp
composer require revolt/event-loop   # schedule events explicitly if needed
```

--------------------------------

### await() basic usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Basic example of awaiting a future. The output is int(42).

```php
use Amp\Future;

$future = Amp\async(function (): int {
    Amp\delay(1);
    return 6 * 7;
});

$result = $future->await();
var_dump($result); // int(42)
```

--------------------------------

### isComplete() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Example showing how to check if a future is complete. The var_dump will output bool(false) until the fiber runs.

```php
use Amp\Future;

$future = Amp\async(fn (): int => 1);
var_dump($future->isComplete()); // bool(false) until the fiber runs
```

--------------------------------

### Basic async() usage

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Starts a fiber that delays 0.1 seconds and returns the sum of two arguments. The future is awaited to get the result int(5).

```php
use function Amp\async;

$future = async(function (int $a, int $b): int {
    Amp\delay(0.1);
    return $a + $b;
}, 2, 3);

var_dump($future->await()); // int(5)
```

--------------------------------

### awaitAll usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Example of using Amp\Future\awaitAll with two async tasks, one succeeding and one throwing. Demonstrates that errors are collected in the $errors array and values in $values, without aborting early.

```php
use function Amp\Future\awaitAll;

[$errors, $values] = awaitAll([
    "a" => Amp\async(fn (): int => 1),
    "b" => Amp\async(fn (): int => throw new \RuntimeException('b failed')),
]);

var_dump($values); // array<int> ["a" => 1]
var_dump($errors); // array<\Throwable> ["b" => RuntimeException]
```

--------------------------------

### subscribe() return value example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/NullCancellation.md

Example showing the constant return value of subscribe(). The id can be safely passed to unsubscribe() repeatedly.

```php
$id = $cancellation->subscribe($handler);
var_dump($id); // string("null-cancellation")
```

--------------------------------

### finally() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Example showing how to run a cleanup callback when the future completes. The log callback always runs before the await returns.

```php
use Amp\Future;

$fut = Amp\async(fn (): string => 'data');
$tracked = $fut->finally(fn () => log('resource released'));

$value = $tracked->await(); // always runs the log callback first
```

--------------------------------

### close() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Closable.md

Example usage of close() on a stream resource.

```php
$stream->close();
```

--------------------------------

### awaitFirst usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Example usage of awaitFirst to get the result of the first future to complete, whether success or error. The function is imported with use function and called with an array of futures created by Amp\async.

```php
use function Amp\Future\awaitFirst;

$first = awaitFirst([
    Amp\async(fn (): int => slowQuery()),
    Amp\async(fn (): int => cachedResult()),
]);
```

--------------------------------

### now() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Measures elapsed time using `Amp\now()` and `Amp\delay()`.

```php
use function Amp\now;

$start = now();
Amp\delay(0.5);
$elapsed = now() - $start; // ≈ 0.5
```

--------------------------------

### map() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Example showing how to transform the result of a future using map(). The output is int(42).

```php
use Amp\Future;

$result = Amp\async(fn (): int => 21)
    ->map(fn (int $value): int => $value * 2);

var_dump($result->await()); // int(42)
```

--------------------------------

### isClosed() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Closable.md

Example usage of isClosed() to guard against using a closed resource.

```php
if ($stream->isClosed()) {
    return; // already released
}
```

--------------------------------

### Starting a Coroutine with Amp\async()

Source: https://github.com/amphp/amp/blob/3.x/README.md

This snippet shows how to start a coroutine using Amp\async(). Inside the coroutine, a delayed operation (Amp\delay(3)) simulates asynchronous work, while the main script uses Amp\delay(5) to keep the event loop running. The output sequence illustrates that both the coroutine and the main script run concurrently. This is the recommended way to launch independent coroutines without the need for manual suspension.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

Amp\async(function () {
    print '++ Executing callback passed to async()' . PHP_EOL;

    Amp\delay(3);

    print '++ Finished callback passed to async()' . PHP_EOL;
});

print '++ Suspending to event loop...' . PHP_EOL;
Amp\delay(5);

print '++ Script end' . PHP_EOL;

```

--------------------------------

### subscribe() usage example with DeferredCancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Cancellation.md

Example of subscribing to a cancellation using Amp\DeferredCancellation. The callback is invoked on cancellation and can be used to fail a pending future.

```php
$cancellation = new Amp\DeferredCancellation();

$id = $cancellation->getCancellation()->subscribe(fn (Amp\CancelledException $e) {
    // queue the work for cancellation, e.g. fail a pending future
});
```

--------------------------------

### catch() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Example showing how to recover from an error using catch(). The output is string("recovered: boom").

```php
use Amp\Future;

$result = Amp\async(function (): string {
    throw new \RuntimeException('boom');
})->catch(fn (\Throwable $e): string => 'recovered: ' . $e->getMessage());

var_dump($result->await()); // string("recovered: boom")
```

--------------------------------

### Implementing Closable - SimpleResource example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Closable.md

Minimal implementation of Closable. Tracks a boolean flag and a list of callbacks. close() marks the resource closed and invokes all handlers; onClose() invokes the callback immediately if already closed, otherwise stores it.

```php
use Amp\Closable;

final class SimpleResource implements Closable
{
    private bool $closed = false;
    private array $handlers = [];

    public function close(): void
    {
        if ($this->closed) {
            return;
        }

        $this->closed = true;
        foreach ($this->handlers as $handler) {
            $handler();
        }
        $this->handlers = [];
    }

    public function isClosed(): bool
    {
        return $this->closed;
    }

    public function onClose(\Closure $onClose): void
    {
        if ($this->closed) {
            $onClose();
        } else {
            $this->handlers[] = $onClose;
        }
    }
}
```

--------------------------------

### complete() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Creates a completed future with value 42 and awaits it, printing int(42).

```php
use Amp\Future;

$cached = Future::complete(42);
var_dump($cached->await()); // int(42)
```

--------------------------------

### unsubscribe() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Cancellation.md

Example of unsubscribing from a cancellation using the identifier returned by subscribe().

```php
$cancellation->getCancellation()->unsubscribe($id);
```

--------------------------------

### Basic Interval usage with disable and enable

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Basic usage example: creates an interval, disables it, then enables it again. The callback is not invoked until the interval elapses after enabling.

```php
use Amp\Interval;

// Creates a callback which is invoked every 0.5s
// unless disabled or the object is destroyed.
$interval = new Interval(0.5, function (): void {
    // ...
});

// Disable the repeating timer, stopping future
// invocations until enabled again.
$interval->disable();

// Enable the repeating timer. The callback will
// not be invoked until the given timeout has elapsed.
$interval->enable();
```

--------------------------------

### onClose() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Closable.md

Example usage of onClose() to register a callback that releases a pool slot when the stream is closed.

```php
$stream->onClose(fn () => releasePoolSlot($stream));
```

--------------------------------

### Create a DeferredCancellation instance

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredCancellation.md

Example of creating a new DeferredCancellation instance. Keep a reference to the object to prevent premature cancellation via garbage collection.

```php
$deferred = new Amp\DeferredCancellation();
```

--------------------------------

### await() advanced usage with timeout and re-await

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Advanced example showing how to await with a timeout and re-await later. Cancelling the await does not cancel the underlying operation.

```php
use Amp\CancelledException;
use Amp\TimeoutCancellation;

$future = Amp\async(function (): void {
    Amp\delay(1);
    print 'Operation complete.' . PHP_EOL;
});

try {
    // This cancels only the await, not the operation itself
    $future->await(new TimeoutCancellation(0.5));
} catch (CancelledException) {
    print 'Await operation has been cancelled.' . PHP_EOL;
}

// The fiber is still running; we can await again later
$future->await();
```

--------------------------------

### Amp\CancelledException

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/errors.md

Documentation for the Amp\CancelledException class, including its constructor and usage example.

```APIDOC
## CancelledException

### Description
Exception thrown when an operation is cancelled. It is delivered when a cancellation is requested, when awaiting a future with a cancellation that is already requested, or when a cancellation is triggered by timeout, signal, or deferred cancellation.

### Constructor
`__construct(\Throwable $previous = null)`

### Parameters
- **$previous** (\Throwable|null) - Optional - The previous exception in the exception chain.

### Usage Example
```php
use Amp\CancelledException;

try {
    $future->await(new Amp\TimeoutCancellation(5.0));
} catch (CancelledException) {
    print 'Operation was cancelled.' . PHP_EOL;
}
```

### Notes
- The previous throwable can be retrieved via the standard PHP previous-exception accessor.
- The exception message is always "The operation was cancelled".

```

--------------------------------

### await usage example with HTTP requests

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Concurrent HTTP fetch pattern using Amp\Future\await. Sends HEAD requests to multiple URIs and prints responses. If any request fails, the whole combination fails and the exception is caught.

```php
use Amp\Future;
use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\Request;
use function Amp\async;

$httpClient = HttpClientBuilder::buildDefault();
$uris = [
    "google" => "https://www.google.com",
    "news"   => "https://news.google.com",
];

try {
    $responses = Future\await(array_map(function ($uri) use ($httpClient) {
        return async(fn () => $httpClient->request(new Request($uri, 'HEAD')));
    }, $uris));

    foreach ($responses as $key => $response) {
        printf("%s | HTTP/%s %d %s\n", $key,
            $response->getProtocolVersion(), $response->getStatus(), $response->getReason());
    }
} catch (\Exception $e) {
    // If any one of the requests fails the combo will fail
    echo $e->getMessage(), "\n";
}
```

--------------------------------

### async

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Documentation for the async() function, which starts a new fiber to execute a closure and returns a Future.

```APIDOC
## async

### Description
Starts a new fiber (an independent coroutine call stack) to execute the given closure, returning a `Future` completed with the closure's return value, or errored if the closure threw.

### Signature
```php
function async(\Closure $closure, mixed ...$args): Future
```

### Parameters
- `$closure` (\Closure(...): T) - Required - Closure to execute in the new fiber. Must not have side effects on the caller's stack beyond its return value.
- `...$args` (mixed) - Optional - Arguments forwarded to the closure when the fiber starts.

### Return Value
`Future<T>` - completed with the closure result, errored with whatever `\Throwable` the closure propagates. The future is created even while the fiber is still queued on the event loop.

### Throws
None directly. A closure exception surfaces when the returned future is awaited or subscribed. Arguments are nulled out of the internal closure scope before the fiber runs so an exception thrown from the closure cannot keep the arguments (or the `FutureState`) alive via the stack trace.

### Example
```php
use function Amp\async;

$future = async(function (int $a, int $b): int {
    Amp\delay(0.1);
    return $a + $b;
}, 2, 3);

var_dump($future->await()); // int(5)
```

### Example with Error Handling
```php
use Amp\CancelledException;
use function Amp\async;

$future = async(function (): string {
    if (!\file_exists('/tmp/data')) {
        throw new \RuntimeException('missing input');
    }
    return \file_get_contents('/tmp/data');
});

try {
    $data = $future->await(new Amp\TimeoutCancellation(2.0));
} catch (CancelledException) {
    // timeout fired before the fiber finished
} catch (\RuntimeException $e) {
    // closure threw
}
```
```

--------------------------------

### Create DeferredFuture and get Future

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredFuture.md

Basic usage of the constructor: create a DeferredFuture and obtain its Future via getFuture().

```php
$deferred = new Amp\DeferredFuture();
$future = $deferred->getFuture();
```

--------------------------------

### asyncMultiply: Using DeferredFuture to create a Future

Source: https://github.com/amphp/amp/blob/3.x/README.md

Shows how to create a Future using DeferredFuture: a function creates a DeferredFuture, schedules a callback with Revolt EventLoop, and returns the future. The caller awaits the future to get the result. Demonstrates the complete and getFuture methods.

```php
<?php // Example async producer using DeferredFuture

use Amp\Future;
use Revolt\EventLoop;

require __DIR__ . '/vendor/autoload.php';

function asyncMultiply(int $x, int $y): Future
{
    $deferred = new Amp\DeferredFuture;

    // Complete the async result one second from now
    EventLoop::delay(1, function () use ($deferred, $x, $y) {
        $deferred->complete($x * $y);
    });

    return $deferred->getFuture();
}

$future = asyncMultiply(6, 7);
$result = $future->await();

var_dump($result); // int(42)

```

--------------------------------

### Basic CompositeCancellation usage with two timeouts

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/CompositeCancellation.md

Basic usage example. Creates a composite cancellation with two timeouts (10 and 60 seconds) and passes it to an HTTP client request as a hard deadline.

```php
use Amp\CompositeCancellation;
use Amp\TimeoutCancellation;

$hardDeadline = new CompositeCancellation(
    new TimeoutCancellation(10.0),
    new TimeoutCancellation(60.0),
);

$response = $httpClient->request("https://example.com/", $hardDeadline);
```

--------------------------------

### isRequested() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Cancellation.md

Example of checking if a cancellation has been requested, allowing a poll-based path instead of throwing.

```php
if ($cancellation->isRequested()) {
    // poll-based path instead of throwing
}
```

--------------------------------

### awaitAny usage with multiple sources

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Usage example of awaitAny: it races multiple asynchronous sources and returns the value of the first one that completes successfully, ignoring failures. Shows how to pass an array of named futures and print the resulting value. Requires importing the function with `use function Amp\Future\awaitAny;`.

```php
use function Amp\Future\awaitAny;

// Race the fastest of several sources; ignore individual failures
$value = awaitAny([
    "cache" => Amp\async(fn () => readCache()),
    "primary" => Amp\async(fn () => queryPrimary()),
    "replica" => Amp\async(fn () => queryReplica()),
]);

print 'Served from a working source: ' . $value . PHP_EOL;
```

--------------------------------

### Advanced CompositeCancellation with DeferredCancellation and SignalCancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/CompositeCancellation.md

Advanced usage example. Composes a manual shutdown handle (DeferredCancellation) with an OS signal cancellation (SIGINT and SIGTERM), subscribes a callback to observe cancellation, then cancels via the deferred handle and unsubscribes.

```php
use Amp\CancelledException;
use Amp\CompositeCancellation;
use Amp\DeferredCancellation;
use Amp\SignalCancellation;

$deferred = new Amp\DeferredCancellation();
$cancellation = new CompositeCancellation(
    $deferred->getCancellation(),
    new SignalCancellation([SIGINT, SIGTERM]),
);

$id = $cancellation->subscribe(fn (CancelledException $e) {
    print 'Cancellation requested: ' . $e->getMessage() . PHP_EOL;
});

// somewhere else in the app:
$deferred->cancel();

$cancellation->unsubscribe($id);
```

--------------------------------

### CompositeCancellation with TimeoutCancellation and SignalCancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/CompositeCancellation.md

Example from the constructor section (src/CompositeCancellation.php:22). Creates a composite cancellation combining a 30-second timeout and a SIGINT signal cancellation.

```php
use Amp\CompositeCancellation;
use Amp\SignalCancellation;
use Amp\TimeoutCancellation;

$cancellation = new CompositeCancellation(
    new TimeoutCancellation(30.0),
    new SignalCancellation(SIGINT),
);
```

--------------------------------

### weakClosure function signature and usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

The function signature shows the parameter and return type. The usage example demonstrates wrapping a closure that captures $this in a Timer class to avoid a reference cycle. Invoking the returned closure after the object is destroyed throws an \Error.

```php
function weakClosure(\Closure $closure): \Closure
```

```php
use function Amp\weakClosure;

class Timer
{
    public Interval $interval;

    public function __construct(): void
    {
        // Weak closure so the Interval does not keep $this alive forever
        $this->interval = new Interval(0.5, weakClosure(fn () => $this->tick()));
    }

    private function tick(): void { /* ... */ }
}
```

--------------------------------

### throwIfRequested() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Cancellation.md

Example of using throwIfRequested() to fail cooperatively at a suspension point. Throws CancelledException once cancellation is requested.

```php
$cancellation->throwIfRequested(); // throws CancelledException once cancelled
```

--------------------------------

### ignore() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Example showing fire-and-forget usage: the future is ignored so that unhandled errors are not forwarded to the event-loop error handler.

```php
use Amp\Future;

// Fire-and-forget: we deliberately don't care about failures
$future = Amp\async(fn () => doSomethingRisky());
$future->ignore();
```

--------------------------------

### error() usage example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Creates an errored future with a RuntimeException and catches the exception when awaiting, printing the message.

```php
use Amp\Future;

$failed = Future::error(new \RuntimeException('cache miss'));
try {
    $failed->await();
} catch (\RuntimeException $e) {
    print $e->getMessage(); // "cache miss"
}
```

--------------------------------

### Basic TimeoutCancellation usage

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/TimeoutCancellation.md

Basic usage example: create a TimeoutCancellation with a 30-second timeout and pass it to a cancellation-aware request function. The cancellation will automatically trigger after the timeout.

```php
use Amp\TimeoutCancellation;

$cancellation = new TimeoutCancellation(30.0);
request("...", $cancellation);
```

--------------------------------

### async() function signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Declares the async() function that starts a new fiber and returns a Future. The closure must not have side effects on the caller's stack beyond its return value.

```php
function async(\Closure $closure, mixed ...$args): Future
```

--------------------------------

### awaitAnyN usage with replicas and error handling

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Usage example of awaitAnyN: waits for two successful completions out of four replicas, preserving keys in the result. It iterates over the successful values and prints them. In the catch block, it retrieves the errors from the CompositeException to inspect which replicas failed.

```php
use Amp\CompositeException;
use function Amp\Future\awaitAnyN;

try {
    // Any 2 of 4 replicas succeeding is enough
    $values = awaitAnyN(2, [
        "r1" => Amp\async(fn () => replica(1)),
        "r2" => Amp\async(fn () => replica(2)),
        "r3" => Amp\async(fn () => replica(3)),
        "r4" => Amp\async(fn () => replica(4)),
    ]);

    foreach ($values as $key => $value) {
        print "{$key}: {$value}" . PHP_EOL;
    }
} catch (CompositeException $e) {
    $errors = $e->getReasons(); // which replicas failed
}
```

--------------------------------

### Amp\CompositeException class and catch example

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/errors.md

CompositeException is thrown by awaitAny() when all futures error and by awaitAnyN() when too many futures error. The first block shows the class signature; the second shows catching it and iterating over getReasons() to print each reason's class and message.

```php
final class CompositeException extends \Exception
{
    public function __construct(array $reasons, ?string $message = null)
    public function getReasons(): array   // non-empty-array<array-key, \Throwable>
}
```

```php
use Amp\CompositeException;

try {
    awaitAny($futures);
} catch (CompositeException $e) {
    foreach ($e->getReasons() as $key => $reason) {
        print "{$key}: ", $reason::class, " — ", $reason->getMessage(), PHP_EOL;
    }
}
```

--------------------------------

### Basic usage: async and delay with await

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/README.md

Shows how to use Amp\async() and Amp\delay() to create a future that returns 42 after a 1-second delay, then await it. Requires Composer autoloading.

```php
require __DIR__ . '/vendor/autoload.php';

$future = Amp\async(function (): int {
    Amp\delay(1);
    return 42;
});

var_dump($future->await()); // int(42)
```

--------------------------------

### Run PHP app with AMP_DEBUG and assertions enabled

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/configuration.md

Run an application with future-origin tracking enabled by setting AMP_DEBUG=true and enabling PHP assertions with -dzend.assertions=1 -dassert.exception=1. This enables backtrace capture for Future creation and modifies UnhandledFutureError messages.

```bash
# run an application with future-origin tracking
AMP_DEBUG=true php -dzend.assertions=1 -dassert.exception=1 ./app.php
```

--------------------------------

### Using DeferredCancellation with a callback

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredCancellation.md

Shows how to use DeferredCancellation: create it, register a callback that calls cancel(), and pass the cancellation to an operation. The callback triggers cancellation later.

```php
use Amp\DeferredCancellation;

$deferredCancellation = new Amp\DeferredCancellation();

// Register some custom callback somewhere
onSomeEvent(fn () => $deferredCancellation->cancel());

request("...", $deferredCancellation->getCancellation());
```

--------------------------------

### Check if interval is referenced

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Example usage of isReferenced() showing the default result of bool(true).

```php
var_dump($interval->isReferenced()); // bool(true) by default
```

--------------------------------

### Get Future from DeferredFuture

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredFuture.md

Obtain the Future from the deferred and hand it to the caller, resolving later via the deferred.

```php
$deferred = new Amp\DeferredFuture();
$future = $deferred->getFuture();
// hand $future to the caller; resolve via $deferred later
```

--------------------------------

### enable() method signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Method signature for enable(). Restarts the repeating timer if previously disabled.

```php
public function enable(): self
```

--------------------------------

### Cancelling and catching CancelledException

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredCancellation.md

Shows how to cancel an operation and catch the resulting Amp\CancelledException when awaiting. The cancellation is passed to the await method.

```php
$deferredCancellation->cancel();

try {
    $future->await($deferredCancellation->getCancellation());
} catch (Amp\CancelledException) {
    // operation await aborted
}
```

--------------------------------

### awaitAll

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Documentation for the awaitAll function, which awaits all futures and returns errors and values.

```APIDOC
## awaitAll

### Description
Awaits **all** futures, tolerating every error, and returns results as a `[$errors, $values]` pair. Unlike `await` it never aborts early.

### Function Signature
```php
function awaitAll(iterable $futures, ?Cancellation $cancellation = null): array
```

### Parameters
- **$futures** (`iterable<Tk, Future<Tv>>`) - Required - Iterable of futures.
- **$cancellation** (`?Cancellation`) - Optional - Default: `null` - Optional cancellation.

### Return Type
`array{array<Tk, \Throwable>, array<Tk, Tv>}` — a two-element array `[$errors, $values]`; `$errors` maps each failed future's key to its exception, `$values` maps each successful future's key to its value.

### Throws
The cancellation's exception only (individual future errors are collected, not thrown).

### Example
```php
use function Amp\Future\awaitAll;

[$errors, $values] = awaitAll([
    "a" => Amp\async(fn (): int => 1),
    "b" => Amp\async(fn (): int => throw new \RuntimeException('b failed')),
]);

var_dump($values); // array<int> ["a" => 1]
var_dump($errors); // array<\Throwable> ["b" => RuntimeException]
```
```

--------------------------------

### Pass TimeoutCancellation to HTTP client

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/TimeoutCancellation.md

Basic call example: pass a TimeoutCancellation directly into an HTTP client request method. The request will be cancelled after 30 seconds if not completed.

```php
use Amp\TimeoutCancellation;

$response = $httpClient->request("https://example.com/", new TimeoutCancellation(30.0));
```

--------------------------------

### Future::complete()

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Static method to create an immediately-successful future.

```APIDOC
## `Future::complete()`

### Description
Creates a future that is already completed with the given value. `await()` returns immediately.

### Method
`public static function complete(mixed $value = null): self`

### Parameters
- `$value` (Tv) - Optional - Default: `null` - The already-known result value.

### Return Type
`Future<Tv>` - a future that is already completed; `await()` returns immediately.

### Throws
- `\Error("Cannot complete with an instance of Amp\Future")` if the value is another `Future` (thrown from the underlying state).

### Example
```php
use Amp\Future;

$cached = Future::complete(42);
var_dump($cached->await()); // int(42)
```
```

--------------------------------

### await: Concurrent HTTP requests with Future\await

Source: https://github.com/amphp/amp/blob/3.x/README.md

Uses Future\await to run multiple HTTP requests concurrently. If any request fails, the exception is caught and the message is printed. Requires the amphp/http-client package and autoloading the vendor directory.

```php
<?php

use Amp\Future;
use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\Request;

require __DIR__ . '/vendor/autoload.php';

$httpClient = HttpClientBuilder::buildDefault();
$uris = [
    "google" => "https://www.google.com",
    "news"   => "https://news.google.com",
    "bing"   => "https://www.bing.com",
    "yahoo"  => "https://www.yahoo.com",
];

try {
    $responses = Future\await(array_map(function ($uri) use ($httpClient) {
        return Amp\async(fn () => $httpClient->request(new Request($uri, 'HEAD')));
    }, $uris));

    foreach ($responses as $key => $response) {
        printf(
            "%s | HTTP/%s %d %s\n",
            $key,
            $response->getProtocolVersion(),
            $response->getStatus(),
            $response->getReason()
        );
    }
} catch (Exception $e) {
    // If any one of the requests fails the combo will fail
    echo $e->getMessage(), "\n";
}

```

--------------------------------

### Catching CompositeLengthException from awaitAnyN

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/errors.md

Shows catching CompositeLengthException when awaitAnyN is called with fewer futures than the required count. The example passes 3 as the count but only 1 future, triggering the exception with the message 'too few futures'.

```php
use Amp\CompositeLengthException;

try {
    awaitAnyN(3, [Amp\async(fn (): int => 1)]); // only 1 future
} catch (CompositeLengthException $e) {
    print $e->getMessage(); // too few futures
}
```

--------------------------------

### Creating SignalCancellation with single or multiple signals

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/SignalCancellation.md

Shows how to create a SignalCancellation with a single signal (SIGINT) or multiple signals (SIGINT, SIGTERM, SIGHUP) and pass it to a request function. The comment indicates the multi-signal variant.

```php
use Amp\SignalCancellation;

request("...", new SignalCancellation(SIGINT));
// or several signals:
request("...", new SignalCancellation([SIGINT, SIGTERM, SIGHUP]));
```

--------------------------------

### Advanced trapSignal call with cancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Advanced usage of trapSignal with cancellation. It waits for either SIGINT or SIGTERM, but if cancellation is requested, a CancelledException is thrown and caught, printing a shutdown message. This example requires importing Amp\CancelledException and the trapSignal function.

```php
use Amp\CancelledException;
use function Amp\trapSignal;

$cancel = new Amp\DeferredCancellation();

try {
    trapSignal([SIGINT, SIGTERM], cancellation: $cancel->getCancellation());
} catch (CancelledException) {
    print 'Interrupted by application shutdown' . PHP_EOL;
}
```

--------------------------------

### Advanced async() with error handling

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Shows how to handle timeout and closure exceptions when awaiting the future. Uses TimeoutCancellation and catches CancelledException and RuntimeException.

```php
use Amp\CancelledException;
use function Amp\async;

$future = async(function (): string {
    if (!\file_exists('/tmp/data')) {
        throw new \RuntimeException('missing input');
    }
    return \file_get_contents('/tmp/data');
});

try {
    $data = $future->await(new Amp\TimeoutCancellation(2.0));
} catch (CancelledException) {
    // timeout fired before the fiber finished
} catch (\RuntimeException $e) {
    // closure threw
}
```

--------------------------------

### Basic trapSignal call with SIGINT

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Basic usage of trapSignal to block the current fiber until SIGINT (Ctrl-C) is received. The function returns the signal number, which is then printed. This example requires importing the function via 'use function Amp\trapSignal;'.

```php
use function Amp\trapSignal;

$signo = trapSignal(SIGINT); // blocks this fiber until Ctrl-C
print 'Caught signal ' . $signo . PHP_EOL;
```

--------------------------------

### NullCancellation constructor

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/NullCancellation.md

Constructor call for NullCancellation. Takes no parameters and instances have no state.

```php
new NullCancellation()
```

--------------------------------

### Amp\Cancellation (interface)

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/types.md

Documentation for the Amp\Cancellation interface, including its methods and usage.

```APIDOC
## Amp\Cancellation (interface)

### Description
Defines a contract for cancellation tokens. Allows subscribing to cancellation callbacks, unsubscribing, and checking or throwing if cancellation has been requested.

### Interface
```php
interface Cancellation
{
    public function subscribe(\Closure $callback): string;
    public function unsubscribe(string $id): void;
    public function isRequested(): bool;
    public function throwIfRequested(): void;
}
```

### Methods

#### subscribe(\Closure $callback): string
- **Parameters:**
  - `$callback` (\Closure) - Required - Handler invoked on cancellation.
- **Returns:** `string` - Subscription id.

#### unsubscribe(string $id): void
- **Parameters:**
  - `$id` (string) - Required - Subscription id to remove.
- **Returns:** `void`

#### isRequested(): bool
- **Returns:** `bool` - Whether cancellation was requested.

#### throwIfRequested(): void
- **Throws:** `CancelledException` if cancellation was requested.
- **Returns:** `void`
```

--------------------------------

### subscribe()

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/NullCancellation.md

Registers a callback but never stores or invokes it. Returns the constant string 'null-cancellation'.

```APIDOC
## subscribe()

### Description
Registers a callback for cancellation notification. The callback is never stored and never invoked. Returns a constant string identifier.

### Method
subscribe

### Signature
php
public function subscribe(\Closure $callback): string


### Parameters
- **$callback** (\Closure) - Required - The callback to register. It is never called.

### Return Value
- **string** - Always the constant `"null-cancellation"`.

### Example
php
$id = $cancellation->subscribe($handler);
var_dump($id); // string("null-cancellation")

```

--------------------------------

### Optional cancellation default with NullCancellationToken

Source: https://github.com/amphp/amp/blob/3.x/README.md

Provides a no-op cancellation as a default for optional cancellation parameters.

This avoids null checks like `if ($cancellation)` when cancellation is not required.

Note: the source uses `NullCancellationToken` here, which is not the `NullCancellation` class named in the documentation, but appears in the example.

```php
$cancellation ??= new NullCancellationToken();
```

--------------------------------

### now() function signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Returns the current time in seconds relative to an arbitrary monotonic epoch, suitable for measuring time differences.

```php
function now(): float
```

--------------------------------

### now()

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/functions.md

Returns the current time relative to an arbitrary point in time (high-resolution, independent of wall-clock). Suitable for measuring time differences.

```APIDOC
## now()

### Description
Returns the current time relative to an arbitrary point in time (high-resolution, independent of wall-clock). Suitable for measuring time differences.

### Method
Function

### Endpoint
`Amp\now()`

### Parameters
No parameters.

### Return Type
`float` — seconds since an arbitrary (monotonic) epoch. Computed as `(float) \hrtime(true) / 1_000_000_000`.

### Example
```php
use function Amp\now;

$start = now();
Amp\delay(0.5);
$elapsed = now() - $start; // ≈ 0.5
```

### Source
`src/functions.php:51`
```

--------------------------------

### DeferredCancellation constructor

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredCancellation.md

Constructor signature with no parameters. Internally creates an Amp\Internal\Cancellable source and a WrappedCancellation facade. Note: when the object is destroyed, the source is cancelled.

```php
public function __construct()
```

--------------------------------

### await

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future-combinators.md

Documentation for the await function, which awaits all futures and aborts on the first error.

```APIDOC
## await

### Description
Awaits **all** futures and aborts as soon as any of them errors. The result maps input keys to values, in the order the futures *resolved* — not the order given by the iterable (sort after completion if order matters).

### Function Signature
```php
function await(iterable $futures, ?Cancellation $cancellation = null): array
```

### Parameters
- **$futures** (`iterable<Tk, Future<Tv>>`) - Required - Iterable of futures.
- **$cancellation** (`?Cancellation`) - Optional - Default: `null` - Optional cancellation.

### Return Type
`array<Tk, Tv>` — unwrapped values keyed by the input keys.

### Throws
- The first error (in completion order) propagates — the whole combination fails.
- The cancellation's exception.

### Example
```php
use Amp\Future;
use Amp\Http\Client\HttpClientBuilder;
use Amp\Http\Client\Request;
use function Amp\async;

$httpClient = HttpClientBuilder::buildDefault();
$uris = [
    "google" => "https://www.google.com",
    "news"   => "https://news.google.com",
];

try {
    $responses = Future\await(array_map(function ($uri) use ($httpClient) {
        return async(fn () => $httpClient->request(new Request($uri, 'HEAD')));
    }, $uris));

    foreach ($responses as $key => $response) {
        printf("%s | HTTP/%s %d %s\n", $key,
            $response->getProtocolVersion(), $response->getStatus(), $response->getReason());
    }
} catch (\Exception $e) {
    // If any one of the requests fails the combo will fail
    echo $e->getMessage(), "\n";
}
```
```

--------------------------------

### Class Signature and Constructor

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/NullCancellation.md

The class signature and constructor for NullCancellation. The constructor takes no parameters and instances have no state.

```APIDOC
## Class Signature

php
final class NullCancellation implements Cancellation
{
    use ForbidCloning;
    use ForbidSerialization;

    public function subscribe(\Closure $callback): string
    public function unsubscribe(string $id): void
    public function isRequested(): bool
    public function throwIfRequested(): void
}


## Constructor

php
new NullCancellation()


No parameters. Instances have no state.
```

--------------------------------

### Create a repeating Interval

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Creates an Interval that prints a dot every 0.5 seconds. The callback runs in a new coroutine each interval.

```php
use Amp\Interval;

$interval = new Interval(0.5, function (): void {
    print '.' . PHP_EOL;
});
```

--------------------------------

### iterate() basic usage

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Basic call to Future::iterate() that processes futures in completion order without attaching callbacks. Each future is awaited and its value printed.

```php
use Amp\Future;

foreach (Future::iterate($futures) as $key => $future) {
    $value = $future->await();
    print "Future {$key} completed with: ", var_export($value), PHP_EOL;
}
```

--------------------------------

### Amp\Closable

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/types.md

Interface contract for closable resources.

```APIDOC
## Amp\Closable (interface)

### Description
Defines a contract for resources that can be closed and notify on close.

### Methods

#### close(): void
Closes the resource, marking it unusable.

#### isClosed(): bool
Whether the resource is closed.

#### onClose(\Closure $onClose): void
Registers a close-notification callback.

```

--------------------------------

### complete() method signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredFuture.md

Signature of the complete() method. Accepts an optional mixed value (default null) and returns void. Throws \Error if the deferred is already completed or if the value is a Future.

```php
public function complete(mixed $value = null): void
```

--------------------------------

### Interval constructor signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Constructor signature for Interval. Accepts the interval in seconds, a closure to invoke, and an optional reference flag.

```php
public function __construct(float $interval, \Closure $closure, bool $reference = true)
```

--------------------------------

### Future::iterate()

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Static method to iterate futures in completion order.

```APIDOC
## `Future::iterate()`

### Description
Iterates over futures, yielding them in completion order. This is the engine behind the combinators in Future-combinators.md.

### Method
`public static function iterate(iterable $futures, ?Cancellation $cancellation = null): iterable`

### Parameters
- `$futures` (iterable<Tk, Future<Tv>>) - Required - Any iterable whose values are `Future` instances; array keys are preserved.
- `$cancellation` (?Cancellation) - Optional - Default: `null` - Optional cancellation; when requested, the suspension that is waiting for the next completion is aborted.

### Return Type
`iterable<Tk, Future<Tv>>` - a generator yielding `$key => $future` pairs in completion order.

### Throws
- `\TypeError("Array must only contain instances of Amp\Future")` for a non-`Future` element when `$futures` is an array (thrown synchronously during iteration).
- `\TypeError("Iterable must only provide instances of Amp\Future")` for non-array iterables (surfaced at the point of consumption because a separate fiber performs the iteration).
- The cancellation's exception if cancellation is requested while the consumer is blocked waiting for the next item.
- A future that errors is still yielded; the error is only thrown if the consumer awaits it.

### Example
```php
use Amp\Future;

foreach (Future::iterate($futures) as $key => $future) {
    $value = $future->await();
    print "Future {$key} completed with: ", var_export($value), PHP_EOL;
}
```
```

--------------------------------

### DeferredCancellation::__construct

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredCancellation.md

Constructor for creating a new DeferredCancellation instance.

```APIDOC
## Constructor

### Description
Creates a new deferred cancellation instance.

### Method
`__construct`

### Signature
```php
public function __construct()
```

### Parameters
None.

### Example
```php
$deferred = new Amp\DeferredCancellation();
```
```

--------------------------------

### Chain reference and unreference

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Interval.md

Shows that reference() and unreference() are chainable and can be called in sequence.

```php
$interval->reference()->unreference(); // chainable no-op round trip
```

--------------------------------

### Amp\TimeoutCancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/TimeoutCancellation.md

Documentation for the Amp\TimeoutCancellation class, including its constructor and methods for subscribing to cancellation, unsubscribing, checking if cancellation was requested, and throwing if requested.

```APIDOC
## TimeoutCancellation::__construct

### Description
Creates a cancellation that automatically requests cancellation after a specified timeout. Once triggered, subscribers are notified with a CancelledException whose previous exception is an Amp\TimeoutException carrying the configured message.

### Method
Constructor

### Signature
```php
public function __construct(float $timeout, string $message = "Operation timed out")
```

### Parameters
- **$timeout** (float) - Required - Seconds until cancellation is requested.
- **$message** (string) - Optional - Message for the TimeoutException used as the previous exception. Defaults to "Operation timed out".

### Usage Example
```php
use Amp\TimeoutCancellation;

$cancellation = new TimeoutCancellation(30.0);
request("...", $cancellation);
```

### Notes
- Registers a one-shot Revolt\EventLoop::delay watcher and immediately unreferences it, so the event loop may exit while the timer is pending.
- When the timer fires, subscribers receive a CancelledException with a TimeoutException as previous.
- When assertions are enabled, the message is augmented with a backtrace of where the TimeoutCancellation was created.
- Destruction cancels the delay watcher, so a cancelled/abandoned timeout stops keeping the process alive.

## TimeoutCancellation::subscribe

### Description
Registers a callback to be invoked when the timeout fires. Returns a subscription id. The callback is queued (not called synchronously) with the CancelledException when the timeout fires. If the timeout already fired, the callback is queued immediately.

### Method
subscribe

### Signature
```php
public function subscribe(\Closure $callback): string
```

### Parameters
- **$callback** (Closure) - Required - The callback to invoke with the CancelledException when the timeout fires.

### Return Value
- **string** - Subscription id that can be used to unsubscribe.

## TimeoutCancellation::unsubscribe

### Description
Removes a previously registered subscription.

### Method
unsubscribe

### Signature
```php
public function unsubscribe(string $id): void
```

### Parameters
- **$id** (string) - Required - The subscription id returned by subscribe().

## TimeoutCancellation::isRequested

### Description
Returns true once the timeout has elapsed.

### Method
isRequested

### Signature
```php
public function isRequested(): bool
```

### Return Value
- **bool** - True if the timeout has elapsed, false otherwise.

## TimeoutCancellation::throwIfRequested

### Description
Throws the CancelledException if the timeout has elapsed, otherwise does nothing.

### Method
throwIfRequested

### Signature
```php
public function throwIfRequested(): void
```

### Exceptions
- **CancelledException** - Thrown if the timeout has elapsed.

## Usage Example

### Basic Usage
```php
use Amp\TimeoutCancellation;

$response = $httpClient->request("https://example.com/", new TimeoutCancellation(30.0));
```

### Advanced Usage with Try/Catch
```php
use Amp\CancelledException;
use Amp\TimeoutCancellation;
use Amp\TimeoutException;

$cancellation = new TimeoutCancellation(1.0, "render deadline");

try {
    $result = renderReport()->await($cancellation);
} catch (CancelledException $e) {
    // $e->getPrevious() is Amp\TimeoutException in this build of PHP
    print 'The operation exceeded the time limit' . PHP_EOL;
}
```
```

--------------------------------

### complete() signature

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Future.md

Signature for Future::complete(), which creates an already-completed future with the given value.

```php
public static function complete(mixed $value = null): self
```

--------------------------------

### Interface signature for Amp\Cancellation

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/Cancellation.md

The full interface signature for Amp\Cancellation, showing the four methods that any cancellation implementation must provide.

```php
interface Cancellation
{
    public function subscribe(\Closure $callback): string;
    public function unsubscribe(string $id): void;
    public function isRequested(): bool;
    public function throwIfRequested(): void;
}
```

--------------------------------

### DeferredFuture::__construct

Source: https://github.com/amphp/amp/blob/3.x/_autodocs/api-reference/DeferredFuture.md

Constructor for creating a new DeferredFuture instance.

```APIDOC
## Constructor

### Description
Creates a new DeferredFuture instance with an associated Future.

### Method
__construct

### Signature
```php
public function __construct()
```

### Parameters
None.

### Return Type
void

### Example
```php
$deferred = new Amp\DeferredFuture();
$future = $deferred->getFuture();
```
```
Tokens:
Raw