PHP True Async

• Version: 1.4
• Date: 2025-09-30
• Author: Edmond [HT], edmondifthen@proton.me
• Status: Under discussion
• First Published at: http://wiki.php.net/rfc/true_async
• Git: https://github.com/true-async

For several years, PHP has been attempting to carve out a niche in the development of long-running applications, where concurrent code execution becomes particularly useful. Production-ready solutions such as Swoole, AMPHP, ReactPHP, and others have emerged.

However, PHP still does not provide a comprehensive implementation for writing concurrent code. PHP extensions have no way to support non-blocking execution, even if they are capable of doing so. Swoole is forced to copy thousands of lines of code just for a few modifications, while AMPHP developers have to build drivers for MySQL, PostgreSQL, Redis, and other systems from scratch in user-land.

The goal of this RFC is to establish a standard for writing concurrent code in PHP, as well as a C-API interface that would allow PHP to be extended at a low level using C, Rust, C++, and other languages. This would enable extensions to support non-blocking I/O without the need to override PHP functions or duplicate code.

The True Async project pursues the following goals and values:

• From a PHP developer's perspective, the main value of this implementation is that they DO NOT NEED to change existing code (or if changes are required, they should be minimal) to enable concurrency. Unlike explicit async models, this approach lets developers reuse existing synchronous code inside fibers without modification.

• Code that was originally written and intended to run outside of a Coroutine must work EXACTLY THE SAME inside a Coroutine without modifications.

• A PHP developer should not have to think about how Coroutine switch and should not need to manage their switching—except in special cases where they consciously choose to intervene in this logic.

• If there is existing code or a familiar style, such as AMPHP interfaces, Go coroutines, Swoole API, and others, it is best to use what is most recognizable to a broad range of developers.

• The goal is to find a balance between flexibility and simplicity. On one hand, the implementation should allow leveraging existing solutions without requiring external libraries. On the other hand, it should avoid unnecessary complexity. Many design choices in this implementation are driven by the desire to free developers from concerns about compatibility with “external libraries” in favor of a standardized approach.

This RFC does not include modifications to PHP built-in functions or PHP extension functions!

Code examples that involve PHP built-in stream functions, such as file_get_contents, as well as sleep, usleep, and PHP Socket functions are provided for demonstration purposes only to better illustrate the content of the RFC.

This RFC is quite complex due to the number of logical connections. Please use the diagrams from the table to simplify understanding.

This RFC describes the API for writing concurrent code in PHP, which includes:

A lightweight execution thread that can be suspended (suspend) and resumed. Example:

spawn(function() {
    echo "Start";
    suspend();  // Suspend the coroutine
    echo "Resumed";
});

A container that manages coroutine lifetimes. Example:

$scope = new Async\Scope();
$scope->spawn(function() {
    // Coroutine bound to $scope
    spawn(function() {
        // Coroutine bound to $scope
    });
});
 
// Dispose of the scope after 5 seconds
sleep(5);
$scope->disposeSafely();

A special exception that implements cooperative cancellation: Example:

$coroutine = spawn(function() {
    try {
        Async\delay(1000);
    } catch (Async\CancellationError $e) {
        echo "Coroutine cancelled";
    }
});
 
suspend();
 
$coroutine->cancel();

function fetchData(string $file): string
{
    $result = file_get_contents($file);
 
    if($result === false) {
        throw new Exception("Error reading $file");
    }
 
    return $result;
}
echo await(spawn(fetchData(...), "file.txt"));

A set of functions that enables synchronization of execution with multiple awaitable objects: awaitAny(), awaitAll(), awaitFirstSuccess(). Example:

$results = awaitAll([spawn(task1(...)), spawn(task2(...))]);

echo await(spawn('fetchData', "https://php.net/"), Async\timeout(2000));
echo await(spawn('fetchData', "https://php.net/"), spawn('sleep', 2));

Transferring control from the coroutine to the other coroutines.:

function myFunction(): void {
    echo "Hello, World!\n";
    Async\suspend();
    echo "Goodbye, World!\n";
}
 
Async\spawn(myFunction(...));
echo "Next line\n";

Output:

Hello, World
Next line
Goodbye, World

use Async\Scope;
 
function getUserProfile(int $userId): array {
    $scope = new Scope();
    $tasks = [];
 
    $tasks[] = $scope->spawn(fetchUserData(...), $userId);
    $tasks[] = $scope->spawn(fetchUserOrders(...), $userId);
    $tasks[] = $scope->spawn(fetchUserSettings(...), $userId);
 
    return awaitAllOrFail($tasks);
}

This RFC is based on the principle of “Cancellable by design”, which can be described as follows:

By default, coroutines should be designed in such a way that their
cancellation at any moment does not compromise data integrity.

Coroutines launched without a defined Scope or lifetime must adhere to the “Cancellable by design” principle.

If a coroutine’s lifetime needs to be controlled — it MUST be done EXPLICITLY!

In practice, this means that if a coroutine is created without specifying a Scope, the developer treats it as non-critical in terms of data integrity. If it is necessary to manage the coroutine’s lifetime, a Scope MUST be defined. In other words, the developer must take extra steps to explicitly extend the coroutine’s lifetime.

All functions, classes, and constants defined in this RFC are located in the Async namespace. Extensions for Scheduler/Reactor are allowed to extend this namespace with functions and classes, provided that they are directly related to concurrency functionality.

A Coroutine is an execution container, transparent to the code,
that can be suspended on demand and resumed at any time.

Isolated execution contexts make it possible to switch between coroutines and execute tasks concurrently.

Any function can be executed as a coroutine without any changes to the code.

A coroutine can stop itself bypassing control to the Scheduler. However, it cannot be stopped externally.

⚠️ Warning:
It is permissible to stop a coroutine’s execution externally for two reasons:
* To implement multitasking.
* To enforce an active execution time limit.

A suspended coroutine can be resumed at any time. The Scheduler component is responsible for the coroutine resumption algorithm.

A coroutine can be resumed with an exception, in which case an exception will be thrown from the suspension point.

This state diagram illustrates the lifecycle of a coroutine, showing how it transitions through various states during its execution:

States:

1. Created – The coroutine has been defined but not yet started.
2. Queued – The coroutine is queued
3. Running – The coroutine is actively executing.
4. Suspended – Execution is paused, usually waiting for a result or I/O.
5. Completed – The coroutine has finished successfully (via return).
6. Pending Cancellation – A cancellation was requested; the coroutine is cleaning up.

Key Transitions:

1. spawn moves a coroutine from Created to Running.
2. suspend and resume move it between Running and Suspended.
3. return/exit ends it in Completed.
4. cancel() initiates cancellation from Running or Suspended, leading to Pending Cancellation, and finally Cancelled.

To create coroutines, the spawn(callable $callable, mixed ...$args) function is used. It launches the <callable> in a separate execution context and returns an instance of the Async\Coroutine class as a result.

Let's look at two examples:

Note: The examples below are for demonstration purposes only.
The non-blocking version of the file_get_contents function is not part of this RFC.

$result = file_get_contents('https://php.net');
echo "next line".__LINE__."\n";

This code:

1. first returns the contents of the PHP website,
2. then executes the ''echo'' statement.

$coroutine = spawn('file_get_contents', 'https://php.net');
echo "next line".__LINE__."\n";

This code:

1. starts a coroutine with the ''file_get_contents'' function.
2. The next line is executed without waiting for the result of ''file_get_contents''.
3. The coroutine is executed after the ''echo'' statement.

spawnWith(Async\ScopeProvider $scope, callable $callable, mixed ...$args) allows launching a coroutine with a specific Scope.

The parameter can be either an Async\Scope object or a class that implements the Async\ScopeProvider interface.

Note: The non-blocking version of the gethostbyname function is not part
of this RFC and is provided for demonstration purposes only.

$scope = new Async\Scope();
 
$coroutine = spawnWith($scope, function() use ():string {
    return gethostbyname('php.net');
});
 
function defineTargetIpV4(string $host): string {
    return gethostbyname($host);
}
 
spawnWith($scope, defineTargetIpV4(...), $host);

