async.c

/*
+----------------------------------------------------------------------+
  | Copyright (c) The PHP Group                                          |
  +----------------------------------------------------------------------+
  | This source file is subject to version 3.01 of the PHP license,      |
  | that is bundled with this package in the file LICENSE, and is        |
  | available through the world-wide-web at the following url:           |
  | https://www.php.net/license/3_01.txt                                 |
  | If you did not receive a copy of the PHP license and are unable to   |
  | obtain it through the world-wide-web, please send a note to          |
  | license@php.net so we can mail you a copy immediately.               |
  +----------------------------------------------------------------------+
  | Author: Edmond                                                       |
  +----------------------------------------------------------------------+
*/

#include "zend_exceptions.h"
#include "zend_closures.h"
#include "zend_common.h"
#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include "php_async.h"
#include "ext/standard/info.h"
#include "scheduler.h"
#include "internal/circular_buffer.h"
#include "Zend/zend_fibers.h"
#include "exceptions.h"
#include "scope.h"
#include "context.h"
#include "future.h"
#include "channel.h"
#include "thread_channel.h"
#include "thread_pool.h"
#include "pool.h"
#include "task_group.h"
#include "fs_watcher.h"
#include "iterator.h"
#include "async_API.h"
#include "cpu_info.h"
#include "zend_enum.h"
#include "async_arginfo.h"
#include "zend_interfaces.h"
#include "libuv_reactor.h"
#include "thread.h"

zend_class_entry *async_ce_awaitable = NULL;
zend_class_entry *async_ce_completable = NULL;
zend_class_entry *async_ce_timeout = NULL;
zend_class_entry *async_ce_signal = NULL;
zend_class_entry *async_ce_circuit_breaker_state = NULL;
zend_class_entry *async_ce_circuit_breaker = NULL;
zend_class_entry *async_ce_circuit_breaker_strategy = NULL;

///////////////////////////////////////////////////////////////
/// Module functions
///////////////////////////////////////////////////////////////

static zend_object *async_timeout_create(zend_ulong ms, bool is_periodic);

#define THROW_IF_SCHEDULER_CONTEXT \
	if (UNEXPECTED(ZEND_ASYNC_IS_SCHEDULER_CONTEXT)) { \
		async_throw_error("The operation cannot be executed in the scheduler context"); \
		RETURN_THROWS(); \
	}

#define THROW_IF_ASYNC_OFF \
	if (UNEXPECTED(ZEND_ASYNC_OFF)) { \
		async_throw_error("The operation cannot be executed while async is off"); \
		RETURN_THROWS(); \
	}

#define SCHEDULER_LAUNCH \
	if (UNEXPECTED(ZEND_ASYNC_CURRENT_COROUTINE == NULL)) { \
		if (!async_scheduler_launch()) { \
			RETURN_THROWS(); \
		} \
	}

PHP_FUNCTION(Async_spawn)
{
	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	zval *args = NULL;
	int args_count = 0;
	HashTable *named_args = NULL;

	zend_fcall_info fci;
	zend_fcall_info_cache fcc;

	ZEND_PARSE_PARAMETERS_START(1, -1)
	Z_PARAM_FUNC(fci, fcc);
	Z_PARAM_VARIADIC_WITH_NAMED(args, args_count, named_args);
	ZEND_PARSE_PARAMETERS_END();

	async_coroutine_t *coroutine = (async_coroutine_t *) ZEND_ASYNC_SPAWN();

	if (UNEXPECTED(coroutine == NULL)) {
		return;
	}

	ZEND_ASYNC_FCALL_DEFINE(fcall, fci, fcc, args, args_count, named_args);

	coroutine->coroutine.fcall = fcall;

	RETURN_OBJ_COPY(&coroutine->std);
}

PHP_FUNCTION(Async_spawn_with)
{
	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	zval *args = NULL;
	int args_count = 0;
	HashTable *named_args = NULL;

	zend_async_scope_t *scope = NULL;
	zend_object *scope_provider = NULL;
	zend_fcall_info fci;
	zend_fcall_info_cache fcc;

	ZEND_PARSE_PARAMETERS_START(2, -1)
	Z_PARAM_OBJ_OF_CLASS(scope_provider, async_ce_scope_provider)
	Z_PARAM_FUNC(fci, fcc);
	Z_PARAM_VARIADIC_WITH_NAMED(args, args_count, named_args);
	ZEND_PARSE_PARAMETERS_END();

	// If scope_provider is an instance of async_ce_scope
	if (instanceof_function(scope_provider->ce, async_ce_scope)) {
		scope = &((async_scope_object_t *) scope_provider)->scope->scope;
	}

	async_coroutine_t *coroutine =
			(async_coroutine_t *) (scope_provider ? ZEND_ASYNC_SPAWN_WITH_PROVIDER(scope_provider)
												  : ZEND_ASYNC_SPAWN_WITH(scope));

	if (UNEXPECTED(EG(exception) != NULL)) {
		RETURN_THROWS();
	}

	ZEND_ASYNC_FCALL_DEFINE(fcall, fci, fcc, args, args_count, named_args);

	coroutine->coroutine.fcall = fcall;

	RETURN_OBJ_COPY(&coroutine->std);
}

PHP_FUNCTION(Async_spawn_thread)
{
	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

#ifndef ZTS
	async_throw_error("spawn_thread() requires a Thread-Safe (ZTS) PHP build");
	RETURN_THROWS();
#endif

	zval *entry_zv = NULL;
	bool inherit = true;
	zval *bootloader_zv = NULL;

	ZEND_PARSE_PARAMETERS_START(1, 3)
	Z_PARAM_OBJECT_OF_CLASS(entry_zv, zend_ce_closure)
	Z_PARAM_OPTIONAL
	Z_PARAM_BOOL(inherit)
	Z_PARAM_OBJECT_OF_CLASS_OR_NULL(bootloader_zv, zend_ce_closure)
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	const uint32_t thread_flags = inherit ? ZEND_THREAD_F_INHERIT : 0;

	/* Build fcall structs from Closure zvals */
	zend_fcall_t entry;
	zend_fcall_info_init(entry_zv, 0, &entry.fci, &entry.fci_cache, NULL, NULL);

	zend_fcall_t boot, *boot_ptr = NULL;
	if (bootloader_zv != NULL
		&& zend_fcall_info_init(bootloader_zv, 0, &boot.fci, &boot.fci_cache, NULL, NULL) == SUCCESS) {
		boot_ptr = &boot;
	}

	zend_async_thread_event_t *thread_event =
		ZEND_ASYNC_NEW_THREAD_EVENT_EX(&entry, boot_ptr, thread_flags, 0);

	if (UNEXPECTED(thread_event == NULL)) {
		RETURN_THROWS();
	}

	/* Create the Thread PHP object — takes ownership of the event (ref_count=1) */
	zend_object *obj = async_ce_thread->create_object(async_ce_thread);
	async_thread_object_t *thread_obj = async_thread_object_from_obj(obj);
	thread_obj->thread_event = thread_event;

	/* Capture the current scope as the parent for any finally-handlers that
	 * may get registered later. Addref keeps the scope struct alive until
	 * thread_object_free() releases it, so handlers always have a valid
	 * parent even if the user drops their scope reference first. */
	thread_obj->parent_scope = ZEND_ASYNC_CURRENT_SCOPE;
	if (thread_obj->parent_scope != NULL) {
		ZEND_ASYNC_EVENT_ADD_REF(&thread_obj->parent_scope->event);
	}

	/* Set event reference so ZEND_ASYNC_OBJECT_TO_EVENT() can resolve from this object */
	ZEND_ASYNC_EVENT_REF_SET(thread_obj,
		offsetof(async_thread_object_t, std), &thread_event->base);

	/* Record spawn location */
	zend_apply_current_filename_and_line(&thread_event->filename, &thread_event->lineno);

	/* Start the thread */
	if (UNEXPECTED(!thread_event->base.start(&thread_event->base))) {
		OBJ_RELEASE(obj);
		RETURN_THROWS();
	}

	RETURN_OBJ(obj);
}

