DOCSEARCHbyAlgolia
Submit Docs

Pokio Documentation

repository·main·Indexed 20 days ago

https://github.com/nunomaduro/pokio

A simple asynchronous API for PHP 8.3+ that utilizes process forking via PCNTL and shared memory via FFI to achieve concurrency. It provides global async() and await() functions, along with promises supporting then(), catch(), and finally() method chaining.

Tokens
1.1K
Snippets
5
Records
6
Agent score
23%

What's inside Pokio

  1. How Pokio's asynchronous model works

    main

    Pokio provides an asynchronous API by using the PCNTL extension to fork the current process and run closures in child processes. This allows multiple tasks to run concurrently without blocking the main process.

    For efficient data sharing between the parent and child processes, Pokio uses FFI to create a shared memory segment.

    Fallback Behavior: If the PCNTL or FFI extensions are not available, Pokio automatically falls back to sequential execution, ensuring the code still runs (though without concurrency benefits).

  2. Install Pokio via Composer

    main

    To use Pokio, require it via Composer. Note that Pokio requires PHP 8.3+.

    Caution: This package uses low-level techniques like FFI for inter-process communication and process lifecycle manipulation. It is intended for internal use (e.g., performance optimizations in Pest) and should not be used in production without understanding the risks.

    composer require nunomaduro/pokio

  3. Invoke a promise directly to get its value

    main

    Instead of using the await() function, you can invoke a promise object directly as a function to return its resolved value.

    $promise = async(fn (): int => 1 + 2);

$result = $promise();

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

  4. Use the await() function to resolve promises

    main

    The await global function blocks the current process until the given promise (or array of promises) resolves.

    • Single Promise: await($promise) returns the resolved value.
    • Array of Promises: await([$promiseA, $promiseB]) awaits them simultaneously and returns an array of their resolved values.
    // Awaiting a single promise
$promise = async(function () {
    sleep(2);
    return 1 + 1;
});
var_dump(await($promise)); // int(2)

// Awaiting multiple promises concurrently
$promiseA = async(fn() => 1 + 1);
$promiseB = async(fn() => 2 + 2);
var_dump(await([$promiseA, $promiseB])); // array(2) { [0]=> int(2) [1]=> int(4) }

  5. Chain methods on promises with then(), catch(), and finally()

    main

    Pokio promises support method chaining for handling resolution, errors, and cleanup:

    • then(closure): Called when the promise resolves successfully. The closure receives the resolved value as its first argument.
    • catch(closure): Called if the closure throws an exception. The closure receives the Throwable as its argument.
    • finally(closure): Called regardless of whether the promise resolves or throws.
    // Using then()
$promise = async(fn (): int => 1 + 2)
    ->then(fn ($result): int => $result + 2)
    ->then(fn ($result): int => $result * 2);

var_dump(await($promise)); // int(10)

// Using catch()
$promise = async(function () {
    throw new Exception('Error');
})->catch(function (Throwable $e) {
    return 'Rescued: ' . $e->getMessage();
});

var_dump(await($promise)); // string(16) "Rescued: Error"

// Using finally()
$promise = async(function (): void {
    throw new RuntimeException('Exception 1');
})->finally(function () {
    echo "Finally called\n";
});

  6. Use the async() function to create promises

    main

    The async global function returns a promise that eventually resolves to the value returned by the provided closure. If the closure returns another promise, it will be awaited automatically.

    $promise = async(function () {
    return 1 + 1;
});

var_dump(await($promise)); // int(2)