rfc:true_async_engine_api

TrueAsync engine API RFC

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:

  1. 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.
  2. Universal Access: Core functions and extensions can always reference its symbols, regardless of whether a backend is installed.
  3. Garbage Collection Integration: The garbage collector uses async primitives to run cycle collection in dedicated coroutines, preventing user code from being blocked during destruction.
  4. 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

rfc/true_async_engine_api.txt · Last modified: by edmond

Page Tools



Table of Contents