PHP_FUNCTION(Async_suspend)
{
	ZEND_PARSE_PARAMETERS_NONE();

	if (UNEXPECTED(ZEND_ASYNC_IS_OFF)) {
		return;
	}

	THROW_IF_SCHEDULER_CONTEXT;
	ZEND_ASYNC_ENQUEUE_COROUTINE(ZEND_ASYNC_CURRENT_COROUTINE);
	ZEND_ASYNC_SUSPEND();
	zend_async_waker_clean(ZEND_ASYNC_CURRENT_COROUTINE);
}

PHP_FUNCTION(Async_protect)
{
	zend_object *closure;

	ZEND_PARSE_PARAMETERS_START(1, 1)
	Z_PARAM_OBJ_OF_CLASS(closure, zend_ce_closure)
	ZEND_PARSE_PARAMETERS_END();

	zend_coroutine_t *coroutine = ZEND_ASYNC_CURRENT_COROUTINE;
	bool do_bailout = false;

	zend_try
	{
		if (coroutine != NULL) {
			ZEND_COROUTINE_SET_PROTECTED(coroutine);
		}

		ZVAL_UNDEF(return_value);

		zval closure_zval;
		ZVAL_OBJ(&closure_zval, closure);

		if (UNEXPECTED(call_user_function(NULL, NULL, &closure_zval, return_value, 0, NULL) == FAILURE)) {
			zend_throw_error(NULL, "Failed to call finally handler in finished coroutine");
			zval_ptr_dtor(return_value);
		}

		if (Z_TYPE_P(return_value) == IS_UNDEF) {
			// If the closure did not return a value, we return NULL.
			ZVAL_NULL(return_value);
		}
	}
	zend_catch
	{
		do_bailout = true;
	}
	zend_end_try();

	if (coroutine != NULL) {
		ZEND_COROUTINE_CLR_PROTECTED(coroutine);
	}

	if (UNEXPECTED(do_bailout)) {
		zend_bailout();
	}

	if (UNEXPECTED(coroutine == NULL)) {
		return;
	}

	async_coroutine_t *async_coroutine = (async_coroutine_t *) coroutine;

	if (async_coroutine->deferred_cancellation) {
		ZEND_COROUTINE_SET_CANCELLED(coroutine);
		async_rethrow_exception(async_coroutine->deferred_cancellation);
		async_coroutine->deferred_cancellation = NULL;
	}
}

PHP_FUNCTION(Async_await)
{
	zend_object *awaitable = NULL;
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(1, 2)
	Z_PARAM_OBJ_OF_CLASS(awaitable, async_ce_completable);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_completable);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	zend_coroutine_t *coroutine = ZEND_ASYNC_CURRENT_COROUTINE;

	if (UNEXPECTED(coroutine == NULL)) {
		RETURN_NULL();
	}

	zend_async_event_t *awaitable_event = ZEND_ASYNC_OBJECT_TO_EVENT(awaitable);
	zend_async_event_t *cancellation_event = cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL;

	// Mark that result will be used and exception will be caught
	ZEND_ASYNC_EVENT_SET_RESULT_USED(awaitable_event);
	ZEND_ASYNC_EVENT_SET_EXC_CAUGHT(awaitable_event);

	// If the awaitable is the same as the cancellation event, we can skip the cancellation check.
	if (awaitable_event == cancellation_event) {
		cancellation_event = NULL;
	}

	// If the awaitable is already resolved, we can return the result immediately.
	if (ZEND_ASYNC_EVENT_IS_CLOSED(awaitable_event)) {

		if (UNEXPECTED(awaitable_event->replay == NULL)) {
			zend_error(E_CORE_WARNING, "Cannot await a closed event which cannot be replayed");
			RETURN_NULL();
		}

		if (ZEND_ASYNC_EVENT_EXTRACT_RESULT(awaitable_event, return_value)) {
			return;
		}

		RETURN_NULL();
	}

	if (cancellation != NULL && UNEXPECTED(async_resolve_cancel_token(cancellation))) {
		RETURN_THROWS();
	}

	ZEND_ASYNC_WAKER_NEW(coroutine);

	if (UNEXPECTED(EG(exception) != NULL)) {
		RETURN_THROWS();
	}

	zend_async_resume_when(coroutine, awaitable_event, false, zend_async_waker_callback_resolve, NULL);

	if (UNEXPECTED(EG(exception) != NULL)) {
		RETURN_THROWS();
	}

	if (cancellation_event != NULL) {
		zend_async_resume_when(coroutine, cancellation_event, false, zend_async_waker_callback_cancel, NULL);

		if (UNEXPECTED(EG(exception) != NULL)) {
			RETURN_THROWS();
		}
	}

	if (!ZEND_ASYNC_SUSPEND()) {
		zend_async_waker_clean(coroutine);
		RETURN_THROWS();
	}

	ZEND_ASSERT(coroutine->waker != NULL && "coroutine->waker must not be NULL");

	if (Z_TYPE(coroutine->waker->result) == IS_UNDEF) {
		ZVAL_NULL(return_value);
	} else {
		ZVAL_COPY(return_value, &coroutine->waker->result);
	}

	zend_async_waker_clean(coroutine);
}

