Add the Async Scheduler Hook API: a thin, policy-free concurrency core

The engine gains the ability to activate a concurrent execution mode.
A scheduler - a C extension or a PHP library - registers a set of
hooks through a single call and takes control of concurrency. The core
contains NO implementation: no scheduler, no queues, no event system;
it is hook routing plus the minimal mechanism only the engine can
perform (context switching, the GC destructor walker, the coroutine
lifecycle status).

Core ABI (Zend/zend_async_API.h):

  - zend_coroutine_t: lifecycle status packed into the flags word,
    modifier flags, object_offset for the single-allocation embed
    pattern (or a stored object pointer via OBJ_REF), an awaiting_info
    diagnostics hook. No embedded wait state.
  - scheduler slots registered once per process via a versioned struct:
    new_coroutine, enqueue_coroutine, suspend(from_main, is_bailout),
    resume, cancel, launch, shutdown, get_class_ce, call_on_main_stack,
    context accessors (userland zval keys + internal numeric keys with
    a core-owned key registry), intercept_fiber, gc_destructors, defer.
  - zend_async_microtask_t: a thin one-shot task (handler, dtor, 32-bit
    ref_count, named flag bits incl. is_cancelled). The queue is
    provider-owned; the defer slot only routes the pointer.
  - per-thread globals: state, current/main coroutine, live coroutine
    count, the in_scheduler_context flag, the PHP bridge hook storage.

Engine integration:

  - the scheduler is not lazy: it launches right before the script code
    runs (main.c, phpdbg) and receives the after-main handover; after
    destructors the API deactivates.
  - fibers: intercept_fiber links a fiber to a coroutine (the hook
    returns the coroutine to bind, created by the scheduler, or NULL
    for the legacy low-level path). There is NO switching API: inside
    scheduler code (in_scheduler_context, set around hook invocations)
    the plain Fiber API on a bound fiber performs the direct context
    switch; in application code the same calls park the value and
    route through the hooks. Deferred starts take an owned deep copy
    of their arguments. Fiber::suspend() is unchanged.
  - GC: the destructor phase is an around-interceptor. The engine keeps
    the walker, the once-per-object guarantee and the phase cursor, and
    re-runs missed destructors after the hook as a safety net; the hook
    brackets the run with provider logic (open a completion group, run,
    await everything the destructors spawned, transitively). Each
    destructor executes as application code (the scheduler flag is
    dropped around it). The executor reaches the hook as a Closure over
    an unregistered internal function - unreachable from application
    code.

PHP bridge (Zend/zend_scheduler_hook.c): final class Async\
SchedulerHook - hook-name constants, register(module, hooks) (throws
when a scheduler is already registered), getModule(), defer()
(forwards to the DEFER hook). Hooks are stored by numeric index in the
per-thread globals; each slot is backed by a C thunk forwarding to the
stored callable.

Tests (Zend/tests/async, 13): registration semantics, constants,
launch-at-registration, managed-fiber lifecycle through a plain-Fiber
scheduler loop (start/suspend/resume/finish, throw at the suspension
point, uncaught exception propagation, after-main drain, direct-
inside/routed-outside context semantics), low-level fibers untouched
by a null intercept, microtask forwarding, and a GC cycle whose
destructors spawn managed fibers awaited by the hook. Full async,
fibers and gc suites pass (194/194, debug build - leak-checked).

RFC and integration reference:
https://github.com/true-async/php-async-core-rfc

Author: EdmondDantes

Zend/tests/async/fiber_lowlevel_null.phpt

@@ -0,0 +1,34 @@
+--TEST--
+intercept_fiber returning null keeps the fiber on the low-level path
+--FILE--
+<?php
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => function (Fiber $fiber): ?object {
+        echo "intercept: null\n";
+        return null;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout): bool {
+        // Never called for the low-level fiber itself; the engine invokes it
+        // for the after-main handover (script end, then after destructors).
+        echo "suspend(fromMain: ", var_export($fromMain, true), ")\n";
+        return true;
+    },
+]);
+
+// A low-level fiber behaves exactly as classic Fiber even with a scheduler.
+$fiber = new Fiber(function (int $x): int {
+    $y = Fiber::suspend($x + 1);
+    return $y * 10;
+});
+
+var_dump($fiber->start(5));
+var_dump($fiber->resume(4));
+var_dump($fiber->getReturn());
+?>
+--EXPECT--
+intercept: null
+int(6)
+NULL
+int(40)
+suspend(fromMain: true)
+suspend(fromMain: true)

