Skip to content

Commit 66095b9

Browse files
committed
Provide README on task IDs
1 parent a2f9ce9 commit 66095b9

File tree

1 file changed

+27
-0
lines changed

1 file changed

+27
-0
lines changed

README.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,33 @@ Some tips:
8989
- Use short but frequent sleeps instead.
9090
- Avoid using `SIGINT`! On Unix, this signal is reserved for timeout detection.
9191

92+
### Task IDs
93+
You can assign task IDs to tasks before they are run, but you cannot change them after the tasks are started. This allows you to track the statuses of long-running tasks across web requests.
94+
95+
By default, if a task does not has its user-specified task ID when starting, a ULID will be generated as its task ID.
96+
97+
```php
98+
// create a task with a specified task ID...
99+
$task = new AsyncTask(function () {}, "customTaskID");
100+
101+
// will return a status object for immediate checking...
102+
$status = $task->start();
103+
104+
// in case the task ID was not given, what is the generated task ID?
105+
$taskID = $status->taskID;
106+
107+
// is that task still running?
108+
$status->isRunning();
109+
110+
// when task IDs are known, task status objects can be recreated on-the-fly
111+
$anotherStatus = new AsyncTaskStatus();
112+
```
113+
114+
Some tips:
115+
- Task IDs can be optional (i.e. `null`) but CANNOT be blank (i.e. `""`)!
116+
- If multiple tasks are started with the same task ID, then the task status object will only track the first task that was started
117+
- Known issue: on Windows, checking task statuses can be slow (about 0.5 - 1 seconds) due to underlying bottlenecks
118+
92119
## Testing
93120
PHPUnit via Composer script:
94121
```sh

0 commit comments

Comments
 (0)