Skip to content

true-async-api-rfc.md

Latest commit

 

History

History
93 lines (69 loc) · 4.92 KB

true-async-api-rfc.md

File metadata and controls

93 lines (69 loc) · 4.92 KB

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.5 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: Since the garbage collector calls destructors during the collection cycle, and a destructor in PHP userland may trigger a context switch, the garbage collector must be adapted to 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 available 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 cycle destruction.

  4. System-Level Operations: Core functions like network I/O, file operations, and process management need async variants.

Specification

API Architecture

The TrueAsync engine API defines a pluggable interface that enables different async backends to be registered by extensions while maintaining implementation flexibility. The core provides standardized async primitives without mandating specific implementations.

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 for signaling coroutine cancellation. Positioned as a root exception (not extending Exception) to ensure generic catch blocks don't accidentally intercept cancellation signals. Defined in core because fundamental engine functions assume all throwable types are known at startup.

Impact on Core

The API maintains separation between the Zend Engine and specific async implementations. Extensions implement async features using their preferred libraries (libuv, etc.) and register them during initialization. The engine interacts only through standardized interfaces, keeping implementation details isolated.

Backward Compatibility

Full backward compatibility is maintained:

  • The API is always available and does not change PHP’s behavior if the extension is not activated and not used.
  • No new special functions are being added to PHP
  • Existing extensions remain unaffected unless they opt-in to async functionality
  • CancellationException is a new root exception, not extending Exception, ensuring it does not interfere with existing code.

Proposed PHP Version(s)

PHP 8.5

It is proposed to approve the principles of this RFC for the next PHP version, and to consider the PHP changes as separate PRs, the order of which will be determined by agreement.

References