Reference / Async

async()

function async(callable $main): mixed

Run $main to completion on the async engine and return its value.

This is the entry point: an async block composes like an ordinary call. It opens the implicit root scope, so a top-level spawn() is still structured and joined before async() returns. Whatever escapes the root scope is thrown from async(). If the loop runs out of work while tasks are still parked, DeadlockException is thrown instead of exiting silently. A root cancellation (see shutdownOn()) is a shutdown, not a failure: async() returns normally.

$total = Async\async(function () {
    $a = Async\spawn(fn() => 1);
    $b = Async\spawn(fn() => 2);
    return $a->await() + $b->await();
});

Each async() call starts a fresh, independent engine.

Parameters

$main callable

the program; called with no arguments, as the root task

Returns

mixed — the value returned by $main

Throws

\Throwable

whatever escaped the root scope

DeadlockException

when tasks are left parked with nothing to wake them

Example

use function Async\async;
use function Async\delay;
use function Async\spawn;

// async() runs the callable on the engine and returns its value.
$total = async(function () {
    // spawn() starts a task in the current scope and returns a handle.
    $slow = spawn(function () {
        delay(0.02);
        return 10;
    });
    $fast = spawn(function () {
        delay(0.01);
        return 32;
    });

    // await() suspends this task (not the process) until the other one settles.
    return $slow->await() + $fast->await();
});

echo "total: $total\n";

Output

total: 42

See also: spawn, group, shutdownOn

View source