====== TrueAsync engine API RFC ======

  * **Version:** 1.0  
  * **Date:** 2025‑07‑15  
  * **Author:** Edmond [HT], edmondifthen@proton.me  
  * **Status:** Under discussion  
  * **First Published at:** 2025‑07‑15  
  * **Git:** [[https://github.com/true-async|https://github.com/true-async]]  
  * **Related RFC:** [[https://wiki.php.net/rfc/true_async|https://wiki.php.net/rfc/true_async]]
  * **PR:** [[https://github.com/php/php-src/pull/19142]]

===== Introduction =====

The **TrueAsync engine API** introduces a pluggable framework for asynchronous programming in %%PHP%%.  
It allows extensions to register their own %%scheduler%%, %%reactor%% and %%thread pool%% implementations while keeping the %%Zend Engine%% independent of any particular event‑loop library.

The primary goal is to separate the core %%PHP%% functions from any specific asynchronous backend so that alternative implementations can be swapped in without modifying the engine.

This is effectively the **first step** toward bringing userland async capabilities to %%PHP%%, which will require a separate %%RFC%% aimed at %%PHP%% 8.6 (PHP 9.0) or higher.

===== Motivation =====

%%PHP%% currently lacks a unified asynchronous interface, creating significant challenges for the ecosystem:

  * **Fragmented Async Ecosystem:** Each async library (%%ReactPHP%%, %%Swoole%%, %%Amp%%, etc.) implements its own async primitives, leading to incompatible ecosystems that cannot interoperate.  
  * **Core System Limitations:** Many core %%PHP%% functions—network I/O, file operations, database connections—are inherently blocking and cannot be made async without core‑level modifications.  
  * **Garbage Collection Issues:** Because the garbage collector invokes destructors during collection, and a destructor in userland may trigger a context switch, the collector itself must support coroutines.

The %%TrueAsync engine API%% addresses these problems by providing standardized async primitives in the core. The %%API%% is part of the %%Zend Engine%% for the following reasons:

  - **Early Initialization:** As a core module it is available before extension initialization, enabling %%scheduler%% and %%reactor%% to cooperate correctly. Critical async infrastructure (like coroutine‑switch hooks) must be ready during the earliest stages of the %%PHP%% lifecycle.  
  - **Universal Access:** Core functions and extensions can always reference its symbols, regardless of whether a backend is installed.  
  - **Garbage Collection Integration:** The garbage collector uses async primitives to run cycle collection in dedicated coroutines, preventing user code from being blocked during destruction.  
  - **System‑Level Operations:** Core functions such as network I/O, file operations, and process management need async variants.

===== Specification =====

==== API Architecture ====

The %%TrueAsync engine API%% defines a pluggable interface that lets extensions register different async backends while the core supplies standardized primitives.

**Key Components**

  * **Events:** Low‑level representation of sockets, timers and other readiness sources  
  * **Coroutines:** Stackful tasks  
  * **Scopes:** Hierarchical lifetime management enabling grouped cancellation  
  * **Wakers:** Event‑completion handlers that resume suspended coroutines  

==== CancellationException ====

A new root exception class used to signal coroutine cancellation.  
It does **not** extend **Exception**, ensuring generic catch blocks do not intercept cancellation signals.  
It lives in core so that fundamental engine code knows all throwable types at startup.

===== Impact on Core =====

The %%API%% keeps the %%Zend Engine%% decoupled from specific async implementations.  
Extensions implement async features with their preferred libraries (e.g. %%libuv%%) and register them at startup; the engine communicates only through the standardized interface.

===== Backward Compatibility =====

  * The %%API%% is always present but inert unless an async extension activates it.  
  * No existing core behavior changes when the %%API%% is unused.  
  * Existing extensions remain unaffected unless they opt‑in to async functions.  
  * **CancellationException** is a new root throwable that does not interfere with current code.

===== Proposed PHP Version(s) =====

Target: %%PHP%% 8.5.  
Approve the principles in this %%RFC%% for that release; individual changes will be submitted as separate pull requests in an agreed order.

===== PRs =====

* [[https://github.com/php/php-src/pull/19142]]

===== References =====

  * Current diff: [[https://github.com/php/php-src/compare/master...true-async:php-src:true-async-api-stable|compare master…true-async-api-stable]]  
  * Zend Async API implementation files: [[https://github.com/true-async/php-src/tree/true-async-api|php-src/true-async-api]]  
  * General changes to PHP functions + Async API: [[https://github.com/true-async/php-src/tree/true-async|php-src/true-async]]  
  * Extension implementing the API: [[https://github.com/true-async/php-async|php-async]]  
  * Additional documentation: [[https://github.com/true-async/php-src/blob/true-async-api/docs/source/true_async_api/coroutines.rst|coroutines.rst]]