async: interface-based scheduler registration (Async\Scheduler + AbstractScheduler)

Author: EdmondDantes

Zend/zend_async_API.h

@@ -514,6 +514,9 @@ typedef struct {
 typedef struct {
 	bool active;
 	zend_string *module;
+	/* The registered Async\Scheduler instance; one ref held for the request.
+	 * The bound hook methods borrow this object. */
+	zend_object *scheduler;
 	php_async_hook_t hooks[PHP_ASYNC_HOOK_COUNT];
 } php_async_handlers_t;
 

Zend/zend_scheduler_hook.c

@@ -35,79 +35,67 @@
 #include "zend_exceptions.h"
 #include "zend_closures.h"
 
-/* The hook names, indexed by php_async_hook_id: used only to map the
- * incoming array keys (the Async\SchedulerHook class constants). */
+/* The Async\Scheduler method name for each hook (lower-cased, as stored in the
+ * class function table), indexed by php_async_hook_id. */
 static const struct {
 	const char *name;
 	size_t len;
-} php_async_hook_names[PHP_ASYNC_HOOK_COUNT] = {
+} php_async_hook_methods[PHP_ASYNC_HOOK_COUNT] = {
 	[PHP_ASYNC_HOOK_LAUNCH] = { ZEND_STRL("launch") },
 	[PHP_ASYNC_HOOK_SHUTDOWN] = { ZEND_STRL("shutdown") },
-	[PHP_ASYNC_HOOK_INTERCEPT_FIBER] = { ZEND_STRL("intercept_fiber") },
-	[PHP_ASYNC_HOOK_ENQUEUE] = { ZEND_STRL("enqueue_coroutine") },
+	[PHP_ASYNC_HOOK_INTERCEPT_FIBER] = { ZEND_STRL("interceptfiber") },
+	[PHP_ASYNC_HOOK_ENQUEUE] = { ZEND_STRL("enqueue") },
 	[PHP_ASYNC_HOOK_SUSPEND] = { ZEND_STRL("suspend") },
 	[PHP_ASYNC_HOOK_RESUME] = { ZEND_STRL("resume") },
 	[PHP_ASYNC_HOOK_CANCEL] = { ZEND_STRL("cancel") },
-	[PHP_ASYNC_HOOK_CONTEXT_FIND] = { ZEND_STRL("context_find") },
-	[PHP_ASYNC_HOOK_CONTEXT_SET] = { ZEND_STRL("context_set") },
-	[PHP_ASYNC_HOOK_CONTEXT_UNSET] = { ZEND_STRL("context_unset") },
+	[PHP_ASYNC_HOOK_CONTEXT_FIND] = { ZEND_STRL("contextfind") },
+	[PHP_ASYNC_HOOK_CONTEXT_SET] = { ZEND_STRL("contextset") },
+	[PHP_ASYNC_HOOK_CONTEXT_UNSET] = { ZEND_STRL("contextunset") },
 	[PHP_ASYNC_HOOK_DEFER] = { ZEND_STRL("defer") },
 };
 
+/* Class entries, filled by zend_register_scheduler_hook(). */
+static zend_class_entry *async_ce_Scheduler;
+static zend_class_entry *async_ce_AbstractScheduler;
+
 /* The storage lives in the per-thread async globals: correct under ZTS,
  * request-local by construction. */
 #define PHP_ASYNC_HANDLERS (ZEND_ASYNC_G(scheduler_hooks))
 #define PHP_ASYNC_HOOK(id) (&PHP_ASYNC_HANDLERS.hooks[(id)])
 
-/* Read the callable for `id` from the incoming array into storage. */
-static bool php_async_hook_take(HashTable *array, php_async_hook_id id)
+/* Bind hook `id` to the scheduler's method of the same name. A hook is
+ * considered "provided" only when the method is overridden below
+ * Async\AbstractScheduler; a method that resolves to AbstractScheduler is its
+ * inert default, so the engine keeps its own behaviour for that hook. */
+static void php_async_hook_bind(zend_object *scheduler, php_async_hook_id id)
 {
 	php_async_hook_t *hook = PHP_ASYNC_HOOK(id);
-	zval *entry = zend_hash_str_find(array, php_async_hook_names[id].name, php_async_hook_names[id].len);
+	zend_function *fn = zend_hash_str_find_ptr(&scheduler->ce->function_table,
+			php_async_hook_methods[id].name, php_async_hook_methods[id].len);
 
-	if (entry == NULL) {
+	if (fn == NULL || fn->common.scope == async_ce_AbstractScheduler) {
 		hook->set = false;
-		return true;
+		return;
 	}
 
-	char *error = NULL;
-
-	if (zend_fcall_info_init(entry, 0, &hook->fci, &hook->fcc, NULL, &error) != SUCCESS) {
-		zend_type_error("Async scheduler hook \"%s\" must be a valid callable: %s",
-				php_async_hook_names[id].name, error != NULL ? error : "unknown error");
-		if (error != NULL) {
-			efree(error);
-		}
-
-		return false;
-	}
+	memset(&hook->fci, 0, sizeof(hook->fci));
+	memset(&hook->fcc, 0, sizeof(hook->fcc));
 
-	if (error != NULL) {
-		efree(error);
-	}
+	hook->fci.size = sizeof(hook->fci);
+	hook->fci.object = scheduler;
+	ZVAL_UNDEF(&hook->fci.function_name);
 
-	/* Keep the callable alive for the whole request. */
-	Z_TRY_ADDREF(hook->fci.function_name);
-	if (hook->fci.object != NULL) {
-		GC_ADDREF(hook->fci.object);
-	}
+	hook->fcc.function_handler = fn;
+	hook->fcc.object = scheduler;
+	hook->fcc.called_scope = scheduler->ce;
 
 	hook->set = true;
-	return true;
 }
 
 static void php_async_hook_release(php_async_hook_t *hook)
 {
-	if (!hook->set) {
-		return;
-	}
-
-	zval_ptr_dtor(&hook->fci.function_name);
-
-	if (hook->fci.object != NULL) {
-		OBJ_RELEASE(hook->fci.object);
-	}
-
+	/* The scheduler object (and thus the bound method) is owned once by the
+	 * handlers container; nothing per-hook to release. */
 	hook->set = false;
 }
 
@@ -383,6 +371,11 @@ static void php_async_handlers_reset(void)
 		php_async_hook_release(PHP_ASYNC_HOOK(id));
 	}
 
+	if (PHP_ASYNC_HANDLERS.scheduler != NULL) {
+		OBJ_RELEASE(PHP_ASYNC_HANDLERS.scheduler);
+		PHP_ASYNC_HANDLERS.scheduler = NULL;
+	}
+
 	if (PHP_ASYNC_HANDLERS.module != NULL) {
 		zend_string_release(PHP_ASYNC_HANDLERS.module);
 		PHP_ASYNC_HANDLERS.module = NULL;
@@ -451,11 +444,11 @@ static void php_async_build_api(zend_async_scheduler_api_t *api)
 ZEND_METHOD(Async_SchedulerHook, register)
 {
 	zend_string *module;
-	HashTable *hooks;
+	zend_object *scheduler;
 
 	ZEND_PARSE_PARAMETERS_START(2, 2)
 		Z_PARAM_STR(module)
-		Z_PARAM_ARRAY_HT(hooks)
+		Z_PARAM_OBJ_OF_CLASS(scheduler, async_ce_Scheduler)
 	ZEND_PARSE_PARAMETERS_END();
 
 	/* A scheduler is registered once per process — by a C extension or by
@@ -466,12 +459,11 @@ ZEND_METHOD(Async_SchedulerHook, register)
 	}
 
 	for (php_async_hook_id id = 0; id < PHP_ASYNC_HOOK_COUNT; id++) {
-		if (!php_async_hook_take(hooks, id)) {
-			php_async_handlers_reset();
-			RETURN_THROWS();
-		}
+		php_async_hook_bind(scheduler, id);
 	}
 
+	PHP_ASYNC_HANDLERS.scheduler = scheduler;
+	GC_ADDREF(scheduler);
 	PHP_ASYNC_HANDLERS.module = zend_string_copy(module);
 	PHP_ASYNC_HANDLERS.active = true;
 
@@ -533,8 +525,64 @@ ZEND_METHOD(Async_SchedulerHook, defer)
 	}
 }
 
+/////////////////////////////////////////////////////////////////////
+/// Async\AbstractScheduler default hooks
+/////////////////////////////////////////////////////////////////////
+
+/* These bodies are the inert defaults: the bridge detects them by scope and
+ * keeps the engine's own behaviour instead of calling them. They only run when
+ * userland invokes them directly; the argument count/types are already checked
+ * against the arginfo at the call boundary, so the bodies just return. */
+
+ZEND_METHOD(Async_AbstractScheduler, interceptFiber)
+{
+	RETURN_NULL();
+}
+
+ZEND_METHOD(Async_AbstractScheduler, resume)
+{
+	RETURN_FALSE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, cancel)
+{
+	RETURN_FALSE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, defer)
+{
+	RETURN_FALSE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, launch)
+{
+	RETURN_TRUE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, shutdown)
+{
+	RETURN_TRUE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, contextFind)
+{
+	RETURN_NULL();
+}
+
+ZEND_METHOD(Async_AbstractScheduler, contextSet)
+{
+	RETURN_FALSE;
+}
+
+ZEND_METHOD(Async_AbstractScheduler, contextUnset)
+{
+	RETURN_FALSE;
+}
+
 void zend_register_scheduler_hook(void)
 {
+	async_ce_Scheduler = register_class_Async_Scheduler();
+	async_ce_AbstractScheduler = register_class_Async_AbstractScheduler(async_ce_Scheduler);
 	register_class_Async_SchedulerHook();
 }
 

Zend/zend_scheduler_hook.stub.php

@@ -4,45 +4,103 @@
 
 namespace Async;
 
+/**
+ * A scheduler plugs into the concurrent mode by implementing this interface
+ * and handing an instance to Async\SchedulerHook::register(). Each method is
+ * a scheduling *policy* hook; the engine performs the actual context switches.
+ *
+ * Extend Async\AbstractScheduler to implement only the hooks you need.
+ */
+interface Scheduler
+{
+    /** A coroutine became runnable (freshly created, or its wait ended). */
+    public function enqueue(object $coroutine): bool;
+
+    /** The current flow yields; pick who runs next and switch to them. */
+    public function suspend(bool $fromMain, bool $isBailout): bool;
+
+    /** A fiber is starting: return a coroutine object to adopt it, or null. */
+    public function interceptFiber(\Fiber $fiber): ?object;
+
+    /** Wake a suspended coroutine (deferred: enqueue it to run later). */
+    public function resume(object $coroutine, ?\Throwable $error = null): bool;
+
+    /** Cancel a coroutine. */
+    public function cancel(object $coroutine, ?\Throwable $error = null): bool;
+
+    /** Store a one-shot microtask on the scheduler's queue. */
+    public function defer(callable $task): bool;
+
+    /** Invoked once when the scheduler starts. */
+    public function launch(): bool;
+
+    /** A graceful shutdown has been requested. */
+    public function shutdown(): bool;
+
+    /** Look up a value in a coroutine context. */
+    public function contextFind(object $context, mixed $key, bool $includeParent): mixed;
+
+    /** Set a value in a coroutine context. */
+    public function contextSet(object $context, mixed $key, mixed $value): bool;
+
+    /** Remove a value from a coroutine context. */
+    public function contextUnset(object $context, mixed $key): bool;
+}
+
+/**
+ * Convenience base: only enqueue() and suspend() are required; every other
+ * hook has a default, so the engine keeps its own behaviour for the ones you
+ * do not override.
+ */
+abstract class AbstractScheduler implements Scheduler
+{
+    abstract public function enqueue(object $coroutine): bool;
+
+    abstract public function suspend(bool $fromMain, bool $isBailout): bool;
+
+    public function interceptFiber(\Fiber $fiber): ?object {}
+
+    public function resume(object $coroutine, ?\Throwable $error = null): bool {}
+
+    public function cancel(object $coroutine, ?\Throwable $error = null): bool {}
+
+    public function defer(callable $task): bool {}
+
+    public function launch(): bool {}
+
+    public function shutdown(): bool {}
+
+    public function contextFind(object $context, mixed $key, bool $includeParent): mixed {}
+
+    public function contextSet(object $context, mixed $key, mixed $value): bool {}
+
+    public function contextUnset(object $context, mixed $key): bool {}
+}
+
 /**
  * Activation point for the concurrent mode.
  *
- * A scheduler is registered by handing register() a map of hook name
- * (the class constants below) to callable. There is exactly one scheduler
- * per process, so the class is used only through its static methods.
+ * A scheduler is registered by handing register() an object that implements
+ * Async\Scheduler. There is exactly one scheduler per process, so the class
+ * is used only through its static methods.
  */
 final class SchedulerHook
 {
-    public const string LAUNCH = 'launch';
-    public const string SHUTDOWN = 'shutdown';
-    public const string INTERCEPT_FIBER = 'intercept_fiber';
-    public const string ENQUEUE = 'enqueue_coroutine';
-    public const string SUSPEND = 'suspend';
-    public const string RESUME = 'resume';
-    public const string CANCEL = 'cancel';
-    public const string CONTEXT_FIND = 'context_find';
-    public const string CONTEXT_SET = 'context_set';
-    public const string CONTEXT_UNSET = 'context_unset';
-    public const string DEFER = 'defer';
-
     /**
      * Registers a scheduler and activates the concurrent mode.
      *
-     * $hooks maps a hook constant to a callable; omitted hooks keep their
-     * defaults. A scheduler is registered once per process: calling this
-     * when a scheduler is already registered (by a C extension or by an
-     * earlier PHP call) throws an Error.
+     * A scheduler is registered once per process: calling this when a
+     * scheduler is already registered (by a C extension or by an earlier PHP
+     * call) throws an Error.
      */
-    public static function register(string $module, array $hooks): bool {}
+    public static function register(string $module, Scheduler $scheduler): bool {}
 
     /** Returns the module name of the registered scheduler, or null when none. */
     public static function getModule(): ?string {}
 
     /**
      * Queues a callable on the scheduler's microtask queue (one-shot,
-     * runs on the next tick). Forwards to the DEFER hook; the queue and
-     * its draining belong to the scheduler.
+     * runs on the next tick). Forwards to the scheduler's defer() hook.
      */
     public static function defer(callable $task): void {}
-
 }