PHP_FUNCTION(Async_await_any_or_fail)
{
	zval *futures;
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(1, 2)
	Z_PARAM_ZVAL(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	HashTable *results = zend_new_array(8);

	async_await_futures(futures,
						1,
						false,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						NULL,
						false,
						false,
						false);

	if (EG(exception)) {
		zend_array_release(results);
		RETURN_THROWS();
	}

	if (zend_hash_num_elements(results) == 0) {
		zend_array_release(results);
		RETURN_NULL();
	}

	zval result;
	ZEND_HASH_FOREACH_VAL(results, zval * item)
	{
		ZVAL_COPY(&result, item);
		break;
	}
	ZEND_HASH_FOREACH_END();

	zend_array_release(results);

	RETURN_ZVAL(&result, 0, 0);
}

PHP_FUNCTION(Async_await_first_success)
{
	zval *futures;
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(1, 2)
	Z_PARAM_ZVAL(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	HashTable *results = zend_new_array(8);
	HashTable *errors = zend_new_array(8);

	async_await_futures(futures,
						1,
						true,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						errors,
						false,
						false,
						true);

	if (EG(exception)) {
		zend_array_release(results);
		zend_array_release(errors);
		RETURN_THROWS();
	}

	HashTable *return_array = zend_new_array(2);

	zval val;
	ZVAL_NULL(&val);

	ZEND_HASH_FOREACH_VAL(results, zval * item)
	{
		ZVAL_COPY(&val, item);
		break;
	}
	ZEND_HASH_FOREACH_END();

	zend_hash_next_index_insert_new(return_array, &val);

	ZVAL_ARR(&val, errors);
	zend_hash_next_index_insert_new(return_array, &val);

	zend_array_release(results);

	RETURN_ARR(return_array);
}

PHP_FUNCTION(Async_await_all_or_fail)
{
	zval *futures;
	zend_object *cancellation = NULL;
	bool preserve_key_order = true;

	ZEND_PARSE_PARAMETERS_START(1, 3)
	Z_PARAM_ZVAL(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	Z_PARAM_BOOL(preserve_key_order);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	HashTable *results = zend_new_array(8);

	async_await_futures(futures,
						0,
						false,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						NULL,
						// For awaitAll, it’s always necessary to fill the result with NULL,
						// because the order of keys matters.
						true,
						preserve_key_order,
						true);

	if (EG(exception)) {
		zend_array_release(results);
		RETURN_THROWS();
	}

	RETURN_ARR(results);
}

PHP_FUNCTION(Async_await_all)
{
	zval *futures;
	zend_object *cancellation = NULL;
	bool preserve_key_order = true;
	bool fill_null = false;

	ZEND_PARSE_PARAMETERS_START(1, 4)
	Z_PARAM_ZVAL(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	Z_PARAM_BOOL(preserve_key_order);
	Z_PARAM_BOOL(fill_null);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	HashTable *results = zend_new_array(8);
	HashTable *errors = zend_new_array(8);

	async_await_futures(futures,
						0,
						true,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						errors,
						fill_null,
						preserve_key_order,
						true);

	if (EG(exception)) {
		zend_array_release(results);
		zend_array_release(errors);
		RETURN_THROWS();
	}

	HashTable *return_array = zend_new_array(2);

	zval val;
	ZVAL_ARR(&val, results);
	zend_hash_next_index_insert_new(return_array, &val);

	ZVAL_ARR(&val, errors);
	zend_hash_next_index_insert_new(return_array, &val);

	RETURN_ARR(return_array);
}

PHP_FUNCTION(Async_await_any_of_or_fail)
{
	zval *futures;
	zend_object *cancellation = NULL;
	zend_long count = 0;
	bool preserve_key_order = true;

	ZEND_PARSE_PARAMETERS_START(2, 4)
	Z_PARAM_LONG(count)
	Z_PARAM_ITERABLE(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	Z_PARAM_BOOL(preserve_key_order);
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	HashTable *results = zend_new_array(8);

	if (count == 0) {
		RETURN_ARR(results);
	}

	async_await_futures(futures,
						(int) count,
						false,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						NULL,
						false,
						preserve_key_order,
						false);

	if (EG(exception)) {
		zend_array_release(results);
		RETURN_THROWS();
	}

	RETURN_ARR(results);
}

PHP_FUNCTION(Async_await_any_of)
{
	zval *futures;
	zend_object *cancellation = NULL;
	zend_long count = 0;
	bool preserve_key_order = true;
	bool fill_null = false;

	ZEND_PARSE_PARAMETERS_START(2, 5)
	Z_PARAM_LONG(count)
	Z_PARAM_ZVAL(futures);
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_awaitable);
	Z_PARAM_BOOL(preserve_key_order);
	Z_PARAM_BOOL(fill_null);
	ZEND_PARSE_PARAMETERS_END();

	HashTable *results = zend_new_array(8);
	HashTable *errors = zend_new_array(8);

	SCHEDULER_LAUNCH;

	async_await_futures(futures,
						(int) count,
						true,
						cancellation != NULL ? ZEND_ASYNC_OBJECT_TO_EVENT(cancellation) : NULL,
						0,
						0,
						results,
						errors,
						fill_null,
						preserve_key_order,
						true);

	if (EG(exception)) {
		zend_array_release(results);
		zend_array_release(errors);
		RETURN_THROWS();
	}

	HashTable *return_array = zend_new_array(2);

	zval val;
	ZVAL_ARR(&val, results);
	zend_hash_next_index_insert_new(return_array, &val);

	ZVAL_ARR(&val, errors);
	zend_hash_next_index_insert_new(return_array, &val);

	RETURN_ARR(return_array);
}

PHP_FUNCTION(Async_delay)
{
	zend_long ms = 0;

	ZEND_PARSE_PARAMETERS_START(1, 1)
	Z_PARAM_LONG(ms)
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	zend_coroutine_t *coroutine = ZEND_ASYNC_CURRENT_COROUTINE;

	if (UNEXPECTED(coroutine == NULL)) {
		return;
	}

	if (UNEXPECTED(ms == 0)) {
		ZEND_ASYNC_ENQUEUE_COROUTINE(ZEND_ASYNC_CURRENT_COROUTINE);
	} else {
		zend_async_waker_new_with_timeout(coroutine, ms, NULL);

		if (UNEXPECTED(EG(exception) != NULL)) {
			RETURN_THROWS();
		}
	}

	ZEND_ASYNC_SUSPEND();

	zend_async_waker_clean(coroutine);
}

PHP_FUNCTION(Async_available_parallelism)
{
	ZEND_PARSE_PARAMETERS_NONE();

	if (UNEXPECTED(zend_async_available_parallelism_fn == NULL)) {
		async_throw_error("Reactor is not registered");
		RETURN_THROWS();
	}

	RETURN_LONG((zend_long) ZEND_ASYNC_AVAILABLE_PARALLELISM());
}

/* Lock-free snapshot of scheduler counters. */
PHP_FUNCTION(Async_runtime_stats)
{
	ZEND_PARSE_PARAMETERS_NONE();

	/*
	 * Before the scheduler is launched (e.g. runtime_stats() called at the top
	 * level, outside any coroutine), the queue buffers are not yet allocated.
	 * Report a zeroed snapshot rather than reading uninitialized state; the pool
	 * minimum and fiber stack size are static and still meaningful.
	 */
	if (ZEND_ASYNC_SCHEDULER == NULL) {
		array_init(return_value);
		add_assoc_long(return_value, "coroutines_total",         0);
		add_assoc_long(return_value, "coroutines_active",        0);
		add_assoc_long(return_value, "microtasks_queue",         0);
		add_assoc_long(return_value, "coroutine_queue",          0);
		add_assoc_long(return_value, "resumed_queue",            0);
		add_assoc_long(return_value, "fiber_pool_count",         0);
		add_assoc_long(return_value, "fiber_pool_capacity",      0);
		add_assoc_long(return_value, "fiber_pool_min",           (zend_long) ASYNC_FIBER_POOL_SIZE);
		add_assoc_long(return_value, "fiber_stack_size",         (zend_long) EG(fiber_stack_size));
		add_assoc_long(return_value, "fiber_pool_virtual_bytes", 0);
		return;
	}

	const circular_buffer_t *const pool       = &ASYNC_G(fiber_context_pool);
	const circular_buffer_t *const microtasks = &ASYNC_G(microtasks);
	const circular_buffer_t *const coro_queue = &ASYNC_G(coroutine_queue);
	const circular_buffer_t *const resumed_q  = &ASYNC_G(resumed_coroutines);

	/* Both reads guard against capacity 0: before the scheduler allocates these
	 * buffers, circular_buffer_capacity() would underflow (capacity-1 = SIZE_MAX)
	 * and circular_buffer_count() would read uninitialized head/tail. Clamp to 0. */
	const size_t pool_count      = pool->capacity > 0
	                                 ? circular_buffer_count(pool) : 0;
	const size_t pool_capacity   = pool->capacity > 0
	                                 ? circular_buffer_capacity(pool) : 0;
	const size_t stack_size      = EG(fiber_stack_size);

	array_init(return_value);

	add_assoc_long(return_value, "coroutines_total",
	               (zend_long) zend_hash_num_elements(&ASYNC_G(coroutines)));
	add_assoc_long(return_value, "coroutines_active",
	               (zend_long) ZEND_ASYNC_ACTIVE_COROUTINE_COUNT);

	add_assoc_long(return_value, "microtasks_queue",
	               (zend_long) (microtasks->capacity > 0 ? circular_buffer_count(microtasks) : 0));
	add_assoc_long(return_value, "coroutine_queue",
	               (zend_long) (coro_queue->capacity > 0 ? circular_buffer_count(coro_queue) : 0));
	add_assoc_long(return_value, "resumed_queue",
	               (zend_long) (resumed_q->capacity > 0 ? circular_buffer_count(resumed_q) : 0));

	add_assoc_long(return_value, "fiber_pool_count",    (zend_long) pool_count);
	add_assoc_long(return_value, "fiber_pool_capacity", (zend_long) pool_capacity);
	add_assoc_long(return_value, "fiber_pool_min",      (zend_long) ASYNC_FIBER_POOL_SIZE);
	add_assoc_long(return_value, "fiber_stack_size",    (zend_long) stack_size);
	add_assoc_long(return_value, "fiber_pool_virtual_bytes",
	               (zend_long) (pool_count * stack_size));
}

PHP_FUNCTION(Async_timeout)
{
	zend_long ms = 0;

	ZEND_PARSE_PARAMETERS_START(1, 1)
	Z_PARAM_LONG(ms)
	ZEND_PARSE_PARAMETERS_END();

	if (ms <= 0) {
		zend_value_error("Timeout value must be greater than 0");
		RETURN_THROWS();
	}

	zend_object *zend_object = async_timeout_create(ms, false);

	if (UNEXPECTED(EG(exception) != NULL)) {
		RETURN_THROWS();
	}

	RETURN_OBJ(zend_object);
}

PHP_FUNCTION(Async_current_context)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	// The context is anchored to a scope, and no scope exists until the scheduler launches.
	SCHEDULER_LAUNCH;

	zend_async_scope_t *scope = ZEND_ASYNC_CURRENT_SCOPE;

	if (UNEXPECTED(scope == NULL)) {
		async_throw_error("The current scope is not defined");
		RETURN_THROWS();
	}

	if (scope->context == NULL) {
		// Scope exists but no context - create new context and link it to scope
		async_context_t *context = async_context_new();
		context->scope = scope;
		scope->context = &context->base;
		RETURN_OBJ_COPY(&context->std);
	}

	// Return the existing context from scope
	async_context_t *context = (async_context_t *) scope->context;
	RETURN_OBJ_COPY(&context->std);
}

PHP_FUNCTION(Async_coroutine_context)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	// The context is anchored to the coroutine, and no coroutine exists until the scheduler launches.
	SCHEDULER_LAUNCH;

	async_coroutine_t *coroutine = (async_coroutine_t *) ZEND_ASYNC_CURRENT_COROUTINE;

	if (UNEXPECTED(coroutine == NULL)) {
		async_throw_error("The current coroutine is not defined");
		RETURN_THROWS();
	}

	if (coroutine->coroutine.context == NULL) {
		// Coroutine exists but no context - create and assign to coroutine
		async_context_t *context = async_context_new();
		coroutine->coroutine.context = &context->base;
		RETURN_OBJ_COPY(&context->std);
	}

	// Return the existing context from coroutine
	async_context_t *context = (async_context_t *) coroutine->coroutine.context;
	RETURN_OBJ_COPY(&context->std);
}

PHP_FUNCTION(Async_current_coroutine)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	async_coroutine_t *coroutine = (async_coroutine_t *) ZEND_ASYNC_CURRENT_COROUTINE;

	if (UNEXPECTED(coroutine == NULL)) {
		zend_async_throw(ZEND_ASYNC_EXCEPTION_DEFAULT, "The current coroutine is not defined");

		RETURN_THROWS();
	}

	RETURN_OBJ_COPY(&coroutine->std);
}

PHP_FUNCTION(Async_root_context)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	// The root context is the context of the main scope. Holding it in a global of its own put it outside
	// the scope tree, where find() -- which walks scope->parent_scope -- could never reach it.
	SCHEDULER_LAUNCH;

	zend_async_scope_t *scope = ZEND_ASYNC_MAIN_SCOPE;

	if (UNEXPECTED(scope == NULL)) {
		async_throw_error("The main scope is not defined");
		RETURN_THROWS();
	}

	if (scope->context == NULL) {
		async_context_t *context = async_context_new();
		context->scope = scope;
		scope->context = &context->base;
		RETURN_OBJ_COPY(&context->std);
	}

	async_context_t *context = (async_context_t *) scope->context;
	RETURN_OBJ_COPY(&context->std);
}