You can also use the spawn method, which is available for the Scope and CoroutineGroup classes:

$scope = new Async\Scope();
 
$coroutine = $scope->spawn(function() use ():string {
		return gethostbyname('php.net');
});
 
function defineTargetIpV4(string $host): string {
		return gethostbyname($host);
}
 
$coroutine = $scope->spawn(defineTargetIpV4(...), $host);

The ScopeProvider interface allows objects to provide an Async\Scope instance that can be used in a spawnWith function.

This is useful when you want to abstract the scope management logic, letting higher-level structures (like a coroutine group or a custom container) expose a scope without directly exposing internal details.

declare(strict_types=1);
 
namespace Async;
 
interface ScopeProvider
{
    /**
     * Returns the associated Scope instance.
     *
     * This scope will be used when spawning a coroutine via ''spawn with $provider''.
     *
     * @return Scope|null
     */
    public function provideScope(): ?Scope;
}

The provideScope method may return NULL; in this case, the current Scope will be used.

Example Use Case:

A coroutine group can implement this interface to automatically provide its internal scope to spawn with:

class CustomCoroutineGroup implements ScopeProvider
{
    private Scope $scope;
 
    public function __construct()
    {
        $this->scope = new Scope();
    }
 
    public function provideScope(): ?Scope
    {
        return $this->scope;
    }
}

This allows you to spawn coroutines into the task group using:

$coroutineGroup->spawn(function() {
    // This coroutine is bound to the CoroutineGroup's scope
});

The SpawnStrategy interface allows attaching a newly spawned coroutine to a custom user-defined context immediately after the spawn with expression is evaluated.

This is useful for scenarios where the coroutine should be registered, tracked, or logically grouped within a context.

interface SpawnStrategy extends ScopeProvider
{
    /**
     * Called before a coroutine is spawned, before it is enqueued.
     *
     * @param   Coroutine   $coroutine  The coroutine to be spawned.
     * @param   Scope       $scope      The Scope instance.
     *
     */
    public function beforeCoroutineEnqueue(Coroutine $coroutine, Scope $scope): array;
 
    /**
     * Called after a coroutine is spawned, enqueued.
     *
     * @param Coroutine $coroutine
     * @param Scope     $scope
     */
    public function afterCoroutineEnqueue(Coroutine $coroutine, Scope $scope): void;
}

If the $scope object in a spawn with expression implements the SpawnStrategy interface, then the acceptCoroutine method will be called immediately after the coroutine is created.

Example:

A class like CustomCoroutineGroup might implement this interface to automatically collect all spawned coroutines under its management:

class CustomCoroutineGroup implements Async\SpawnStrategy
{
    private array $coroutines = [];
 
    public function afterCoroutineEnqueue(Coroutine $coroutine, Scope $scope): void
    {
        $this->coroutines[] = $coroutine;
        echo "Coroutine added to the group as ".$coroutine->getSpawnLocation()."\n";
    }
 
    // Additional methods for managing the group...
}
 
$customCoroutineGroup = new CustomCoroutineGroup();
 
$customCoroutineGroup->spawn(function() {
    // This coroutine will be automatically added to the custom task group
});

The beforeCoroutineEnqueue() method is called after the coroutine has been created, but before it is added to the queue. It allows for additional operations to be performed with the coroutine and its context, and it returns an optional list of options for the Scheduler.

The list of options for the Scheduler is not part of this RFC
and is defined by the Scheduler implementation.

class HiPriorityStrategy implements Async\SpawnStrategy
{
    public function beforeCoroutineEnqueue(Coroutine $coroutine, Scope $scope): array
    {
        // Mark the coroutine as high priority before it is enqueued
        $coroutine->asHiPriority();
 
        return [];
    }
 
    // Additional methods ...
}
 
spawnWith(new HiPriorityStrategy(), function() {
    // This coroutine will be marked as high priority
});

The Async\hiPriority(?Scope $scope = null) function allows launching a coroutine with high priority:

use function Async\hiPriority;
 
spawn(function() {
    echo "normal priority\n";
});
 
spawnWith(hiPriority(), function {
    echo "high priority\n";
});

Expected output:

high priority
normal priority

If the $scope parameter is not specified, the current Scope will be used for launching.

The hiPriority strategy marks the coroutine as high-priority using the Coroutine::asHiPriority() method.

This action serves as a recommendation for the Scheduler, suggesting that the coroutine should be placed as close to the front of the queue as possible. However, the programmer MUST NOT rely on this outcome.

hiPriority can be useful in situations where resources need to be released as quickly as possible or when a critical section of code must be executed promptly. The programmer should not overuse it, as this may negatively affect the application's performance.

A coroutine can suspend itself at any time using the suspend keyword:

function example(string $name): void {
    echo "Hello, $name!";
    Async\suspend();
    echo "Goodbye, $name!";
}
 
spawn('example', 'World');
spawn('example', 'Universe');

Expected output:

Hello, World!
Hello, Universe!
Goodbye, World!
Goodbye, Universe!

Basic usage:

    Async\suspend();

The suspend can be used in any function including from the main execution flow:

function example(string $name): void {
    echo "Hello, $name!";
    Async\suspend();
    echo "Goodbye, $name!";
}
 
$coroutine = spawn(example(...), 'World');
 
// suspend the main flow
Async\suspend();
 
echo "Back to the main flow";

Expected output:

Hello, World!
Back to the main flow
Goodbye, World!

The suspend keyword can be a throw point if someone resumes the coroutine externally with an exception.

function example(string $name): void {
    echo "Hello, $name!";
 
    try {
        suspend();
    } catch (Exception $e) {
        echo "Caught exception: ", $e->getMessage();
    }
 
    echo "Goodbye, $name!";
}
 
$coroutine = spawn('example', 'World');
 
// pass control to the coroutine
suspend();
 
$coroutine->cancel();

Expected output:

Hello, World!
Caught exception: cancelled at ...
Goodbye, World!

The Awaitable interface is a contract that allows objects to be used in the await expression.

The interface does not have any methods on the user-land side and is intended for objects implemented as PHP extensions, such as:

- Future - Cancellation - CoroutineGroup

Note: These classes are not part of this RFC.

The following classes from this RFC also implement this interface:

- Coroutine

Unlike Future, the Awaitable interface does not impose limitations on the number of state changes, which is why the Future contract is considered a special case of the Awaitable contract.

In the general case, objects implementing the Awaitable interface can act as triggers — that is, they can change their state an unlimited number of times. This means that multiple calls to await <Awaitable> may produce different results.

In contrast, Coroutine, Future and Cancellation objects change their state only once, so using them multiple times in an await expression will always yield the same result.

Comparison of Different Awaitable Classes:

Async\await(Async\Awaitable $awaitable, ?Async\Awaitable $cancellation = null): mixed

The await function is used to wait for the completion of another coroutine or any object that implements the Awaitable interface.:

function readFile(string $fileName):string
{
    $result = file_get_contents($fileName);
 
    if($result === false) {
        throw new Exception("Error reading file1.txt");
    }
 
    return $result;
}
 
$coroutine = spawn(readFile(...), 'file1.txt');
 
echo await($coroutine);
// or
echo await spawn(readFile(...), 'file2.txt');

await suspends the execution of the current coroutine until the awaited one returns a final result or completes with an exception.

function testException(): void {
    throw new Exception("Error");
}
 
try {
    await(spawn(testException(...)));
} catch (Exception $e) {
    echo "Caught exception: ", $e->getMessage();
}

The await function can accept a second argument $cancellation, which is an Awaitable object. This object can be a Coroutine, or another object that implements the Awaitable interface.

The $cancellation argument limits the waiting time for the first argument. As soon as the $cancellation is triggered, execution is interrupted with an exception AwaitCancelledException.

function readFile(string $fileName):string
{
		$result = file_get_contents($fileName);
 
		if($result === false) {
				throw new Exception("Error reading file1.txt");
		}
 
		return $result;
}
 
try {
		// Wait for the coroutine to finish or for the cancellation to occur
		echo await(spawn(readFile(...), 'file1.txt'), Async\timeout(2000));
} catch (AwaitCancelledException $e) {
		echo "Caught exception: ", $e->getMessage();
}