Zend/tests/async/fiber_managed_after_main.phpt

@@ -0,0 +1,50 @@
+--TEST--
+After-main handover runs deferred managed coroutines; abandoned ones die cleanly
+--FILE--
+<?php
+$queue = new SplQueue();
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => fn (Fiber $fiber): object
+        => new class($fiber) {
+            public function __construct(public readonly Fiber $fiber) {}
+        },
+    Async\SchedulerHook::ENQUEUE => function (object $coroutine) use ($queue): bool {
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout) use ($queue): bool {
+        // This scheduler defers everything: nothing runs until after main.
+        if (!$fromMain) {
+            return true;
+        }
+
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+        }
+
+        return true;
+    },
+]);
+
+$fiber = new Fiber(function (): void {
+    echo "ran after main\n";
+    Fiber::suspend();
+    echo "never printed: nobody resumes\n";
+});
+
+// The deferring scheduler does not run the fiber here.
+var_dump($fiber->start());
+var_dump($fiber->isStarted());
+
+echo "end of script\n";
+// After-main handover: the scheduler drains its queue, the fiber runs and
+// suspends. Nobody resumes it, so it is destroyed at shutdown without
+// completing; the second echo never happens.
+?>
+--EXPECT--
+NULL
+bool(false)
+end of script
+ran after main

Zend/tests/async/fiber_managed_basic.phpt

@@ -0,0 +1,62 @@
+--TEST--
+A fiber adopted by the scheduler runs through the coroutine path
+--FILE--
+<?php
+$queue = new SplQueue();
+$log = [];
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => function (Fiber $fiber) use (&$log): object {
+        $log[] = 'intercept';
+
+        // The scheduler defines the coroutine; here it simply remembers
+        // which fiber the coroutine drives.
+        return new class($fiber) {
+            public function __construct(public readonly Fiber $fiber) {}
+        };
+    },
+    Async\SchedulerHook::ENQUEUE => function (object $coroutine) use ($queue, &$log): bool {
+        $log[] = 'enqueue';
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::RESUME => function (object $coroutine, ?Throwable $error) use ($queue, &$log): bool {
+        $log[] = 'resume';
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout) use ($queue, &$log): bool {
+        $log[] = 'suspend';
+
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+
+            if (!$fromMain) {
+                return true;
+            }
+        }
+
+        return true;
+    },
+]);
+
+$fiber = new Fiber(function (int $x): int {
+    $y = Fiber::suspend($x + 1);
+    return $y * 10;
+});
+
+var_dump($fiber->start(5));
+var_dump($fiber->isSuspended());
+var_dump($fiber->resume(4));
+var_dump($fiber->isTerminated());
+var_dump($fiber->getReturn());
+echo implode(',', $log), "\n";
+?>
+--EXPECT--
+int(6)
+bool(true)
+NULL
+bool(true)
+int(40)
+intercept,enqueue,suspend,resume,suspend

Zend/tests/async/fiber_managed_throw.phpt

@@ -0,0 +1,52 @@
+--TEST--
+Fiber::throw() on a managed fiber delivers the exception at the suspension point
+--FILE--
+<?php
+$queue = new SplQueue();
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => fn (Fiber $fiber): object
+        => new class($fiber) {
+            public function __construct(public readonly Fiber $fiber) {}
+        },
+    Async\SchedulerHook::ENQUEUE => function (object $coroutine) use ($queue): bool {
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::RESUME => function (object $coroutine, ?Throwable $error) use ($queue): bool {
+        echo "resume hook error: ", $error === null ? 'none' : get_class($error), "\n";
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout) use ($queue): bool {
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+
+            if (!$fromMain) {
+                return true;
+            }
+        }
+
+        return true;
+    },
+]);
+
+$fiber = new Fiber(function (): string {
+    try {
+        Fiber::suspend('waiting');
+    } catch (RuntimeException $e) {
+        return 'caught: ' . $e->getMessage();
+    }
+
+    return 'not reached';
+});
+
+var_dump($fiber->start());
+$fiber->throw(new RuntimeException('boom'));
+var_dump($fiber->getReturn());
+?>
+--EXPECT--
+string(7) "waiting"
+resume hook error: RuntimeException
+string(12) "caught: boom"

Zend/tests/async/fiber_managed_uncaught.phpt

