TrueAsync + Fiber

TrueAsync 0.5.0 + Async ABI 0.8.0

In this release, the main new feature is Fiber support for the new RFC.

Integration with FrankenPHP + TrueAsync has been completed.

See details here: https://github.com/true-async/frankenphp/tree/true-async

Added

• Fiber Support: Full integration of PHP Fibers with TrueAsync coroutine system
  • Fiber::suspend() and Fiber::resume() work in async scheduler context
  • Fiber::getCoroutine() method to access fiber's coroutine
  • Fiber status methods (isStarted, isSuspended, isRunning, isTerminated)
  • Support for nested fibers and fiber-coroutine interactions
  • Comprehensive test coverage for all fiber scenarios
• TrueAsync API: Added ZEND_ASYNC_SCHEDULER_LAUNCH() macro for scheduler initialization
• TrueAsync API: Updated to version 0.8.0 with fiber support
• TrueAsync API: Added customizable scheduler heartbeat handler mechanism with zend_async_set_heartbeat_handler() API

Fixed

• Critical GC Bug: Fixed garbage collection crash during coroutine cancellation when exception occurs in main coroutine while GC is running
• Fixed double free in zend_fiber_object_destroy()
• Fixed stream_select() for timeout == NULL case in async context
• Fixed fiber memory leaks and improved GC logic

Changed

• Deadlock Detection: Replaced warnings with structured exception handling
  • Deadlock detection now throws Async\DeadlockError exception instead of multiple warnings
  • Breaking Change: Applications relying on deadlock warnings
    will need to be updated to catch Async\DeadlockError exceptions
• Breaking Change: PHP Coding Standards Compliance - Function names updated to follow official PHP naming conventions:
  • spawnWith() → spawn_with()
  • awaitAnyOrFail() → await_any_or_fail()
  • awaitFirstSuccess() → await_first_success()
  • awaitAllOrFail() → await_all_or_fail()
  • awaitAll() → await_all()
  • awaitAnyOfOrFail() → await_any_of_or_fail()
  • awaitAnyOf() → await_any_of()
  • currentContext() → current_context()
  • coroutineContext() → coroutine_context()
  • currentCoroutine() → current_coroutine()
  • rootContext() → root_context()
  • getCoroutines() → get_coroutines()
  • gracefulShutdown() → graceful_shutdown()
  • Rationale: Compliance with PHP Coding Standards - functions must use lowercase with underscores

v0.4.0 - Performance Improvements

PHP Async Extension v0.4.0

This release focuses on three core performance optimizations that significantly improve async operation efficiency.

Core Performance Improvements

1. Minimizing Kernel Function Calls

• Reduced unnecessary LibUV calls in scheduler tick processing
• Optimized network_async_accept_incoming - attempt accept() before waiting
• Separate queue for resumed coroutines to improve scheduler stability
• Replaced expensive EG(exception) checks with direct bool returns in TrueAsync API

2. Event Descriptor Caching

• Introduced zend_async_poll_proxy_t structure for efficient file descriptor management
• Event handler caching for sockets - avoid EventLoop recreation overhead
• Poll proxy event aggregation and improved lifecycle management
• Automatic waker event cleanup when coroutines resume (ZEND_ASYNC_WAKER_CLEAN_EVENTS)

3. Memory Allocation Optimization

• Fixed ref_count logic in zend_async_event_callback_t structures
• Optimized waker trigger structures with improved memory layout
• Enhanced memory allocation patterns for async structures
• Better resource cleanup and lifecycle management

Additional Features

• Full async UDP socket operations integrated with TrueAsync API
• Implemented SSL support for socket streams

Bug Fixes

• Fixed await iterator logic for awaitXXX functions
• Resolved process waiting logic issues on UNIX-like systems
• Fixed compilation errors in curl_async.c
• Improved iterator state management in concurrent environments

Requirements

• LibUV: >= 1.45.0 (upgraded from 1.44.0 to fix critical timer bugs)
• PHP: 8.5+
• Platforms: Linux, macOS, Windows, FreeBSD, etc.

API Changes

• TrueAsync API functions now return bool instead of void for better performance
• Automatic cleanup of waker events when coroutines resume

For detailed technical changes, see CHANGELOG.md.

v0.3.0 - EXP Release