The use of spawn/await/suspend is allowed in any part of a PHP program. This is possible because the PHP script entry point forms the main execution thread, which is also considered a coroutine.

As a result, operations like suspend and currentCoroutine() will behave the same way as in other cases.

Asynchronous code will work as expected, including inside register_shutdown_function.

Coroutine Scope — the space associated with coroutines created using the spawn expression.

Sometimes it is necessary to gain control not only over a currently running coroutine, but also over all coroutines that will be launched within a new one — without having direct access to them. This could be the case for web server code that handles requests in separate coroutines and does not know how many additional coroutines will be launched, or a JobExecutor that wants to manage the lifecycle of running jobs.

Without such control, the application code loses the ability to resist runtime errors, which increases the risk of a complete service failure.

This is why the Coroutine Scope pattern is of critical importance in the context of ensuring reliability.

The main use cases for Scope are:

1. Controlling the lifetime of coroutines created within a single scope (Point of responsibility) 2. Handling errors from all coroutines within the scope 3. Binding the lifetime of the scope's coroutines to the lifetime of a PHP object 4. Creating a hierarchy of scopes to manage coroutines in a structured way

Binding Scope to objects is a good practice that has proven effective in Kotlin. By allowing coroutines to be tied to an object (this could be a Screen or a ViewModel), it is possible to avoid the error where coroutines outlive the object that manages them.

For frameworks, it can be useful to be able to control all coroutines created within a Scope, to apply context-dependent constraints to them.

By default, all coroutines are associated with the Global Coroutine Scope:

spawn('file_get_contents', 'file1.txt'); // <- global scope
 
function readFile(string $file): void {
    return file_get_contents($file); 		 // <- global scope
}
 
function mainTask(): void { 			  	   // <- global scope
    spawn('readFile', 'file1.txt'); 		 // <- global scope
}
 
spawn('mainTask'); 										   // <- global scope

If an application never creates custom Scopes, its behavior is similar to coroutines in Go:

• Coroutines are not explicitly linked to each other.
• The lifetime of coroutines is not limited.

The function spawnWith creates a new coroutine bound to the specified scope. Scope is propagated between coroutines. If a coroutine is launched within a specific Scope, that Scope is considered the current one. The function like spawn(<callable>) will create a coroutine within the current Scope.

Coroutines created during the execution of this new coroutine will become sibling tasks:

use Async\Scope;
 
$scope = new Scope();
 
$scope->spawn(function() { // <- new scope
 
    echo "Sibling task 1\n";
 
    spawn(function() { // <- $scope is current scope
        echo "Sibling task 2\n";
 
        spawn(function() { // <- $scope is current scope
            echo "Sibling task 3\n";
        });
    });
});
 
$scope->awaitCompletion(Async\signal(SIGTERM));

Expected output:

Sibling task 1
Sibling task 2
Sibling task 3

Structure:

main()                          ← defines a $scope
└── $scope = new Scope()
    ├── task1()                 ← runs in the $scope
    ├── task2()                 ← runs in the $scope
    ├── task3()                 ← runs in the $scope

Thus, the function spawnWith() or method Scope::spawn creates a new branch of sibling coroutines, where the new coroutine exists at the same level as all subsequent ones.

The code that owns a Scope object becomes the Point of responsibility for all coroutines executed within that Scope.

A good practice is to ensure that a Scope object has only ONE owner.
Passing $scope as a parameter to other functions or assigning it to multiple objects
is a potentially dangerous operation that can lead to complex bugs.
If you need to interact with the Scope in different parts of the program,
use Async\ScopeProvider containers or other appropriate mechanisms.

The Scope class does not implement the Awaitable interface, and therefore cannot be used in an await expression. Awaiting a Scope is a potentially dangerous operation that should be performed consciously, not accidentally.

There are several Use-Cases where waiting for a Scope might be necessary: * Structured concurrency: when a parent awaits the completion of all child coroutines. * Waiting for Scope tasks to complete the cancellation process.

The structured concurrency pattern with waiting for all child coroutines can be useful for applications whose lifetime is explicitly limited by external conditions. For example, the user might stop a console application.

To support a task awaiting in a controlled manner, Scope provides two specific methods:

- public function awaitCompletion(Awaitable $cancellation): void {} - public function awaitAfterCancellation(?callable $errorHandler = null, ?Awaitable $cancellation = null): void {}

The awaitCompletion method blocks the execution flow until all tasks within the scope are completed. The awaitAfterCancellation method does the same but is intended to be called only after the scope has been cancelled.

use Async\Scope;
 
$scope = new Scope();
 
$scope->spawn(function() {
 
    echo "Sibling task 1\n";
 
    spawn(function() {
        echo "Sibling task 2\n";
 
        spawn(function() {
            echo "Sibling task 3\n";
        });
    });
});
 
$scope->awaitCompletion(Async\signal(SIGTERM));

Expected output:

Sibling task 1
Sibling task 2
Sibling task 3

The Scope awaiting methods do not capture any task results, so they cannot be used to await return values.

The awaitCompletion method can only be used with an explicitly defined cancellation token. This requirement helps prevent indefinite waiting.

Awaiting the $scope object also allows handling exceptions from coroutines within the $scope:

use Async\Scope;
 
$scope = new Scope();
 
$scope->spawn(function() {
    spawn(function() {
        spawn(function() {
            throw new Exception("Error occurred");
        });
    });
});
 
try {
    $scope->awaitCompletion(Async\signal(SIGTERM));
} catch (Exception $exception) {
    echo $exception->getMessage()."\n";
}

Expected output:

Error occurred

Calling the awaitCompletion() method after the Scope has been cancelled will immediately throw a cancellation exception.

$scope = new Scope();
 
try {
    $scope->spawn(task1(...));
    $scope->spawn(task2(...));
    $scope->cancel();
    // Wait all tasks
    $scope->awaitCompletion(Async\signal(SIGTERM));
} catch (Exception $exception) {
    echo "Caught exception: ",$exception->getMessage()."\n";
}

Expected output:

Caught exception: cancelled at ...

In this example, $scope->awaitCompletion(Async\signal(SIGTERM)); will immediately throw an exception.

If you need to wait for the Scope to complete after it has been cancelled, use the special method awaitAfterCancellation, which is designed for this case.

$scope = new Scope();
 
spawn(function() {
    try {
        $scope->awaitCompletion(Async\signal(SIGTERM));
    } catch (\Async\CancellationError $exception) {
        $scope->awaitAfterCancellation();
        echo "Caught exception: ",$exception->getMessage()."\n";
    }
});
 
$scope->spawn(function() use ($scope) {
    $scope->cancel();
 
    try {
        Async\delay(1000);
    } finally {
        sleep(1);
        echo "Finally\n";
    }
});

Expected output:

Finally
Caught exception: cancelled at ...

In this example, the line Finally will be printed first because $scope->awaitAfterCancellation() waits for all coroutines inside the Scope to complete.

The awaitAfterCancellation method is used in scenarios where final resource cleanup is required after all child tasks are guaranteed to have finished execution.

There is also a risk of indefinite waiting, so it is recommended to explicitly specify a timeout.

A hierarchy can be a convenient way to describe an application as a set of dependent tasks:

• Parent tasks are connected to child tasks and are responsible for their execution time.
• Tasks on the same hierarchy level are independent of each other.
• Parent tasks should control their child's tasks.
• Child tasks MUST NOT control or wait for their parent tasks.
• It is correct if tasks at the same hierarchy level are only connected to tasks of the immediate child level.

WebServer
├── Request Worker
│   ├── request1 task
│   │   ├── request1 subtask A
│   │   └── request1 subtask B
│   └── request2 task
│       ├── request2 subtask A
│       └── request2 subtask B

The work of a web server can be represented as a hierarchy of task groups that are interconnected. The Request Worker is a task responsible for handling incoming requests. There can be multiple requests. Each request may spawn subtasks. On the same level, all requests form a group of request-tasks.

Scope is fit for implementing this concept:

WebServer
├── Request Worker
│   ├── request1 Scope
│   │   ├── request1 subtask A
│   │   │   └── subtask A Scope
│   │   │       ├── sub-subtask A1
│   │   │       └── sub-subtask A2
│   │   └── request1 subtask B
│   └── request2 Scope
│       ├── request2 subtask A
│       └── request2 subtask B
│           └── subtask B Scope
│               └── sub-subtask B1

A new child Scope can be created using a special constructor: Scope::inherit(). It returns a new Scope object that acts as a child. A coroutine created within the child Scope can also be considered a child relative to the coroutines in the parent Scope.

An example:

use Async\Scope;
use Async\CancellationError;
 
function connectionChecker($socket, callable $cancelToken): void
{
    while (true) {
        if(feof($socket)) {
            $cancelToken("The connection was closed by user");
            return;
        }
 
        Async\delay(1000); // throw CancellationError if canceled
    }
}
 
function connectionLimiter(callable $cancelToken): void
{
   Async\delay(10000);
   $cancelToken("The request processing limit has been reached.");
}
 
function connectionHandler($socket): void
{
    // Note that a parent Scope can stop the execution of all coroutines
    // belonging to a child Scope at any moment.
    $scope = Scope::inherit();
 
    //
    // Passing ''$scope'' via ''use'' into a single coroutine is equivalent to the logic:
    // the lifetime of ''$scope'' equals the lifetime of the coroutine.
    // In this way, we create a coroutine-closure that acts as a Point of Responsibility.
    // This code is one example of how to implement Points of Responsibility.
    //
    $scope->spawn(function() use ($socket, $scope) {
 
        $limiterScope = Scope::inherit(); // child scope for connectionLimiter and connectionChecker
 
        // We do not provide direct access to the Scope object in other functions, because this is an antipattern!
        $cancelToken = fn(string $message) => $scope->cancel(new CancellationError($message));
 
        // Limiter coroutine
        $limiterScope->spawn(connectionLimiter(...), $cancelToken);
 
        // A separate coroutine checks that the socket is still active.
        $limiterScope->spawn(connectionChecker(...), $socket, $cancelToken);
 
        try {
            sendResponse($socket, dispatchRequest(parseRequest($socket)));
        } catch (\Exception $exception) {
            fwrite($socket, "HTTP/1.1 500 Internal Server Error\r\n\r\n");
        } finally {
            fclose($socket);
            // Explicitly cancel all coroutines in the child scope
            $scope->cancel();
        }
    });
}
 
function socketServer(): void
{
    // Main Server $scope
    $scope = new Scope();
 
    // Child coroutine that listens for a shutdown signal
    //
    // Note that we are passing ''$scope'' to another function!
    // This is acceptable here because the code is within a single visual block,
    // and the risk of an error due to oversight is minimal.
    $scope->spawn(function() use ($scope) {
        try {
            // Note: The ''signal'' function is not part of this RFC,
            // but it may be implemented in the standard library in the future.
            // This example shows how such a function could be used.
            // The ''signal'' function returns a trigger ''Awaitable''.
            await Async\signal(SIGINT);
        } finally {
            $scope->cancel(new CancellationError('Server shutdown'));
        }
    }
 
    try {
       // The main coroutine that listens for incoming connections
       // The server runs as long as this coroutine is running.
       await($scope->spawn(function() {
           while ($socket = stream_socket_accept($serverSocket, 0)) {
               connectionHandler($socket);
           });
       }));
    } catch (\Throwable $exception) {
        echo "Server error: ", $exception->getMessage(), "\n";
    } finally {
        echo "Server should be stopped...\n";
 
        // Graceful exit
        try {
            $scope->cancel();
            // Await for all coroutines to finish but not more than 5 seconds
            $scope->awaitAfterCancellation(cancellation: Async\timeout(5000));
            echo "Server stopped\n";
        } catch (\Throwable $exception) {
            // Force exit
            echo "Server error: ", $exception->getMessage(), "\n";
            throw $exception;
        }
    }
}

Let's examine how this example works.

1. socketServer creates a new Scope for coroutines that will handle all connections. 2. Each new connection is processed using connectionHandler() in a separate Scope,

 which is inherited from the main one.

3. connectionHandler creates a new Scope for the connectionLimiter and connectionChecker coroutines. 4. connectionHandler creates coroutine: connectionLimiter() to limit the processing time of the request. 5. connectionHandler creates coroutine, connectionChecker(), to monitor the connection's activity.

 As soon as the client disconnects, ''connectionChecker'' will cancel all coroutines related to the request.

6. If the main Scope is closed, all coroutines handling requests will also be canceled.

GLOBAL <- globalScope
│
├── socketListen (Scope) <- rootScope
│   │
│   ├── connectionHandler (Scope) <- request scope1
│   │   └── connectionLimiter (Coroutine) <- $limiterScope
│   │   └── connectionChecker (Coroutine) <- $limiterScope
│   │
│   ├── connectionHandler (Scope) <- request scope2
│   │   └── connectionLimiter (Coroutine) <- $limiterScope
│   │   └── connectionChecker (Coroutine) <- $limiterScope
│   │

The connectionHandler doesn't worry if the lifetimes of the connectionLimiter or connectionChecker coroutines exceed the lifetime of the main coroutine handling the request, because it is guaranteed to call $scope->cancel() when the main coroutine finishes.

$limiterScope is used to explicitly define a child-group of coroutines that should be cancelled when the request is completed. This approach minimizes errors.

On the other hand, if the server receives a shutdown signal, all child Scopes will be cancelled because the main Scope will be cancelled as well.

Note that the coroutine waiting on await Async\signal(SIGINT) will not remain hanging in memory if the server shuts down in another way, because $scope will be explicitly closed in the finally block.

The cancel method cancels all child coroutines and all child Scopes of the current Scope.:

use function Async\Scope\delay;
 
$scope = new Scope();
 
$scope->spawn(function() {
    spawn(function() {
        Async\delay(1000);
        echo "Task 1\n";
    });
 
    spawn(function() {
        Async\delay(2000);
        echo "Task 2\n";
    });
});
 
$scope->cancel();

Expected output:

Coroutine Scope has several resource cleanup strategies that can be triggered either explicitly, on demand, or implicitly when the Scope object loses its last reference.

There are three available strategies for Scope termination:

The main goal of all three methods is to terminate the execution of coroutines that belong to the Scope or its child Scopes. However, each method approaches this task slightly differently.