PHP_FUNCTION(Async_request_context)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	zend_async_scope_t *scope = ZEND_ASYNC_REQUEST_SCOPE;

	if (scope == NULL) {
		RETURN_NULL();
	}

	if (scope->context == NULL) {
		async_context_t *context = async_context_new();
		context->scope = scope;
		scope->context = &context->base;
		RETURN_OBJ_COPY(&context->std);
	}

	async_context_t *context = (async_context_t *) scope->context;
	RETURN_OBJ_COPY(&context->std);
}

PHP_FUNCTION(Async_get_coroutines)
{
	ZEND_PARSE_PARAMETERS_NONE();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	array_init(return_value);

	async_coroutine_t *coroutine;
	ZEND_HASH_FOREACH_PTR(&ASYNC_G(coroutines), coroutine)
	{
		add_next_index_object(return_value, &coroutine->std);
		GC_ADDREF(&coroutine->std);
	}
	ZEND_HASH_FOREACH_END();
}

PHP_FUNCTION(Async_graceful_shutdown)
{
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(0, 1)
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_cancellation_exception)
	ZEND_PARSE_PARAMETERS_END();

	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	start_graceful_shutdown_with(cancellation);
}

PHP_FUNCTION(Async_iterate)
{
	THROW_IF_ASYNC_OFF;
	THROW_IF_SCHEDULER_CONTEXT;

	zval *iterable;
	zend_fcall_info fci;
	zend_fcall_info_cache fcc;
	zend_long concurrency = 0;
	bool cancel_pending = true;

	ZEND_PARSE_PARAMETERS_START(2, 4)
	Z_PARAM_ZVAL(iterable)
	Z_PARAM_FUNC(fci, fcc)
	Z_PARAM_OPTIONAL
	Z_PARAM_LONG(concurrency)
	Z_PARAM_BOOL(cancel_pending)
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	zend_object_iterator *zend_iterator = NULL;
	zval *array = NULL;

	if (Z_TYPE_P(iterable) == IS_ARRAY) {
		array = iterable;
	} else if (Z_TYPE_P(iterable) == IS_OBJECT && Z_OBJCE_P(iterable)->get_iterator) {
		zend_iterator = Z_OBJCE_P(iterable)->get_iterator(Z_OBJCE_P(iterable), iterable, 0);

		if (UNEXPECTED(EG(exception) == NULL && zend_iterator == NULL)) {
			async_throw_error("Failed to create iterator");
		}
	} else {
		zend_argument_type_error(1, "must be of type array|Traversable, %s given", zend_zval_type_name(iterable));
		RETURN_THROWS();
	}

	if (UNEXPECTED(EG(exception))) {
		RETURN_THROWS();
	}

	// Create a child scope for the iterator to isolate it from the current scope.
	// This prevents exceptions in iterator coroutines from cancelling unrelated coroutines.
	zend_async_scope_t *iterator_scope = ZEND_ASYNC_NEW_SCOPE(ZEND_ASYNC_CURRENT_SCOPE);

	if (UNEXPECTED(iterator_scope == NULL)) {
		// free zend_iterator if it was created before returning
		if (zend_iterator != NULL) {
			zend_iterator_dtor(zend_iterator);
		}

		RETURN_THROWS();
	}

	ZEND_ASYNC_SCOPE_CLR_DISPOSE_SAFELY(iterator_scope);

	/* Create fcall with 2 parameter slots for (value, key) */
	zend_fcall_t *fcall = ecalloc(1, sizeof(zend_fcall_t));
	fcall->fci = fci;
	fcall->fci_cache = fcc;
	fcall->fci.param_count = 2;
	fcall->fci.params = safe_emalloc(2, sizeof(zval), 0);
	ZVAL_UNDEF(&fcall->fci.params[0]);
	ZVAL_UNDEF(&fcall->fci.params[1]);
	Z_TRY_ADDREF(fcall->fci.function_name);

	zend_async_iterator_t *iterator = ZEND_ASYNC_NEW_ITERATOR_SCOPE(
			array, zend_iterator, fcall, NULL, iterator_scope, (unsigned int) concurrency, ZEND_COROUTINE_NORMAL);

	if (UNEXPECTED(iterator == NULL || EG(exception))) {
		iterator_scope->try_to_dispose(iterator_scope);
		efree(fcall->fci.params);
		efree(fcall);

		if (zend_iterator != NULL) {
			zend_iterator_dtor(zend_iterator);
		}

		RETURN_THROWS();
	}

	async_iterator_t *async_iter = (async_iterator_t *) iterator;

	if (Z_TYPE(async_iter->array) != IS_UNDEF) {
		SEPARATE_ARRAY(&async_iter->array);
	}

	// Run the iterator in a separate coroutine within the child scope
	async_iterator_run_in_coroutine(async_iter, ZEND_COROUTINE_NORMAL, false);

	if (UNEXPECTED(EG(exception))) {
		iterator_scope->try_to_dispose(iterator_scope);
		efree(fcall->fci.params);
		efree(fcall);

		if (zend_iterator != NULL) {
			zend_iterator_dtor(zend_iterator);
		}

		RETURN_THROWS();
	}

	// Increment ref count of the scope event to ensure it is not freed while we are waiting for it.
	iterator_scope->event.ref_count++;
	ZEND_ASYNC_MICROTASK_ADD_REF(&iterator->microtask);

	zend_coroutine_t *coroutine = ZEND_ASYNC_CURRENT_COROUTINE;
	zend_object *exception = NULL;

	// Wait for the iterator completion event
	iterator->completion_event = async_iterator_completion_event_create();
	ZEND_ASYNC_WAKER_NEW(coroutine);
	zend_async_resume_when(coroutine, iterator->completion_event, false, zend_async_waker_callback_resolve, NULL);
	ZEND_ASYNC_SUSPEND();

	if (UNEXPECTED(EG(exception))) {
		exception = EG(exception);
		GC_ADDREF(exception);
		zend_clear_exception();
	}

	// Handle pending coroutines spawned inside the iterator scope.
	if (false == ZEND_ASYNC_SCOPE_IS_COMPLETED(iterator_scope)) {

		if (cancel_pending) {
			// Cancel all pending coroutines in the iterator scope
			ZEND_ASYNC_SCOPE_CANCEL(iterator_scope,
									async_new_exception(async_ce_cancellation_exception,
														"Cancellation of pending coroutines after iterator completion"),
									true,
									ZEND_ASYNC_SCOPE_IS_DISPOSE_SAFELY(iterator_scope));
		}

		if (UNEXPECTED(EG(exception))) {
			if (exception != NULL) {
				zend_exception_set_previous(EG(exception), exception);
			}

			exception = EG(exception);
			GC_ADDREF(exception);
			zend_clear_exception();
		} else {
			// Wait for the child scope to fully complete
			ZEND_ASYNC_WAKER_NEW(coroutine);
			zend_async_resume_when(coroutine, &iterator_scope->event, false, zend_async_waker_callback_resolve, NULL);

			if (EXPECTED(EG(exception) == NULL)) {
				ZEND_ASYNC_SUSPEND();
			}
		}

		if (UNEXPECTED(EG(exception))) {
			if (exception != NULL) {
				zend_exception_set_previous(EG(exception), exception);
			}

			exception = EG(exception);
			GC_ADDREF(exception);
			zend_clear_exception();
		}
	}

	// Dispose the child scope
	iterator_scope->try_to_dispose(iterator_scope);

	if (async_iter->zend_iterator != NULL) {
		zend_iterator_dtor(async_iter->zend_iterator);
		async_iter->zend_iterator = NULL;
	}

	if (async_iter->fcall != NULL) {
		zend_fcall_release(async_iter->fcall);
		async_iter->fcall = NULL;
	}

	/* Merge exceptions: iterator exception takes priority */
	if (async_iter->exception != NULL) {

		// Proper handling of iterator exceptions:
		// 1. We can receive the same exception that the iterator threw.
		// 2. If not, then we correctly combine the different exceptions.
		if (exception == async_iter->exception) {
			GC_DELREF(exception);
			async_iter->exception = NULL;
		} else if (exception != NULL) {
			zend_exception_set_previous(async_iter->exception, exception);
			exception = async_iter->exception;
			async_iter->exception = NULL;
		} else {
			exception = async_iter->exception;
			async_iter->exception = NULL;
		}
	}

	iterator->microtask.dtor(&iterator->microtask);

	if (UNEXPECTED(exception != NULL)) {
		zend_throw_exception_internal(exception);
		RETURN_THROWS();
	}
}

