Adds docs.

docs/worker.md

@@ -179,3 +179,49 @@ $handler = static function () use ($workerServer) {
 
 // ...
 ```
+
+## Task workers
+
+`workers` are used to handle HTTP requests, but FrankenPHP also supports `task workers` that can handle
+asynchronous tasks in the background. Task workers can also be used to just execute a script in a loop.
+
+```caddyfile
+frankenphp {
+    task_worker {
+        name my-task-worker # name of the task worker
+        file /path/to/task-worker.php # path to the script to run
+        num 4 # number of task workers to start
+        args arg1 arg2 # args to pass to the script (to simulate $argv in cli mode)
+    }
+}
+```
+
+Tasks workers may call `frankenphp_handle_task()` to wait for a task to be assigned to them. Tasks
+may be dispatched from anywhere in the process using `frankenphp_dispatch_task()`.
+
+```php
+<?php
+// task-worker.php
+
+// setup code here, run once at worker startup
+
+$handleTask = function (string $task) {
+    // do something with the task
+};
+
+$maxTasksBeforeRestarting = 1000;
+$currentTask = 0;
+while(frankenphp_handle_task($handleTask) && $currentTask++ < $maxTasksBeforeRestarting) {
+    // Keep handling tasks until there are no more tasks or the max limit is reached
+}
+```
+
+```php
+<?php
+// some-script.php
+$task = 'do something';
+$workerName = 'my-task-worker'; // name of the task worker to dispatch the task to (first worker if left empty)
+frankenphp_dispatch_task($task, $workerName);
+```
+
+`frankenphp_dispatch_task` is non-blocking and returns immediately.

testdata/tasks/task-worker.php

@@ -1,14 +1,14 @@
 <?php
 
-$handleFunc = function ($task) {
+$handleFunc = function (string $task) {
     echo "$task";
     echo $_SERVER['CUSTOM_VAR'] ?? 'no custom var';
     echo join(' ', $_SERVER['argv']);
 };
 
-$maxRequests = 1000;
-$currentRequest = 0;
+$maxTasksBeforeRestarting = 1000;
+$currentTask = 0;
 
-while(frankenphp_handle_task($handleFunc) && $currentRequest++ < $maxRequests) {
+while(frankenphp_handle_task($handleFunc) && $currentTask++ < $maxTasksBeforeRestarting) {
     // Keep handling tasks until there are no more tasks or the max limit is reached
 }

threadtaskworker.go

@@ -25,7 +25,8 @@ type taskWorker struct {
 	argc        C.int
 }
 
-// representation of a thread that handles tasks directly assigned by go
+// representation of a thread that handles tasks directly assigned by go or via frankenphp_dispatch_task()
+// can also just execute a script in a loop
 // implements the threadHandler interface
 type taskWorkerThread struct {
 	thread       *phpThread