The disposeSafely method is used by default in the destructor of the Async\Scope class. Its key feature is transitioning coroutines into a zombie coroutine state. A zombie coroutine continues execution but is tracked by the system differently than regular coroutines. (See section: [Zombie coroutine policy](#zombie-coroutine-policy)).

A warning is issued when a zombie coroutine is detected.

use function Async\Scope\delay;
 
$scope = new Scope();
 
await($scope->spawn(function() {
    spawn(function() {
        Async\delay(1000);
        echo "Task 1\n";
    });
 
    spawn(function() {
        Async\delay(2000);
        echo "Task 2\n";
    });
 
    echo "Root task\n";
}));
 
$scope->disposeSafely();

Expected output:

Root task
Warning: Coroutine is zombie at ... in Scope disposed at ...
Warning: Coroutine is zombie at ... in Scope disposed at ...
Task 1
Task 2

The $scope variable is released immediately after the coroutine Root task completes execution, so the child coroutine Task 1 does not have time to execute before the disposeSafely method is called.

disposeSafely detects this and signals it with a warning but allows the coroutine to complete.

The Scope::dispose method differs from Scope::disposeSafely in that it does not leave zombie coroutines. It cancels all coroutines. When coroutines are detected as unfinished, a warning is issued.

Example:

use function Async\Scope\delay;
 
$scope = new Scope();
 
await($scope->spawn(function() {
    spawn(function() {
        Async\delay(1000);
        echo "Task 1\n";
    });
 
    spawn(function() {
        Async\delay(2000);
        echo "Task 2\n";
    });
 
    echo "Root task\n";
}));
 
$scope->dispose();

Expected output:

Warning: Coroutine is zombie at ... in Scope disposed at ...
Warning: Coroutine is zombie at ... in Scope disposed at ...
Warning: Coroutine is zombie at ... in Scope disposed at ...

The disposeAfterTimeout method is a delayed version of the disposeSafely method. The $timeout parameter must be greater than zero but less than 10 minutes.

use Async\Scope;
 
class Service
{
    private Scope $scope;
 
    public function __construct() {
        $this->scope = new Scope();
    }
 
    public function __destruct() {
        $this->scope->disposeAfterTimeout(5000);
    }
 
    public function run(): void {
        $this->scope->spawn(function() {
 
            spawn(function() {
                Async\delay(1000);
                echo "Task 2\n";
                Async\delay(5000);
                echo "Task 2 next line never executed\n";
            });
 
            echo "Task 1\n";
        });
    }
}
 
$service = new Service();
$service->run();
 
sleep(1);
unset($service);

Expected output:

Task 1
Warning: Coroutine is zombie at ... in Scope disposed at ...
Task 2

The dispose*() methods can be called multiple times, which is not considered an error.

If the Scope::cancel() method is called with a parameter after the Scope has already been cancelled, PHP will emit a warning indicating that the call will be ignored.

If a Scope has child Scopes, the coroutines in the child Scopes will be canceled or disposed first, followed by those in the parent — from the bottom up in the hierarchy. This approach increases the likelihood that resources will be released correctly. However, it does not guarantee this, since the exact order of coroutines in the execution queue cannot be determined with 100% certainty.

During the release of child Scopes, the same cleanup strategy is used that was applied to the parent Scope.

If the disposeSafely method is called, the child Scopes will also be released using the disposeSafely strategy. If the dispose method is used, the child Scopes will use the same method for cleanup.

The disposeAfterTimeout method will delay the execution of disposeSafely for the specified time.

When the cancel() or dispose() method is called, the Scope is marked as closed. Attempting to launch a coroutine with this Scope will result in a fatal exception.

$scope = new Scope();
 
$scope->spawn(function() {
    echo "Task 1\n";
});
 
$scope->cancel();
 
$scope->spawn(function() { // <- AsyncException: Coroutine scope is closed
    echo "Task 2\n";
});

Detecting erroneous situations when using coroutines is an important part of analyzing an application's reliability.

The following scenarios are considered potentially erroneous:

1. A coroutine belongs to a global scope and is not awaited by anyone (a **zombie coroutine**).
2. The root scope has been destroyed (its destructor was called), but no one awaited
 it or ensured that its resources were explicitly cleaned up (e.g., by calling ''$scope->cancel()'' or ''$scope->dispose()'').
3. Tasks were not cancelled using the ''cancel()'' method, but through a call to ''dispose()''.
 This indicates that the programmer did not intend to cancel the execution of the coroutine,
 yet it happened because the scope was destroyed.
4. An attempt to await a coroutine from within itself.
5. Awaiting ''$scope'' from within itself or from one of its child scopes.
6. Stuck tasks in the cancellation state.
7. Deadlocks caused by circular dependencies between coroutines.

PHP will respond to such situations by issuing warnings, including debug information about the involved coroutines. Developers are expected to write code in a way that avoids triggering these warnings.

An attempt to use the expression await($coroutine) from within the same coroutine throws an exception.

$coroutine = null;
$coroutine = spawn(function() use (&$coroutine) {
    await($coroutine); // <- AsyncException: A coroutine cannot await itself. Coroutine spawned at ...
});

Using the Scope::awaitCompletion() from a coroutine that belongs to the same $scope or to one of its child scopes will throw a fatal exception. This condition makes it impossible to perform the $globalScope->awaitCompletion call.

$scope = new Scope();
 
$scope->spawn(function() use ($scope) {
    $scope->awaitCompletion(Async\timeout(1000)); // <- AsyncException: Awaiting a scope from within itself or
                                                  // its child scope would cause a deadlock. Scope created at ...
});

The only way to create zombie coroutines is by using the spawn expression in the globalScope. However, if the initial code explicitly creates a scope and treats it as the application's entry point, the initializing code gains full control — because spawn <callable> will no longer be able to create a coroutine in globalScope, thus preventing the application from hanging beyond the entry point.

There’s still a way to use global variables and new Scope to launch a coroutine that runs unchecked:

$GLOBALS['my'] = new Scope();
$GLOBALS['my']->spawn(function() { ... });

But such code can't be considered an accidental mistake.

To avoid accidentally hanging coroutines whose lifetimes were not correctly limited, follow these rules:

• Use separate Scopes for different coroutines. This is the best practice,

as it allows explicitly defining lifetime dependencies between Scopes.

• Use Scope::dispose(). The dispose() method cancels coroutine execution and logs an error.
• Don’t mix semantically different coroutines within the same Scope.
• Avoid building hierarchies between Scopes with complex interdependencies.
• Do not use cyclic dependencies between Scopes.
• The principle of single point of responsibility and Scope ownership.

Do not pass the Scope object to different coroutine functions (unless the action happens in a closure).

Do not store ''Scope'' objects in different places.
Violating this rule can lead to manipulations with ''Scope'',
which may cause a deadlock or disrupt the application's logic.
* Child coroutines should not wait for their parents.
Child Scopes should not wait for their parents.

namespace ProcessPool;
 
use Async\Scope;
 
final class ProcessPool
{
    private Scope $watcherScope;
    private Scope $jobsScope;
    private Scope $pool;
 
    /**
     * List of pipes for each process.
     * @var array
     */
    private array $pipes = [];
    /**
     * Map of process descriptors: pid => bool
     * If the value is true, the process is free.
     * @var array
     */
    private array $descriptors = [];
 
    public function __construct(readonly public string $entryPoint, readonly public int $max, readonly public int $min)
    {
        // Define the coroutine scopes for the pool, watcher, and jobs
        $this->watcherScope = new Scope();
        $this->jobsScope = new Scope();
        $this->pool = new Scope();
    }
 
    public function __destruct()
    {
        $this->watcherScope->dispose();
        $this->pool->dispose();
        $this->jobsScope->dispose();
    }
 
    public function start(): void
    {
        $this->watcherScope->spawn($this->processWatcher(...));
 
        for ($i = 0; $i < $this->min; $i++) {
            $this->pool->spawn($this->startProcess(...));
        }
    }
 
    public function stop(): void
    {
        $this->watcherScope->cancel();
        $this->pool->cancel();
        $this->jobsScope->cancel();
    }
 
    private function processWatcher(): void
    {
        while (true) {
            try {
                $this->pool->awaitCompletion(Async\signal(SIGTERM));
            } catch (StopProcessException $exception)  {
                echo "Process was stopped with message: {$exception->getMessage()}\n";
 
                if($exception->getCode() !== 0 || count($this->descriptors) < $this->min) {
                    $this->pool->spawn($this->startProcess(...));
                }
            }
        }
    }
}

The example above demonstrates how splitting coroutines into Scopes helps manage their interaction and reduces the likelihood of errors.

Here, watcherScope monitors tasks in pool. When a process finishes, the watcher detects this event and, if necessary, starts a new process or not. The monitoring logic is completely separated from the process startup logic.

The lifetime of watcherScope matches that of pool, but not longer than the lifetime of the watcher itself.

The overall lifetime of all coroutines in the ProcessPool is determined by the lifetime of the ProcessPool object or by the moment the stop() method is explicitly called.

Coroutines whose lifetime extends beyond the boundaries of their parent Scope are handled according to a separate policy.

This policy aims to strike a balance between uncontrolled resource leaks and the need to abruptly terminate coroutines, which could lead to data integrity violations.

If there are no active coroutines left in the execution queue and no events to wait for, the application is considered complete.

Zombie coroutines differ from regular ones in that they are not counted as active. Once the application is considered finished, zombie coroutines are given a time limit within which they must complete execution. If this limit is exceeded, all zombie coroutines are canceled.

The delay time for handling zombie coroutines can be configured using a constant in the php.ini file: async.zombie_coroutine_timeout, which is set to two seconds by default.

If a coroutine is created within a user-defined Scope, the programmer can set a custom timeout for that specific Scope using the Scope::disposeAfterTimeout(int $ms) method.

Structured concurrency allows organizing coroutines into a group or hierarchy to manage their lifetime or exception handling.

The parent task is required to take responsibility for its child tasks and must not complete before the children have finished their execution.

To implement structured concurrency, it is recommended to use the CoroutineGroup class.

The following code implements this idea:

use Async\Scope;
 
function copyFile(string $sourceFile, string $targetFile): void
{
    $source = fopen($sourceFile, 'r');
    $target = fopen($targetFile, 'w');
 
    $buffer = null;
 
    try {
        // Child scope
        $tasks = new \Async\CoroutineGroup(Scope::inherit());
 
        // Read data from the source file
        $tasks->spawn(function() use (&$buffer, $source) {
            while (!feof($source)) {
                if ($buffer === null) {
                    $chunk = fread($source, 1024);
                    $buffer = $chunk !== false && $chunk !== '' ? $chunk : null;
                }
 
                suspend();
            }
 
            $buffer = '';
        });
 
        // Write data to the target file
        $tasks->spawn(function() use (&$buffer, $target) {
            while (true) {
                if (is_string($buffer)) {
                    if ($buffer === '') {
                        break; // End of a file
                    }
 
                    fwrite($target, $buffer);
                    $buffer = null;
                }
 
                suspend();
            }
 
            echo "Copy complete.\n";
        });
 
        await($tasks);
    } finally {
        fclose($source);
        fclose($target);
    }
}
 
$copyTasks = new \Async\Scope();
 
$copyTasks->spawn(copyFile(...), 'source.txt', 'target.txt');
$copyTasks->spawn(copyFile(...), 'source2.txt', 'target2.txt');
 
$copyTasks->awaitCompletion(Async\signal(SIGTERM));

The example creates two task groups: a parent and a child. The parent task group handles the copy operations directly, while the child tasks perform file reading and writing. File descriptors will not be closed until all child copy tasks have completed. The main code will not finish until all copy operations are completed.

Async utilities are functions that combine multiple awaitable objects into complex execution patterns. The API provides both error-propagating and error-collecting variants for different use cases.

Error-Collecting Functions (Default) (awaitAll, awaitAny, awaitAnyOf, awaitFirstSuccess): * Continue execution despite exceptions * Return results and errors separately as [results, errors] * Allow partial success scenarios * Safe by default - no work is lost

Error-Propagating Functions (Fail-Fast) (awaitAllOrFail, awaitAnyOrFail, awaitAnyOfOrFail): * Stop execution on first exception * Throw the exception immediately * Cancel remaining coroutines * Use when you need strict error handling

Controls whether the result array maintains the same key order as the input iterable.

* true: Results array has same keys/indices as input array * false: Results array is re-indexed with sequential numeric keys (0, 1, 2...)

// With preserveKeyOrder = true (default)
[$results, $errors] = awaitAll([
    'user' => spawn('fetchUser'),
    'settings' => spawn('fetchSettings')
]);
// $results = ['user' => userData, 'settings' => settingsData]
 
// With preserveKeyOrder = false  
[$results, $errors] = awaitAll([
    'user' => spawn('fetchUser'),
    'settings' => spawn('fetchSettings')
], preserveKeyOrder: false);
// $results = [0 => userData, 1 => settingsData]

Controls how failed tasks are represented in the results array (only for error-collecting functions).

* false: Failed tasks are omitted from results array * true: Failed tasks are represented as null in results array

// With fillNull = false (default)
[$results, $errors] = awaitAll([
    spawn('successfulTask'),  // succeeds
    spawn('failingTask'),     // fails  
    spawn('anotherSuccess')   // succeeds
]);
// $results = [0 => successResult, 2 => anotherResult]
// $errors = [1 => Exception]
 
// With fillNull = true
[$results, $errors] = awaitAll([
    spawn('successfulTask'),  // succeeds
    spawn('failingTask'),     // fails
    spawn('anotherSuccess')   // succeeds  
], fillNull: true);
// $results = [0 => successResult, 1 => null, 2 => anotherResult]
// $errors = [1 => Exception]

[$results, $errors] = awaitAll([
    spawn('fetchUserData'),
    spawn('fetchUserSettings'),
    spawn('fetchUserPreferences')
]);
 
// $results = [userData, userSettings, userPreferences] or null for failed
// $errors = [index => Exception] for any failures
// Order matches input order
// All tasks complete even if some fail

$results = awaitAllOrFail([
    spawn('fetchUserData'),
    spawn('fetchUserSettings'),
    spawn('fetchUserPreferences')
]);
 
// $results = [userData, userSettings, userPreferences]
// Throws exception and cancels all on first failure

// Returns first successful result, continues until success
$data = awaitAny([
    spawn('fetchFromCache'),      // might fail
    spawn('fetchFromDatabase'),   // might fail
    spawn('fetchFromAPI')         // fallback
]);
// Returns first successful result, collects all errors

// Returns result from fastest completion (success or failure)
$data = awaitAnyOrFail([
    spawn('fetchFromCache'),
    spawn('fetchFromDatabase'), 
    spawn('fetchFromAPI')
]);
// Throws exception if first completed task fails

[$result, $errors] = awaitFirstSuccess([
    spawn('callUnreliableAPI1'),
    spawn('callUnreliableAPI2'), 
    spawn('callUnreliableAPI3')
]);
 
if ($result !== null) {
    echo "Got result: $result\n";
} else {
    echo "All calls failed. Errors: " . count($errors) . "\n";
}

[$results, $errors] = awaitAll([
    spawn('processFile', 'file1.txt'),
    spawn('processFile', 'file2.txt'),
    spawn('processFile', 'corrupted.txt') // might fail
], fillNull: true);
 
// $results = ["result1", "result2", null]
// $errors = [2 => Exception("corrupted file")]

// Wait for first 3 downloads to complete (including failures)
[$results, $errors] = awaitAnyOf(3, [
    spawn('downloadFile', 'file1.zip'),
    spawn('downloadFile', 'file2.zip'), 
    spawn('downloadFile', 'file3.zip'),
    spawn('downloadFile', 'file4.zip'),
    spawn('downloadFile', 'file5.zip')
]);
 
// $results = [1 => "file2.zip", 0 => "file1.zip", 4 => "file5.zip"]
// $errors = [] (if all successful) or [index => Exception]
// Keys preserve original array indices

// Wait for first 3 downloads to complete, fail fast on errors
$completedDownloads = awaitAnyOfOrFail(3, [
    spawn('downloadFile', 'file1.zip'),
    spawn('downloadFile', 'file2.zip'), 
    spawn('downloadFile', 'file3.zip'),
    spawn('downloadFile', 'file4.zip'),
    spawn('downloadFile', 'file5.zip')
]);
 
// Returns array: [1 => "file2.zip", 0 => "file1.zip", 4 => "file5.zip"] 
// Throws exception if any of the first 3 downloads fail

All Utilities support cancellation through the optional $cancellation parameter:

try {
    $results = awaitAll($tasks, Async\timeout(30000)); // 30 second timeout
} catch (Async\AwaitCancelledException $e) {
    echo "Operation timed out\n";
}

Retry with Multiple Strategies:

function fetchWithRetry(string $url): string
{
    for ($attempt = 1; $attempt <= 3; $attempt++) {
        [$result, $errors] = awaitFirstSuccess([
            spawn('fetchFromCDN', $url),
            spawn('fetchFromOrigin', $url),
            spawn('fetchFromBackup', $url)
        ]);
 
        if ($result !== null) {
            return $result;
        }
 
        echo "Attempt $attempt failed, retrying...\n";
        Async\delay(1000 * $attempt); // exponential backoff
    }
 
    throw new Exception("All retry attempts failed");
}

Batch Processing with Concurrency Control:

function processBatch(array $items, int $batchSize = 10): array
{
    $allResults = [];
 
    for ($i = 0; $i < count($items); $i += $batchSize) {
        $batch = array_slice($items, $i, $batchSize);
        $tasks = array_map(fn($item) => spawn('processItem', $item), $batch);
 
        $batchResults = awaitAll($tasks);
        $allResults = array_merge($allResults, $batchResults);
    }
 
    return $allResults;
}

The standard async library includes two functions similar to usleep(): * Async\delay(int $ms): void * Async\timeout(int $ms): Awaitable

The delay function suspends the execution of a coroutine for the specified number of milliseconds. Unlike usleep, the delay function will throw a cancellation exception if the coroutine is cancelled.

The timeout function is similar to delay, but it returns an Awaitable object:

use function Async\timeout;
use function Async\delay;
 
try {
    Async\delay(1000); // suspends the coroutine for 1 second
    // Try to fetch data from the URL within 1 second
    echo await(spawn('file_get_content', 'https://php.net/'), Async\timeout(1000));
} catch (\Async\AwaitCancelledException) {
    echo "Operation was cancelled by timeout\n";
} catch (\Async\CancellationError) {
    echo "Operation was cancelled by user\n";
}

An uncaught exception in a coroutine follows this flow:

1. If the coroutine is awaited using the await keyword,

 the exception is propagated to the awaiting points.
 If multiple points are awaiting, each will receive the same exception
 (**Each await point will receive the exact same exception object, not cloned**).

2. The exception is passed to the Scope. 3. If the Scope has an exception handler defined, it will be invoked. 4. If the Scope does not have an exception handler, the cancel() method is called,

 canceling all coroutines in this scope, including all child scopes.

5. If the Scope has responsibility points, i.e., the construction Scope::awaitCompletion,

 all responsibility points receive the exception.

6. Otherwise, the exception is passed to the parent scope if it is defined. 7. If there is no parent scope, the exception falls into globalScope,

 where the same rules apply as for a regular scope.

Example:

use Async\Scope;
 
$scope = new Scope();
 
$scope->spawn(function() {
    throw new Exception("Task 1");
});
 
$exception1 = null;
$exception2 = null;
 
$scope2 = new Scope();
 
$scope2->spawn(function() use ($scope, &$exception1) {
    try {
        $scope->awaitCompletion(Async\signal(SIGTERM));
    } catch (Exception $e) {
        $exception1 = $e;
        echo "Caught exception1: {$e->getMessage()}\n";
    }
});
 
$scope2->spawn(function() use ($scope, &$exception2) {
    try {
        $scope->awaitCompletion(Async\signal(SIGTERM));
    } catch (Exception $e) {
        $exception2 = $e;
        echo "Caught exception2: {$e->getMessage()}\n";
    }
});
 
$scope2->awaitCompletion(Async\signal(SIGTERM));
 
echo $exception1 === $exception2 ? "The same exception\n" : "Different exceptions\n";

If an exception reaches globalScope and is not handled in any way, it triggers Graceful Shutdown Mode, which will terminate the entire application.

The Scope class allows defining an exception handler that can prevent exception propagation.

For this purpose, two methods are used:

1. setExceptionHandler – triggers for any exceptions thrown within this Scope.
2. setChildScopeExceptionHandler – triggers for exceptions from child Scopes.

The methods setExceptionHandler and setChildScopeExceptionHandler cannot be used with the globalScope.
If an attempt is made to do so, an exception will be thrown.

Example:

$scope = new Scope();
$scope->setExceptionHandler(function (Async\Scope $scope, Async\Coroutine $coroutine, Throwable $e) {
    echo "Caught exception: {$e->getMessage()}\n in coroutine: {$coroutine->getSpawnLocation()}\n";
});
 
$scope->spawn(function() {
    throw new Exception("Task 1");
});
 
$scope->awaitCompletion(Async\signal(SIGTERM));

Using these handlers, you can implement the Supervisor pattern, i.e., a Scope that will not be canceled when an exception occurs in coroutines.

If the setExceptionHandler or setChildScopeExceptionHandler handlers throw an exception,
it will be propagated to the parent Scope or the global Scope.

The setChildScopeExceptionHandler method allows handling exceptions only from child Scopes, which can be useful for implementing an algorithm where the main Scope runs core tasks, while child Scopes handle additional ones.

For example:

use Async\Scope;
use Async\Coroutine;
 
final class Service
{
    private Scope $scope;
 
    public function __construct()
    {
        $this->scope = new Scope();
 
        $this->scope->setChildScopeExceptionHandler(
        static function (Scope $scope, Coroutine $coroutine, \Throwable $exception): void {
            echo "Occurred an exception: {$exception->getMessage()} in Coroutine {$coroutine->getSpawnLocation()}\n";
        });
    }
 
    public function start(): void
    {
        $this->scope->spawn($this->run(...));
    }
 
    public function stop(): void
    {
        $this->scope->cancel();
    }
 
    private function run(): void
    {
        while (($socket = $this->service->receive()) !== null) {
 
            $scope = Scope::inherit($this->scope);
 
            // supervisor pattern
            ($scope->spawn($this->handleRequest(...), $socket)->onFinally(
                static function () use ($scope) {
                    $scope->disposeSafely();
                }
            );
        }
    }
}

$this->scope listens for new connections on the server socket. Canceling $this->scope means shutting down the entire service.

Each new connection is handled in a separate Scope, which is inherited from $this->scope. If an exception occurs in a coroutine created within a child Scope, it will be passed to the setChildScopeExceptionHandler handler and will not affect the operation of the service as a whole.

Please see also [CoroutineGroup scope exception handling](#CoroutineGroup-scope-exception-handling) and [CoroutineGroup error handling](#CoroutineGroup-error-handling) sections.

A responsibility point is code that explicitly waits for the completion of a coroutine or a Scope:

$scope = new Scope();
 
$scope->spawn(function() {
  throw new Exception("Task 1");
});
 
try {
    $scope->awaitCompletion(Async\signal(SIGTERM));
} catch (\Throwable $e) {
     echo "Caught exception: {$e->getMessage()}\n";
}

The Scope class provides a method for handling exceptions:

$scope = new Scope();
 
$scope->spawn(function() {
    throw new Exception("Task 1");
});
 
$scope->setExceptionHandler(function (Exception $e) {
    echo "Caught exception: {$e->getMessage()}\n";
});
 
$scope->awaitCompletion(Async\signal(SIGTERM));

An exception handler has the right to suppress the exception. However, if the exception handler throws another exception, the exception propagation algorithm will continue.

The onFinally method allows defining a callback function that will be invoked when a coroutine or scope completes. This method can be considered a direct analog of defer in Go.

⚠️ Important: All onFinally handlers are executed concurrently in separate coroutines.
This ensures that slow handlers do not block the completion of other handlers or the main execution flow.

For Scope, the callback receives the completed scope as a parameter:

$scope = new Scope();
 
$scope->spawn(function() {
    throw new Exception("Task 1");
});
 
$scope->onFinally(function (Scope $completedScope) {
    echo "Scope " . spl_object_id($completedScope) . " completed\n";
});
 
$scope->awaitCompletion(Async\signal(SIGTERM));

For Coroutine, the callback receives the completed coroutine as a parameter:

function task(): void
{
    throw new Exception("Task 1");
}
 
$coroutine = spawn('task');
 
$coroutine->onFinally(function (Coroutine $completedCoroutine) {
    echo "Coroutine " . spl_object_id($completedCoroutine) . " completed\n";
});

The onFinally semantics are most commonly used to release resources, serving as a shorter alternative to try-finally blocks:

function task(): void
{
    $file = fopen('file.txt', 'r');
    onFinally(fn() => fclose($file));
 
    throw new Exception("Task 1");
}
 
spawn('task');

The cancellation operation is available for coroutines and scopes using the cancel() method:

function task(): void {}
 
$coroutine = spawn(task(...));
 
// cancel the coroutine
$coroutine->cancel(new Async\CancellationError('Task was cancelled'));

The cancellation operation is implemented as follows:

1. If a coroutine has not started, it will never start. 2. If a coroutine is suspended, its execution will resume with an exception. 3. If a coroutine has already completed, nothing happens.

The CancellationError, if unhandled within a coroutine, is automatically suppressed after the coroutine completes.

⚠️ Warning: You should not attempt to suppress CancellationError exception,
as it may cause application malfunctions.

$scope = new Scope();
 
$scope->spawn(function() {
    sleep(1);
    echo "Task 1\n";
});
 
$scope->cancel(new Async\CancellationError('Task was cancelled'));

Canceling a Scope triggers the cancellation of all coroutines within that Scope and all child Scopes in hierarchical order.

Note: CancellationError can be extended by the user
to add metadata that can be used for debugging purposes.

In the context of coroutines, it is not recommended to use catch \Throwable or catch CancellationError.

Since CancellationError does not extend the \Exception class, using catch \Exception is a safe way to handle exceptions, and the finally block is the recommended way to execute finalizing code.

try {
    $coroutine = spawn(function() {
        sleep(1);
        throw new \Exception("Task 1");
    });
 
    spawn(function() use ($coroutine) {
        $coroutine->cancel();
    });
 
    try {
        await($coroutine);
    } catch (\Exception $exception) {
        // recommended way to handle exceptions
        echo "Caught exception: {$exception->getMessage()}\n";
    }
} finally {
    echo "The end\n";
}

Expected output:

The end

try {
    $coroutine = spawn(function() {
        sleep(1);
        throw new \Exception("Task 1");
    });
 
    spawn(function() use ($coroutine) {
        $coroutine->cancel();
    });
 
    try {
        await($coroutine);
    } catch (Async\CancellationError $exception) {
        // not recommended way to handle exceptions
        echo "Caught CancellationError\n";
        throw $exception;
    }
} finally {
    echo "The end\n";
}

Expected output:

Caught CancellationError
The end

The CancellationError affects PHP standard library functions differently. If it is thrown inside one of these functions that previously did not throw exceptions, the PHP function will terminate with an error.

In other words, the cancel() mechanism does not alter the existing function contract. PHP standard library functions behave as if the operation had failed.

Additionally, the CancellationError will not appear in get_last_error(), but it may trigger an E_WARNING to maintain compatibility with expected behavior for functions like fwrite (if such behavior is specified in the documentation).

Sometimes it's necessary to execute a critical section of code that must not be cancelled via CancellationError.

For example, this could be a sequence of write operations or a transaction.

For this purpose, the Async\protect function is used, which allows executing a closure in a non-cancellable (silent) mode.

function task(): void
{
    Async\protect(fn() => fwrite($file, "Critical data\n"));
}
 
spawn(task(...));

If a CancellationError was sent to a coroutine during protect(), the exception will be thrown immediately after the execution of protect() completes.

The use of loops or unsafe operations inside a critical section can be checked by static analyzers.

This RFC intentionally does not define rules for tracking the execution time of cancelled coroutines. The reason is that cancellation operations may be long-running—for example, rollback strategies—and may require blocking the function being cancelled.

Intentionally stopping coroutines that are in the cancellation state is a dangerous operation that can lead to data loss. To avoid overcomplicating this RFC, it is proposed to delegate the responsibility for such logic to the Scheduler implementation.

The exit/die keywords called within a coroutine result in the immediate termination of the application. Unlike the cancel() operation, they do not allow for proper resource cleanup.

When an unhandled exception occurs in a Coroutine the Graceful Shutdown mode is initiated. Its goal is to safely terminate the application.

Graceful Shutdown cancels all coroutines in globalScope, then continues execution without restrictions, allowing the application to shut down naturally. Graceful Shutdown does not prevent the creation of new coroutines or close connection descriptors. However, if another unhandled exception is thrown during the Graceful Shutdown process, the second phase is triggered.

Second Phase of Graceful Shutdown - All Event Loop descriptors are closed. - All timers are destroyed. - Any remaining coroutines that were not yet canceled will be forcibly canceled.

The further shutdown logic may depend on the specific implementation of the Scheduler component, which can be an external system and is beyond the scope of this RFC.

The Graceful Shutdown mode can also be triggered using the function:

Async\gracefulShutdown(?CancellationError $CancellationError = null): void {}

from anywhere in the application.

A situation may arise where there are no active Coroutines in the execution queue and no active handlers in the event loop. This condition is called a Deadlock, and it represents a serious logical error.

When a Deadlock is detected, the application enters Graceful Shutdown mode and generates warnings containing information about which Coroutines are in a waiting state and the exact lines of code where they were suspended.

The Coroutine class implements methods for inspecting the state of a coroutine.

The Coroutine::getAwaitingInfo() method returns an array with debugging information about what the coroutine is waiting for, if it is in a waiting state.

The format of this array depends on the implementation of the Scheduler and the Reactor.

The Async\Scope::getChildScopes() method returns an array of all child scopes of the current scope.

The method Async\Scope::getCoroutines() returns a list of coroutines that are registered within the specified Scope.

The Async\getCoroutines() method returns an array of all coroutines in the application.

• [Async functions](https://github.com/EdmondDantes/php-true-async-rfc/tree/main/examples/Async/Async.php)
• [Coroutine](https://github.com/EdmondDantes/php-true-async-rfc/tree/main/examples/Async/Coroutine.php)
• [Coroutine Context](https://github.com/EdmondDantes/php-true-async-rfc/tree/main/examples/Async/Context.php)
• [Coroutine Scope](https://github.com/EdmondDantes/php-true-async-rfc/tree/main/examples/Async/Scope.php)

Simultaneous use of the True Async API and the Fiber API is not possible.

1. If new Fiber() is called first, the Async\spawn function will fail with an error.
2. If Async\spawn is called first, any attempt to create a Fiber will result in an error.

PHP 8.6+

The True Async module activates the reactor within the context of php_request_startup\php_request_shutdown() request processing. Therefore, using concurrency is reasonable only for long-life scenarios implemented via CLI.

It is expected that True Async will enable the integration of built-in web servers into PHP, which will be embedded into the reactor’s event loop.

No changes are expected in existing extensions.

Does not affect.

No new constants are introduced.

• async.zombie_coroutine_timeout - default 5 seconds

None.

• Fiber API.

This RFC assumes the subsequent development of additional RFCs:

* Async\Context RFC - Coroutine and Scope Context Management * RFC for Non-Blocking Versions of PHP Built-in Functions. The Socket/Curl extensions as well. * RFC for Special Async Syntax * RFC Context Manager (like in Python) * Equivalent of Go's defer expression RFC. * Special try cancellation block RFC. * An RFC for a set of standard primitives, such as Future, Channel, etc. * And possibly others...

This RFC provides for the subsequent expansion of functionality to achieve a complete toolkit for working with concurrent logic. It proposes development in areas:

• Support for Pipe
• Development of new and revision of existing extensions
• Refactoring of input-output code to improve performance and better integration with the Event Loop
• Functions for collecting metrics

The Future->map()->catch()->finally() call chain is rightly criticized for excessive complexity and difficulty of comprehension. Pipe (not UNIX-like-pipe) can solve this problem and create a more intuitive and understandable interface for describing sequences of asynchronous function calls.

Input-output modules such as PHP Streams can be redesigned with asynchronous capabilities in mind and better optimized for operation in this environment.

It would also be appropriate to add support for pipe in such a way that it can be used regardless of the operating system using fopen() functions. This would make the API more consistent.

Yes or no vote. 2/3 required to pass.

* Current implementation: https://github.com/true-async

Links to external references, discussions or RFCs

• First Discussion - https://externals.io/message/126402
• Second Discussion - https://externals.io/message/126537
• Third Discussion - https://externals.io/message/127120
• Fourth Discussion -

• TrueAsync API RFC - https://github.com/true-async/php-true-async-rfc/blob/main/true-async-api-rfc.md

Additional links:

• Comparison of concurrency models in programming languages
• Cooperative cancellation
• Understanding Concurrency Bugs in Real-World Programs with Kotlin Coroutines
• Understanding Real-World Concurrency Bugs in Go
• Static Analysis for Asynchronous JavaScript Programs

The following can be considered as competing solutions to the current implementation:

• Swoole (https://github.com/swoole/swoole-src) – a C++ library that implements a full feature set for concurrent programming. The advantage and disadvantage of Swoole is that it is a standalone solution that does not directly affect the language itself.

• The Swow (https://github.com/swow/) project is a C library that provides a good lightweight API while not affecting the language itself and not requiring changes to PHP.

• Examples of code: https://github.com/EdmondDantes/php-true-async-rfc/tree/main/examples

Keep this updated with features that were discussed on the mail lists.