/*
PHP_FUNCTION(Async_exec)
{

}
*/

///////////////////////////////////////////////////////////////
/// Signal API
///////////////////////////////////////////////////////////////

#ifndef PHP_WIN32
# include <signal.h>
#endif

/*
 * Async\Signal enum portability shims.
 *
 * The Async\Signal enum (async.stub.php) backs each case with the Linux
 * signal number — those literals are baked into async_arginfo.h at compile
 * time and PHP backed-enum values cannot be platform-conditional.
 *
 * Most signal numbers (HUP, INT, QUIT, ILL, ABRT, FPE, KILL, SEGV, TERM,
 * WINCH) match across Linux, Darwin and the BSDs. SIGUSR1 and SIGUSR2 do
 * NOT — Linux uses 10/12, Darwin/FreeBSD/NetBSD/OpenBSD/DragonFly use
 * 30/31. Without translation, Async\signal(Signal::SIGUSR1) on macOS
 * would arm the libuv watcher on signum 10 (== SIGBUS on Darwin), and a
 * real SIGUSR1 (30) would slip past to PHP's zend_signal_handler_defer,
 * which terminates the process when no userland handler is registered.
 *
 * These two helpers translate between the enum's Linux numbering (used
 * as PHP-visible values) and the OS-native numbers used by libuv /
 * sigaction. Identity on Linux. Compile-time-skipped on Windows (the
 * Async\signal API is Unix-only at the PHP level — its tests carry a
 * SKIPIF for PHP_OS_FAMILY === 'Windows' — and Windows headers do not
 * define SIGUSR1/SIGUSR2 at all, so the translation is unreachable
 * there). The BSD/Darwin family is detected with the same set of
 * preprocessor symbols PHP itself uses elsewhere (Zend/zend_call_stack.c).
 */
static zend_always_inline int async_signum_enum_to_native(int linux_signum)
{
#if defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) \
		|| defined(__OpenBSD__) || defined(__DragonFly__)
	switch (linux_signum) {
		case 10: return SIGUSR1;   /* Linux 10 → BSD/Darwin 30 */
		case 12: return SIGUSR2;   /* Linux 12 → BSD/Darwin 31 */
		default: return linux_signum;
	}
#else
	/* Linux: native already matches enum. Windows: never reached
	 * (signal API is Unix-only) but compiles fine because we don't
	 * reference SIGUSR1/SIGUSR2 macros here. */
	return linux_signum;
#endif
}

static zend_always_inline int async_signum_native_to_enum(int native_signum)
{
#if defined(__APPLE__) || defined(__FreeBSD__) || defined(__NetBSD__) \
		|| defined(__OpenBSD__) || defined(__DragonFly__)
	if (native_signum == SIGUSR1) return 10;
	if (native_signum == SIGUSR2) return 12;
	return native_signum;
#else
	return native_signum;
#endif
}

typedef struct
{
	zend_async_event_callback_t base;
	zend_future_t *future;
	zend_async_signal_event_t *signal_event;
	zend_async_event_callback_t *cancellation_callback;
	zend_async_event_t *cancellation_event;
	zend_object *cancellation_obj;
} async_signal_callback_t;

/* Extra payload appended to zend_future_t for futures returned by Async\signal().
 * Lets the future's own dispose path (called when the PHP Future object is freed,
 * e.g. after await_any_or_fail() picks a different signal) tear down the still-armed
 * signal_event so the libuv reactor can exit. */
typedef struct
{
	zend_async_signal_event_t *signal_event;     /* NULL once signal_event is disposed elsewhere */
	zend_async_event_dispose_t prev_dispose;     /* original zend_future_dispose */
} async_signal_future_extra_t;

#define ASYNC_SIGNAL_FUTURE_EXTRA(future) \
	((async_signal_future_extra_t *) ((char *) (future) + sizeof(zend_future_t)))

static bool async_signal_future_dispose(zend_async_event_t *event)
{
	zend_future_t *future = (zend_future_t *) event;
	async_signal_future_extra_t *extra = ASYNC_SIGNAL_FUTURE_EXTRA(future);

	if (extra->signal_event != NULL) {
		zend_async_event_t *se = &extra->signal_event->base;
		extra->signal_event = NULL;
		if (!ZEND_ASYNC_EVENT_IS_CLOSED(se)) {
			se->stop(se);
		}
		se->dispose(se);
	}

	return extra->prev_dispose != NULL ? extra->prev_dispose(event) : true;
}

