document worker mode for extensions

Author: realFlowControl

docs/worker.md

@@ -179,3 +179,13 @@ $handler = static function () use ($workerServer) {
 
 // ...
 ```
+
+## Worker mode for extension developers
+
+### Request lifecycle
+
+In worker mode FrankenPHP only goes through `RINIT` and `RSHUTDOWN` once per worker thread. In case you need to observe a worker request start and end, you can not rely on `RINIT` and `RSHUTDOWN` phases of the extension lifecycle. Instead, you are able to hook into the `sapi_module.activate` / `sapi_module.deactivate` function pointers to achieve the same effect (you can validate that the current SAPI is FrankenPHP by checking the value of `sapi_module.name`).
+
+Upon entering the `frankenphp_handle_request()` function, FrankenPHP calls `sapi_deactivate()` in internals which calls the `sapi_module.deactivate` hook if initialized and finaly blocks until a request arrives. Once a request arrives for the worker to handle, FrankenPHP calls `sapi_activate()` in internals which calls the `sapi_module.activate` hook if initialized.
+
+Be aware that FrankenPHP worker mode injects a dummy request to start the worker even before the first request arrives.

frankenphp.c

@@ -122,7 +122,12 @@ static void frankenphp_release_temporary_streams() {
   ZEND_HASH_FOREACH_END();
 }
 
-/* Adapted from php_request_shutdown */
+/* Adapted from php_request_shutdown
+ * This mimics the RSHUTDOWN phase from PHP for the worker mode. In case you
+ * need to observe the end of a request being handled, you can hook into the
+ * `sapi_module.deactivate` function pointer which gets called from
+ * `sapi_deactivate()`.
+ * */
 static void frankenphp_worker_request_shutdown() {
   /* Flush all output buffers */
   zend_try { php_output_end_all(); }
@@ -170,7 +175,12 @@ void frankenphp_add_assoc_str_ex(zval *track_vars_array, char *key,
   add_assoc_str_ex(track_vars_array, key, keylen, val);
 }
 
-/* Adapted from php_request_startup() */
+/* Adapted from php_request_startup()
+ * This mimics the RINIT phase from PHP for the worker mode. In case you need to
+ * observe a new request being handled, you can hook into the
+ * `sapi_module.activate` function pointer which gets called from
+ * `sapi_activate()`.
+ * */
 static int frankenphp_worker_request_startup() {
   int retval = SUCCESS;