Stabilization release - 2025-07-16

Added

• Docker support with multi-stage build (Ubuntu 24.04, libuv 1.49, curl 8.10)
• PDO MySQL and MySQLi async support
• TrueAsync API Extensions: Enhanced async API with new object creation and coroutine grouping capabilities
  • Added ZEND_ASYNC_NEW_GROUP() API for creating CoroutineGroup objects for managing multiple coroutines
  • Added ZEND_ASYNC_NEW_FUTURE_OBJ() and ZEND_ASYNC_NEW_CHANNEL_OBJ() APIs for creating Zend objects from async primitives
  • Extended zend_async_task_t structure with run method for thread pool task execution
  • Enhanced zend_async_scheduler_register() function with new API function pointers
• Multiple Callbacks Per Event Support: Complete redesign of waker trigger system to support multiple callbacks on a single event
  • Modified zend_async_waker_trigger_s structure to use flexible array member with dynamic capacity
  • Added waker_trigger_create() and waker_trigger_add_callback() helper functions for efficient memory management
  • Implemented single-block memory allocation for better performance (trigger + callback array in one allocation)
  • Default capacity starts at 1 and doubles as needed (1 → 2 → 4 → 8...)
  • Fixed coroutine_event_callback_dispose() to remove only specific callbacks instead of entire events
  • Breaking Change: Events now persist until all associated callbacks are removed
• Bailout Tests: Added 15 tests covering memory exhaustion and stack overflow scenarios in async operations
• Garbage Collection Support: Implemented comprehensive GC handlers for async objects
  • Added async_coroutine_object_gc() function to track all ZVALs in coroutine structures
  • Added async_scope_object_gc() function to track ZVALs in scope structures
  • Proper GC tracking for context HashTables (values and keys)
  • GC support for finally handlers, exception handlers, and function call parameters
  • GC tracking for waker events, internal context, and nested async structures
  • Prevents memory leaks in complex async applications with circular references
• Key Order Preservation: Added preserveKeyOrder parameter to async await functions
  • Added preserve_key_order parameter to async_await_futures() API function
  • Added preserve_key_order field to async_await_context_t structure
  • Enhanced awaitAll(), awaitAllWithErrors(), awaitAnyOf(), and awaitAnyOfWithErrors() functions with preserveKeyOrder parameter (defaults to true)
  • Allows controlling whether the original key order is maintained in result arrays

Fixed

• Memory management improvements for long-running async applications
• Proper cleanup of coroutine and scope objects during garbage collection cycles
• Async Iterator API:
  • Fixed iterator state management to prevent memory leaks
• Fixed the spawnWith() function for interaction with the ScopeProvider and SpawnStrategy interface
• Build System Fixes:
  • Fixed macOS compilation error with missing field initializer in uv_stdio_container_t structure (libuv_reactor.c:1956)
  • Fixed Windows build script PowerShell syntax error (missing shell: cmd directive)
  • Fixed race condition issues in 10 async test files for deterministic test execution on all platforms

Changed

• Breaking Change: Function Renaming - Major API reorganization for better consistency:
  • awaitAllFailFirst() → awaitAllOrFail()
  • awaitAllWithErrors() → awaitAll()
  • awaitAnyOfFailFirst() → awaitAnyOfOrFail()
  • awaitAnyOfWithErrors() → awaitAnyOf()
• Breaking Change: awaitAll() Return Format - New awaitAll() (formerly awaitAllWithErrors()) now returns [results, exceptions] tuple:
  • First element [0] contains array of successful results
  • Second element [1] contains array of exceptions from failed coroutines
  • Migration: Update from $results = awaitAll($coroutines) to [$results, $exceptions] = awaitAll($coroutines)
• LibUV requirement increased to ≥ 1.44.0 - Requires libuv version 1.44.0 or later to ensure proper UV_RUN_ONCE behavior and prevent busy loop issues that could cause high CPU usage
• Async Iterator API:
  • Proper handling of REWIND/NEXT states in a concurrent environment.
    The iterator code now stops iteration in
    coroutines if the iterator is in the process of changing its position.
  • Added functionality for proper handling of exceptions from Zend iterators (\Iterator and generators).
    An exception that occurs in the iterator can now be handled by the iterator's owner.

Experimental release (fixes)

Bug fixing in the previous release:

• Fixed issue with CURL 8.5
• Fixed warnings for GCC
• Fixed issues with --repeat=2 CLI test mode

Experimental release

🚀 PHP TRUE ASYNC v0.2.0 Release Notes

To build this release, use the corresponding tag from the PHP SRC project:
https://github.com/true-async/php-src/releases/tag/v0.2.0

Major Architecture & API Enhancement

---

🎯 Key Highlights

• Now asynchronous execution is available at all stages of PHP operation, even in the register_shutdown function.

• The key features of the RFC are completed!

  ---

  ⭐ New Features

  🛡️ Enhanced Exception Handling

  • CompositeException - New exception class for handling multiple exceptions in finally blocks
  • Automatic exception collection from onFinally handlers in both Scope and Coroutine
  • Guaranteed execution of all finally handlers even when exceptions occur
  • Methods: addException() and getExceptions() for exception management

  🔄 Extended Scope Capabilities

  • Complete implementation of onFinally() method for Async\Scope class
  • disposeAfterTimeout() method for automatic cleanup with timeout
  • awaitAfterCancellation() method for post-cancellation waiting
  • Async\protect() function for protecting critical sections

  ⚡ Coroutine Priority Support

  • Priority support in async iterator system
  • Coroutine priority support in TrueAsync API
  • Optimized execution scheduling based on priority levels

  🔧 System Improvements

  • Async-aware destructor handling - Proper destructor handling in async context via async_shutdown_destructors()
  • Cross-thread trigger event API for inter-thread communication
  • Signal handlers support (UNIX systems)
  • Enhanced Iterator API integration with run() and run_in_coroutine() methods
  • Asynchronous execution is available at all stages of PHP operation, even in the register_shutdown function.

  ---

  🔄 Architecture Changes

  • Enhanced ZEND_ASYNC_NEW_SCOPE API - Create Scope without Zend object for internal use
  • Refactored catch_or_cancel logic according to RFC scope behavior
  • Optimized iterator module and data structures
  • Improved exception handling and cancellation logic
  • Enhanced Context API behavior for Scope operations

  ---

  🐛 Bug Fixes

  • Multiple fixes for Scope dispose operations
  • Fixed scope_try_to_dispose logic
  • Resolved race conditions in process waiting (libuv)
  • Memory cleanup fixes for reactor shutdown
  • Build issues resolution for Scope
  • Context logic fixes with NULL scope
  • Iterator bugs and coroutine issues resolved
  • Stream tests and DNS tests fixes
  • ZEND_ASYNC_IS_OFF issues resolved

  ---

  📊 Testing Suite

  Comprehensive test coverage includes:

  • 150+ tests across all key areas
  • DNS tests (15 files) including IPv6 support
  • CURL tests with async support
  • Socket and Stream operation tests
  • Output buffer isolation tests between coroutines
  • Exception handling and cancellation tests
  • Scope lifecycle and finally handler tests

  ---

  🏗️ Build Process

The --enable-experimental-async-api option is no longer needed as the Async API is now enabled by default in the core.

---

🔗 Compatibility

• PHP 8.5.0+ (official support)
• LibUV as primary reactor implementation
• Windows and Unix/macOS platforms
• IPv6 support for DNS and socket operations

---

📈 Performance Improvements

• Optimized iterator module performance
• Enhanced memory management with proper separation
• Improved circular buffer behavior during relocation and resizing
• Refactored timeout object implementation
• Better scheduler graceful shutdown logic

---

🚀 What's Next

This release represents a significant step towards stabilizing PHP's async ecosystem. The core API is now mature enough for production testing, with comprehensive exception handling, proper resource management, and
extensive test coverage.

---

📋 Migration Guide

From v0.1.0 to v0.2.0

1. Build Process: Remove --enable-experimental-async-api from your build scripts
2. Exception Handling: Update error handling to work with CompositeException
3. Scope API: Leverage new onFinally(), disposeAfterTimeout(), and awaitAfterCancellation() methods
4. Priority Support: Optionally implement coroutine priorities for better performance

Breaking Changes

• None - this release maintains backward compatibility with v0.1.0

---

PHP TRUE ASYNC — modern async PHP, today!

v0.1.0

Core functions for working with the PHP engine

v0.0.1

Simplified partial core functionality with tests.