static void async_signal_callback_dispose(zend_async_event_callback_t *callback, zend_async_event_t *event)
{
	async_signal_callback_t *const signal_cb = (async_signal_callback_t *) callback;

	if (signal_cb->cancellation_obj != NULL) {
		OBJ_RELEASE(signal_cb->cancellation_obj);
		signal_cb->cancellation_obj = NULL;
	}

	efree(callback);
}

static void async_signal_cancellation_callback_fn(zend_async_event_t *event,
												  zend_async_event_callback_t *callback,
												  void *result,
												  zend_object *exception)
{
	async_signal_callback_t *signal_cb = (async_signal_callback_t *) callback;

	if (ZEND_FUTURE_IS_COMPLETED(signal_cb->future)) {
		return;
	}

	/* Stop and dispose signal event */
	zend_async_event_t *signal_event = &signal_cb->signal_event->base;
	/* Clear future-side back-reference first so async_signal_future_dispose()
	 * doesn't try to dispose an already-freed signal_event. */
	ASYNC_SIGNAL_FUTURE_EXTRA(signal_cb->future)->signal_event = NULL;
	signal_cb->signal_event = NULL;
	signal_event->stop(signal_event);
	signal_event->dispose(signal_event);

	/* Reject with cancellation exception */
	if (exception != NULL) {
		ZEND_FUTURE_REJECT(signal_cb->future, exception);
	} else {
		zend_object *cancel_ex = async_new_exception(async_ce_cancellation_exception, "Signal wait cancelled");
		ZEND_FUTURE_REJECT(signal_cb->future, cancel_ex);
		OBJ_RELEASE(cancel_ex);
	}

	/* Release the cancellation object reference to break the circular reference:
	 * cancel_cb->cancellation_obj → timeout object → timeout event → cancel_cb.
	 * Without this, the timeout object can never be freed. */
	if (signal_cb->cancellation_obj != NULL) {
		OBJ_RELEASE(signal_cb->cancellation_obj);
		signal_cb->cancellation_obj = NULL;
	}
}

static void async_signal_event_callback_fn(zend_async_event_t *event,
										   zend_async_event_callback_t *callback,
										   void *result,
										   zend_object *exception)
{
	async_signal_callback_t *signal_cb = (async_signal_callback_t *) callback;

	if (ZEND_FUTURE_IS_COMPLETED(signal_cb->future)) {
		return;
	}

	/* Remove cancellation callback if set (dispose will release cancellation_obj) */
	if (signal_cb->cancellation_callback != NULL && signal_cb->cancellation_event != NULL) {
		signal_cb->cancellation_event->del_callback(signal_cb->cancellation_event, signal_cb->cancellation_callback);
		signal_cb->cancellation_callback = NULL;
		signal_cb->cancellation_event = NULL;
	}

	/* Stop signal event (one-shot) */
	zend_async_event_t *signal_event = &signal_cb->signal_event->base;
	signal_event->stop(signal_event);

	if (UNEXPECTED(exception != NULL)) {
		ZEND_FUTURE_REJECT(signal_cb->future, exception);
	} else {
		/* Resolve with Signal enum case — translate native signum back to the
		 * Linux numbering the enum is keyed on. */
		const int native_signum = signal_cb->signal_event->signal;
		const int enum_signum = async_signum_native_to_enum(native_signum);
		zend_object *enum_case = NULL;

		if (EXPECTED(zend_enum_get_case_by_value(&enum_case, async_ce_signal, (zend_long) enum_signum, NULL, false) ==
					 SUCCESS)) {
			zval result_zval;
			ZVAL_OBJ(&result_zval, enum_case);
			ZEND_FUTURE_COMPLETE(signal_cb->future, &result_zval);
		} else {
			zend_object *err = async_new_exception(NULL, "Unknown signal number: %d", native_signum);
			ZEND_FUTURE_REJECT(signal_cb->future, err);
			OBJ_RELEASE(err);
		}
	}

	/* Clear future-side back-reference before disposing signal_event. */
	ASYNC_SIGNAL_FUTURE_EXTRA(signal_cb->future)->signal_event = NULL;

	/* Dispose signal event */
	signal_event->dispose(signal_event);
	signal_cb->signal_event = NULL;
}

PHP_FUNCTION(Async_signal)
{
	zend_object *signal_enum = NULL;
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(1, 2)
	Z_PARAM_OBJ_OF_CLASS(signal_enum, async_ce_signal)
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_completable)
	ZEND_PARSE_PARAMETERS_END();

	SCHEDULER_LAUNCH;

	/* Extract backing int value from Signal enum and translate to the OS-native
	 * signal number — the enum bakes Linux numbers; SIGUSR1/SIGUSR2 differ on
	 * Darwin/FreeBSD. See async_signum_enum_to_native() in zend_common.h. */
	const zval *backing_value = zend_enum_fetch_case_value(signal_enum);
	const int signum = async_signum_enum_to_native((int) Z_LVAL_P(backing_value));

	/* If cancellation is already completed, return a rejected Future */
	if (cancellation != NULL) {
		zend_async_event_t *const cancel_event = ZEND_ASYNC_OBJECT_TO_EVENT(cancellation);

		if (ZEND_ASYNC_EVENT_IS_CLOSED(cancel_event)) {
			zend_future_t *const future = async_new_future(false, 0);
			if (UNEXPECTED(future == NULL)) {
				async_throw_error("Failed to create future for signal");
				RETURN_THROWS();
			}

			zend_object *cancel_exception = NULL;
			ZEND_ASYNC_EVENT_EXTRACT_RESULT_OR_ERROR(cancel_event, return_value, &cancel_exception);

			if (cancel_exception == NULL) {
				cancel_exception = async_new_exception(async_ce_cancellation_exception, "Signal wait cancelled");
				ZEND_FUTURE_REJECT(future, cancel_exception);
				OBJ_RELEASE(cancel_exception);
			} else {
				ZEND_FUTURE_REJECT(future, cancel_exception);
			}

			zend_object *const future_obj = async_new_future_obj(future);
			if (UNEXPECTED(future_obj == NULL)) {
				RETURN_THROWS();
			}

			RETURN_OBJ(future_obj);
		}
	}

	/* 1. Create signal event — may fail, nothing to clean up yet */
	zend_async_signal_event_t *const signal_event = ZEND_ASYNC_NEW_SIGNAL_EVENT(signum);
	if (UNEXPECTED(signal_event == NULL)) {
		async_throw_error("Failed to create signal event for signal %d", signum);
		RETURN_THROWS();
	}

	/* 2. Create signal callback — ecalloc never fails (aborts on OOM) */
	async_signal_callback_t *const signal_cb = ecalloc(1, sizeof(async_signal_callback_t));
	signal_cb->base.callback = async_signal_event_callback_fn;
	signal_cb->base.dispose = async_signal_callback_dispose;
	signal_cb->signal_event = signal_event;

	/* 3. Create future — if fails, clean up signal event and callback.
	 * Reserve extra space for async_signal_future_extra_t so the future can
	 * tear down signal_event from its own dispose path (covers the case where
	 * the Future PHP object is freed before signal/cancellation fired — e.g.
	 * after await_any_or_fail() picks a different future). */
	zend_future_t *const future = async_new_future(false, sizeof(async_signal_future_extra_t));
	if (UNEXPECTED(future == NULL)) {
		efree(signal_cb);
		signal_event->base.dispose(&signal_event->base);
		async_throw_error("Failed to create future for signal");
		RETURN_THROWS();
	}

	/* Wire the future-side guard: hold the signal_event and chain dispose. */
	async_signal_future_extra_t *const future_extra = ASYNC_SIGNAL_FUTURE_EXTRA(future);
	future_extra->signal_event = signal_event;
	future_extra->prev_dispose = future->event.dispose;
	future->event.dispose = async_signal_future_dispose;

	signal_cb->future = future;

	/* Add callback to signal event */
	signal_event->base.add_callback(&signal_event->base, &signal_cb->base);

	/* Wire cancellation if provided */
	if (cancellation != NULL) {
		zend_async_event_t *const cancel_event = ZEND_ASYNC_OBJECT_TO_EVENT(cancellation);

		/* Hold a reference to cancellation object so it stays alive */
		GC_ADDREF(cancellation);

		async_signal_callback_t *const cancel_cb = ecalloc(1, sizeof(async_signal_callback_t));
		cancel_cb->base.callback = async_signal_cancellation_callback_fn;
		cancel_cb->base.dispose = async_signal_callback_dispose;
		cancel_cb->future = future;
		cancel_cb->signal_event = signal_event;
		cancel_cb->cancellation_obj = cancellation;

		cancel_event->add_callback(cancel_event, &cancel_cb->base);

		signal_cb->cancellation_callback = &cancel_cb->base;
		signal_cb->cancellation_event = cancel_event;
	}

	/* Start cancellation event — if fails, destroy everything and throw */
	if (cancellation != NULL) {
		zend_async_event_t *const cancel_event = ZEND_ASYNC_OBJECT_TO_EVENT(cancellation);

		if (UNEXPECTED(!cancel_event->start(cancel_event))) {
			signal_event->base.dispose(&signal_event->base);
			RETURN_THROWS();
		}
	}

	zend_object *const future_obj = async_new_future_obj(future);
	if (UNEXPECTED(future_obj == NULL)) {
		signal_event->base.dispose(&signal_event->base);
		RETURN_THROWS();
	}

	/* Start signal event — if fails, reject future and return it */
	if (UNEXPECTED(!signal_event->base.start(&signal_event->base))) {
		zend_object *exception = NULL;
		if (EG(exception)) {
			exception = EG(exception);
			GC_ADDREF(exception);
			zend_clear_exception();
		} else {
			exception = async_new_exception(NULL, "Failed to start signal event for signal %d", signum);
		}

		ZEND_FUTURE_REJECT(future, exception);
		OBJ_RELEASE(exception);
		signal_event->base.dispose(&signal_event->base);
		RETURN_OBJ(future_obj);
	}

	RETURN_OBJ(future_obj);
}

