From 77fec2b4a72db1f75ecebeffdbbc987ab77c8db8 Mon Sep 17 00:00:00 2001
From: Alliballibaba <alliballibaba@gmail.com>
Date: Tue, 7 Oct 2025 21:23:40 +0200
Subject: [PATCH] Adds docs.

---
 docs/worker.md                 | 46 ++++++++++++++++++++++++++++++++++
 testdata/tasks/task-worker.php |  8 +++---
 threadtaskworker.go            |  3 ++-
 3 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/docs/worker.md b/docs/worker.md
index 81c18266..64aed5c1 100644
--- a/docs/worker.md
+++ b/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.
diff --git a/testdata/tasks/task-worker.php b/testdata/tasks/task-worker.php
index bf2a1684..c2c283f2 100644
--- a/testdata/tasks/task-worker.php
+++ b/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
 }
\ No newline at end of file
diff --git a/threadtaskworker.go b/threadtaskworker.go
index f7b5e35e..d3bb184d 100644
--- a/threadtaskworker.go
+++ b/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