@@ -0,0 +1,44 @@
+--TEST--
+An uncaught exception in a managed fiber surfaces at the start()/resume() caller
+--FILE--
+<?php
+$queue = new SplQueue();
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => fn (Fiber $fiber): object
+        => new class($fiber) {
+            public function __construct(public readonly Fiber $fiber) {}
+        },
+    Async\SchedulerHook::ENQUEUE => function (object $coroutine) use ($queue): bool {
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout) use ($queue): bool {
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+
+            if (!$fromMain) {
+                return true;
+            }
+        }
+
+        return true;
+    },
+]);
+
+$fiber = new Fiber(function (): void {
+    throw new RuntimeException('escaped');
+});
+
+try {
+    $fiber->start();
+} catch (RuntimeException $e) {
+    echo "caught: ", $e->getMessage(), "\n";
+}
+
+var_dump($fiber->isTerminated());
+?>
+--EXPECT--
+caught: escaped
+bool(true)

Zend/tests/async/gc_destructors_hook.phpt

@@ -0,0 +1,86 @@
+--TEST--
+GC destructor phase: the hook brackets the engine run and awaits spawned work
+--FILE--
+<?php
+$queue = new SplQueue();
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::INTERCEPT_FIBER => fn (Fiber $fiber): object
+        => new class($fiber) {
+            public function __construct(public readonly Fiber $fiber) {}
+        },
+    Async\SchedulerHook::ENQUEUE => function (object $coroutine) use ($queue): bool {
+        $queue->enqueue($coroutine);
+        return true;
+    },
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout) use ($queue): bool {
+        // Defer: the queue is drained by the GC hook (and after main).
+        if (!$fromMain) {
+            return true;
+        }
+
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+        }
+
+        return true;
+    },
+    Async\SchedulerHook::GC_DESTRUCTORS => function (callable $run) use ($queue): bool {
+        echo "hook: before\n";
+
+        $run();     // the engine calls every pending destructor
+
+        // Await everything the destructors spawned (the "scope" logic:
+        // membership is the scheduler's own bookkeeping).
+        while (!$queue->isEmpty()) {
+            $fiber = $queue->dequeue()->fiber;
+            $fiber->isStarted() ? $fiber->resume() : $fiber->start();
+        }
+
+        echo "hook: after\n";
+        return true;
+    },
+]);
+
+class Node
+{
+    public ?Node $other = null;
+
+    public function __destruct()
+    {
+        echo "destructor\n";
+
+        // The destructor spawns concurrent work; the hook must wait for it.
+        $fiber = new Fiber(function (): void {
+            echo "spawned by destructor\n";
+        });
+        $fiber->start();
+    }
+}
+
+// A garbage cycle: collected only by the GC.
+$a = new Node();
+$b = new Node();
+$a->other = $b;
+$b->other = $a;
+unset($a, $b);
+
+// The GC reruns after the destructor phase: the finished fiber/coroutine
+// pairs collected there carry internal destructors, so the hook brackets
+// a second (empty) phase.
+$collected = gc_collect_cycles();
+var_dump($collected > 0);
+echo "end\n";
+?>
+--EXPECT--
+hook: before
+destructor
+destructor
+spawned by destructor
+spawned by destructor
+hook: after
+hook: before
+hook: after
+bool(true)
+end

Zend/tests/async/microtasks_basic.phpt

@@ -0,0 +1,43 @@
+--TEST--
+Microtasks: defer() forwards to the scheduler's DEFER hook; the queue is the scheduler's
+--FILE--
+<?php
+$tasks = new SplQueue();
+
+Async\SchedulerHook::register('test', [
+    Async\SchedulerHook::SUSPEND => function (bool $fromMain, bool $isBailout): bool {
+        return true;
+    },
+    Async\SchedulerHook::DEFER => function (callable $task) use ($tasks): bool {
+        // The queue is owned by the scheduler, not by the engine.
+        $tasks->enqueue($task);
+        return true;
+    },
+]);
+
+Async\SchedulerHook::defer(function () use ($tasks): void {
+    echo "task 1\n";
+
+    // Queued while draining: the scheduler decides the semantics; this
+    // one drains everything queued before it finishes (classic microtasks).
+    Async\SchedulerHook::defer(function (): void {
+        echo "task 3 (queued by task 1)\n";
+    });
+});
+
+Async\SchedulerHook::defer(function (): void {
+    echo "task 2\n";
+});
+
+// The scheduler drains its own queue on its tick; simulate one here.
+while (!$tasks->isEmpty()) {
+    ($tasks->dequeue())();
+}
+
+echo "drained\n";
+?>
+--EXPECT--
+task 1
+task 2
+task 3 (queued by task 1)
+drained