PHP_METHOD(Async_Timeout, __construct)
{
	async_throw_error("Timeout cannot be constructed directly");
}

PHP_METHOD(Async_Timeout, cancel)
{
	zend_object *cancellation = NULL;

	ZEND_PARSE_PARAMETERS_START(0, 1)
	Z_PARAM_OPTIONAL
	Z_PARAM_OBJ_OF_CLASS_OR_NULL(cancellation, async_ce_cancellation_exception);
	ZEND_PARSE_PARAMETERS_END();

	async_timeout_object_t *timeout = ASYNC_TIMEOUT_FROM_OBJ(Z_OBJ_P(ZEND_THIS));

	if (timeout->event != NULL) {
		zend_async_timer_event_t *timer_event = timeout->event;
		/* Mirror async_timeout_destroy_object(): clear timeout_ext->std before
		 * dispose() so async_timeout_event_dispose() does NOT OBJ_RELEASE the
		 * object. In the current architecture the event holds only a raw
		 * pointer, not a counted reference, so releasing here would drop the
		 * caller's live ref and leave userland $t dangling — tripping
		 * IS_OBJ_VALID at shutdown. */
		async_timeout_ext_t *timeout_ext = ASYNC_TIMEOUT_FROM_EVENT(&timer_event->base);
		timeout_ext->std = NULL;
		timeout->event = NULL;
		timer_event->base.dispose(&timer_event->base);
	}
}

PHP_METHOD(Async_Timeout, isCompleted)
{
	ZEND_PARSE_PARAMETERS_NONE();

	async_timeout_object_t *timeout = ASYNC_TIMEOUT_FROM_OBJ(Z_OBJ_P(ZEND_THIS));

	RETURN_BOOL(timeout->event == NULL || ZEND_ASYNC_EVENT_IS_CLOSED(&timeout->event->base));
}

PHP_METHOD(Async_Timeout, isCancelled)
{
	ZEND_PARSE_PARAMETERS_NONE();

	/* Timeout does not track cancellation separately; it is either active or completed */
	async_timeout_object_t *timeout = ASYNC_TIMEOUT_FROM_OBJ(Z_OBJ_P(ZEND_THIS));

	RETURN_BOOL(timeout->event == NULL);
}

///////////////////////////////////////////////////////////////
/// Register Async Module
///////////////////////////////////////////////////////////////

ZEND_DECLARE_MODULE_GLOBALS(async)

void async_register_awaitable_ce(void)
{
	async_ce_awaitable = register_class_Async_Awaitable();
	async_ce_completable = register_class_Async_Completable(async_ce_awaitable);
}

void async_register_circuit_breaker_ce(void)
{
	async_ce_circuit_breaker_state = register_class_Async_CircuitBreakerState();
	async_ce_circuit_breaker = register_class_Async_CircuitBreaker();
	async_ce_circuit_breaker_strategy = register_class_Async_CircuitBreakerStrategy();
}

static zend_object_handlers async_timeout_handlers;

static void async_timeout_destroy_object(zend_object *object)
{
	async_timeout_object_t *timeout = ASYNC_TIMEOUT_FROM_OBJ(object);

	if (timeout->event != NULL) {
		zend_async_timer_event_t *timer_event = timeout->event;
		async_timeout_ext_t *timeout_ext = ASYNC_TIMEOUT_FROM_EVENT(&timer_event->base);
		timeout_ext->std = NULL;
		timeout->event = NULL;

		timer_event->base.dispose(&timer_event->base);
	}
}

static bool async_timeout_event_dispose(zend_async_event_t *event)
{
	async_timeout_ext_t *timeout = ASYNC_TIMEOUT_FROM_EVENT(event);

	if (timeout->std) {
		zend_object *object = timeout->std;
		async_timeout_object_t *timeout_object = ASYNC_TIMEOUT_FROM_OBJ(object);
		ZEND_ASSERT((timeout_object->event == NULL || timeout_object->event == (zend_async_timer_event_t *) event) &&
					"Event object mismatch");
		timeout_object->event = NULL;
		timeout->std = NULL;
		OBJ_RELEASE(object);
	}

	if (timeout->prev_dispose) {
		timeout->prev_dispose(event);
	}

	return true;
}

static void timeout_before_notify_handler(zend_async_event_t *event, void *result, zend_object *exception)
{
	if (UNEXPECTED(exception != NULL)) {
		ZEND_ASYNC_CALLBACKS_NOTIFY_FROM_HANDLER(event, result, exception);
		return;
	}

	// Here we override the exception value with a timeout exception.
	zend_object *timeout_exception = async_new_exception(async_ce_timeout_exception,
														 "Timeout occurred after %lu milliseconds",
														 ((zend_async_timer_event_t *) event)->timeout);

	ZEND_ASYNC_CALLBACKS_NOTIFY_FROM_HANDLER(event, result, timeout_exception);
	OBJ_RELEASE(timeout_exception);
}

static zend_object *async_timeout_create(const zend_ulong ms, const bool is_periodic)
{
	async_timeout_object_t *object = zend_object_alloc(sizeof(async_timeout_object_t), async_ce_timeout);

	zend_object_std_init(&object->std, async_ce_timeout);
	object_properties_init(&object->std, async_ce_timeout);

	if (UNEXPECTED(EG(exception) != NULL)) {
		efree(object);
		return NULL;
	}

	object->std.handlers = &async_timeout_handlers;

	zend_async_event_t *event =
			(zend_async_event_t *) ZEND_ASYNC_NEW_TIMER_EVENT_EX(ms, is_periodic, sizeof(async_timeout_ext_t));

	if (UNEXPECTED(event == NULL)) {
		efree(object);
		return NULL;
	}

	// A timeout() may be armed mid-tick after synchronous CPU work; refresh the
	// reactor clock at arm time so its deadline is not computed from a stale clock.
	ZEND_ASYNC_TIMER_SET_REFRESH_CLOCK((zend_async_timer_event_t *) event);

	ZEND_ASYNC_EVENT_REF_SET(object, offsetof(async_timeout_object_t, std), (zend_async_timer_event_t *) event);
	// A special flag is set to indicate that the event will contain a reference to a Zend object.
	ZEND_ASYNC_EVENT_WITH_OBJECT_REF(event);

	// Cast the event to the extended type.
	async_timeout_ext_t *timeout = ASYNC_TIMEOUT_FROM_EVENT(event);
	// Store the event in the object.
	timeout->std = &object->std;
	// Define own dispose handler for the event.
	timeout->prev_dispose = event->dispose;

	event->notify_handler = timeout_before_notify_handler;
	event->dispose = async_timeout_event_dispose;

	return &object->std;
}

static zend_object *async_timeout_object_create(zend_class_entry *ce)
{
	async_timeout_object_t *object = zend_object_alloc(sizeof(async_timeout_object_t), ce);

	zend_object_std_init(&object->std, ce);
	object_properties_init(&object->std, ce);

	object->std.handlers = &async_timeout_handlers;
	object->event = NULL;

	return &object->std;
}

void async_register_timeout_ce(void)
{
	async_ce_timeout = register_class_Async_Timeout(async_ce_completable);

	async_ce_timeout->create_object = async_timeout_object_create;

	async_timeout_handlers = std_object_handlers;

	async_timeout_handlers.offset = offsetof(async_timeout_object_t, std);
	async_timeout_handlers.dtor_obj = async_timeout_destroy_object;
}

static PHP_GINIT_FUNCTION(async)
{
#if defined(COMPILE_DL_ASYNC) && defined(ZTS)
	ZEND_TSRMLS_CACHE_UPDATE();
#endif

	async_globals->reactor_started = false;
	async_globals->signal_handlers = NULL;
	async_globals->signal_events = NULL;
	async_globals->process_events = NULL;
	/* Maximum number of coroutines in the concurrent iterator */
	async_globals->default_concurrency = 32;

	/* Initialize reactor execution optimization */
	async_globals->last_reactor_tick = 0;

	/* Debug deadlock diagnostics enabled by default */
	async_globals->debug_deadlock = true;

#ifdef PHP_WIN32
	async_globals->watcherThread = NULL;
	async_globals->ioCompletionPort = NULL;
	async_globals->countWaitingDescriptors = 0;
	zend_atomic_bool_init(&async_globals->isRunning, false);
	async_globals->uvloop_wakeup = NULL;
	async_globals->pid_queue = NULL;
#endif
}

/* {{{ PHP_GSHUTDOWN_FUNCTION */
static PHP_GSHUTDOWN_FUNCTION(async)
{
#ifdef PHP_WIN32
#endif
} /* }}} */

/* INI entries */

PHP_INI_BEGIN()
STD_PHP_INI_BOOLEAN(
		"async.debug_deadlock", "1", PHP_INI_ALL, OnUpdateBool, debug_deadlock, zend_async_globals, async_globals)
PHP_INI_END()

/* Module registration */

/* {{{ async_before_fork */
/* Refuse to fork with any non-main coroutine alive: its in-flight reactor state
 * and worker threads cannot survive fork(). Runs in the parent; throws on refusal. */
static bool async_before_fork(void)
{
	if (ZEND_ASYNC_IS_OFF) {
		return true;
	}

	zend_coroutine_t *coroutine;
	ZEND_HASH_FOREACH_PTR(&ASYNC_G(coroutines), coroutine)
	{
		if (coroutine == NULL || ZEND_COROUTINE_IS_MAIN(coroutine) ||
			coroutine == ZEND_ASYNC_SCHEDULER) {
			continue;
		}

		zend_throw_error(NULL,
				"Cannot fork() while coroutines other than the main one are running. "
				"fork() is only allowed when just the main coroutine is active.");
		return false;
	}
	ZEND_HASH_FOREACH_END();

	return true;
}
/* }}} */

ZEND_MINIT_FUNCTION(async)
{
	REGISTER_INI_ENTRIES();
	async_register_awaitable_ce();
	async_register_timeout_ce();
	async_register_scope_ce();
	async_register_coroutine_ce();
	// Must follow the exceptions: ContextException derives from AsyncException.
	async_register_exceptions_ce();
	async_register_context_ce();
	async_register_channel_ce();
	async_register_thread_channel_ce();
	async_register_thread_pool_ce();
	async_register_fs_watcher_ce();
	async_register_circuit_breaker_ce();
	async_ce_signal = register_class_Async_Signal();
	async_register_pool_ce();
	async_register_task_group_ce();
	async_register_task_set_ce();
	async_register_future_ce();
	async_register_thread_ce();
	async_ce_cpu_snapshot = register_class_Async_CpuSnapshot();
	async_cpu_info_module_init();

	async_scheduler_startup();
	async_api_register();
	async_pool_api_register();
	async_libuv_reactor_register();
	zend_async_fork_register(async_before_fork, libuv_after_fork_child);

	return SUCCESS;
}

ZEND_MSHUTDOWN_FUNCTION(async)
{
	UNREGISTER_INI_ENTRIES();
	async_cpu_info_module_shutdown();

	return SUCCESS;
}

PHP_MINFO_FUNCTION(async)
{
	php_info_print_table_start();
	php_info_print_table_header(2, "Module", PHP_ASYNC_NAME);
	php_info_print_table_row(2, "Version", PHP_ASYNC_VERSION);
	php_info_print_table_row(2, "Support", "Enabled");
	php_info_print_table_row(2, "LibUv Reactor", "Enabled");
#ifdef ZEND_ASYNC_FUZZ
	/* Tests that arm a chaos hook read this row to decide whether to skip. */
	php_info_print_table_row(2, "Chaos hooks", "Enabled");
#endif
	php_info_print_table_end();

	DISPLAY_INI_ENTRIES();
}

PHP_RSHUTDOWN_FUNCTION(async)
{
	async_cpu_usage_reset_state();

	return SUCCESS;
}

PHP_RINIT_FUNCTION(async) /* {{{ */
{
	// async_host_name_list_ctor();
	ZEND_ASYNC_INITIALIZE;
	circular_buffer_ctor(&ASYNC_G(microtasks), 64, sizeof(zend_async_microtask_t *), &zend_std_allocator);
	circular_buffer_ctor(&ASYNC_G(coroutine_queue), 128, sizeof(zend_coroutine_t *), &zend_std_allocator);
	circular_buffer_ctor(&ASYNC_G(resumed_coroutines), 64, sizeof(zend_coroutine_t *), &zend_std_allocator);
	zend_hash_init(&ASYNC_G(coroutines), 128, NULL, NULL, 0);
	zend_hash_init(&ASYNC_G(deadlock_channels), 8, NULL, NULL, 0);
	zend_hash_init(&ASYNC_G(thread_channels), 8, NULL, NULL, 0);

	ASYNC_G(reactor_started) = false;

#ifdef ZEND_ASYNC_FUZZ
	async_fuzz_init(&ASYNC_G(fuzz));
#endif

	return SUCCESS;
} /* }}} */

zend_module_entry async_module_entry = { STANDARD_MODULE_HEADER,
										 PHP_ASYNC_NAME,
										 ext_functions,
										 PHP_MINIT(async),
										 PHP_MSHUTDOWN(async),
										 PHP_RINIT(async),
										 PHP_RSHUTDOWN(async),
										 PHP_MINFO(async),
										 PHP_ASYNC_VERSION,
										 PHP_MODULE_GLOBALS(async),
										 PHP_GINIT(async),
										 PHP_GSHUTDOWN(async),
										 NULL,
										 STANDARD_MODULE_PROPERTIES_EX };

#ifdef COMPILE_DL_ASYNC
ZEND_GET_MODULE(async)
#endif