Merge branch 'master' into serial

Author: Vectorial1024

CHANGELOG.md

@@ -1,7 +1,12 @@
 # Change Log of `laravel-process-async`
+Note: you may refer to `README.md` for description of features.
 
 ## Dev (WIP)
+- Task IDs can be given to tasks (generated or not) (https://github.com/Vectorial1024/laravel-process-async/issues/5)
+
+## 0.2.0 (2025-01-04)
 - Task runners are now detached from the task giver (https://github.com/Vectorial1024/laravel-process-async/issues/7)
+- Task runners can now have time limits (https://github.com/Vectorial1024/laravel-process-async/issues/1)
 
 ## 0.1.0 (2024-12-02)
 Initial release:

README.md

@@ -5,7 +5,7 @@
 [![PHP Dependency Version][php-version-image]][packagist-url]
 [![GitHub Repo Stars][github-stars-image]][github-repo-url]
 
-Utilize Laravel Processes to run PHP code asynchronously.
+Utilize Laravel Processes to run PHP code asynchronously, as if using Laravel Concurrency.
 
 ## What really is this?
 [Laravel Processes](https://laravel.com/docs/10.x/processes) was first introduced in Laravel 10. This library wraps around `Process::start()` to let you execute code in the background to achieve async, albeit with some caveats:
@@ -45,7 +45,7 @@ If you are on Unix, check that you also have the following:
 ## Change log
 Please see `CHANGELOG.md`.
 
-## Example code
+## Example code and features
 Tasks can be defined as PHP closures, or (recommended) as an instance of a class that implements `AsyncTaskInterface`.
 
 A very simple example task to write Hello World to a file:
@@ -54,10 +54,7 @@ A very simple example task to write Hello World to a file:
 // define the task...
 $target = "document.txt";
 $task = new AsyncTask(function () use ($target) {
-    $fp = fopen($target, "w");
-    fwrite($fp, "Hello World!!");
-    fflush($fp);
-    fclose($fp);
+    file_put_contents($target, "Hello World!");
 });
 
 // if you are using interfaces, then it is just like this:
@@ -87,6 +84,38 @@ $task->withTimeLimit(15)->start();
 $task->withoutTimeLimit()->start();
 ```
 
+Some tips:
+- Don't sleep too long! On Windows, timeout handlers cannot trigger while your task is sleeping.
+  - Use short but frequent sleeps instead.
+- Avoid using `SIGINT`! On Unix, this signal is reserved for timeout detection. 
+
+### Task IDs
+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.
+
+By default, if a task does not has its user-specified task ID when starting, a ULID will be generated as its task ID.
+
+```php
+// create a task with a specified task ID...
+$task = new AsyncTask(function () {}, "customTaskID");
+
+// will return a status object for immediate checking...
+$status = $task->start();
+
+// in case the task ID was not given, what is the generated task ID?
+$taskID = $status->taskID;
+
+// is that task still running?
+$status->isRunning();
+
+// when task IDs are known, task status objects can be recreated on-the-fly
+$anotherStatus = new AsyncTaskStatus("customTaskID");
+```
+
+Some tips:
+- Task IDs can be optional (i.e. `null`) but CANNOT be blank (i.e. `""`)!
+- If multiple tasks are started with the same task ID, then the task status object will only track the first task that was started
+- Known issue: on Windows, checking task statuses can be slow (about 0.5 - 1 seconds) due to underlying bottlenecks
+
 ## Testing
 PHPUnit via Composer script:
 ```sh

composer.json

@@ -1,6 +1,6 @@
 {
     "name": "vectorial1024/laravel-process-async",
-    "description": "Utilize Laravel Process to run PHP code asynchronously.",
+    "description": "Utilize Laravel Process to run PHP code asynchronously, as if using Laravel Concurrency.",
     "keywords": [
         "laravel",
         "background",

src/AsyncTask.php

@@ -7,6 +7,9 @@
 use Closure;
 use Illuminate\Process\InvokedProcess;
 use Illuminate\Support\Facades\Process;
+use Illuminate\Support\Str;
+use InvalidArgumentException;
+use Laravel\SerializableClosure\SerializableClosure;
 use LogicException;
 use loophp\phposinfo\OsInfo;
 use RuntimeException;
@@ -24,6 +27,14 @@ class AsyncTask
      */
     private Closure|AsyncTaskInterface $theTask;
 
+    /**
+     * The user-specified ID of the current task. (Null means user did not specify any ID).
+     * 
+     * If null, the task will generate an unsaved random ID when it is started.
+     * @var string|null
+     */
+    private string|null $taskID;
+
     /**
      * The process that is actually running this task. Tasks that are not started will have null here.
      * @var InvokedProcess|null
@@ -92,11 +103,16 @@ class AsyncTask
     /**
      * Creates an AsyncTask instance.
      * @param Closure|AsyncTaskInterface $theTask The task to be executed in the background.
+     * @param string|null $taskID (optional) The user-specified task ID of this AsyncTask. Should be unique.
      */
-    public function __construct(Closure|AsyncTaskInterface $theTask)
+    public function __construct(Closure|AsyncTaskInterface $theTask, string|null $taskID = null)
     {
         // opis/closure allows direct storage of closure
         $this->theTask = $theTask;
+        if ($taskID === "") {
+            throw new InvalidArgumentException("AsyncTask ID cannot be empty.");
+        }
+        $this->taskID = $taskID;
     }
 
     public function __serialize(): array
@@ -135,7 +151,9 @@ public function run(): void
         register_shutdown_function([$this, 'shutdownCheckTaskTimeout']);
         if (OsInfo::isWindows()) {
             // windows can just use PHP's time limit
-            set_time_limit($this->timeLimit);
+            if ($this->timeLimit > 0) {
+                set_time_limit($this->timeLimit);
+            }
         } else {
             // assume anything not Windows to be Unix
             // we already set it to kill this task after the timeout, so we just need to install a listener to catch the signal and exit gracefully
@@ -171,21 +189,26 @@ public function run(): void
 
     /**
      * Starts this AsyncTask immediately in the background. A runner will then run this AsyncTask.
-     * @return void
+     * @return AsyncTaskStatus The status object for the started AsyncTask.
      */
-    public function start(): void
+    public function start(): AsyncTaskStatus
     {
+        // prepare the task details
+        $taskID = $this->taskID ?? Str::ulid()->toString();
+        $taskStatus = new AsyncTaskStatus($taskID);
+
         // prepare the runner command
         $serializedTask = $this->toBase64Serial();
-        $baseCommand = "php artisan async:run $serializedTask";
+        $encodedTaskID = $taskStatus->getEncodedTaskID();
+        $baseCommand = "php artisan async:run $serializedTask --id='$encodedTaskID'";
 
         // then, specific actions depending on the runtime OS
         if (OsInfo::isWindows()) {
             // basically, in windows, it is too tedioous to check whether we are in cmd or ps,
             // but we require cmd (ps won't work here), so might as well force cmd like this
             // windows has real max time limit
-            $this->runnerProcess = Process::quietly()->start("cmd /c start /b $baseCommand");
-            return;
+            $this->runnerProcess = Process::quietly()->start("cmd >nul 2>nul /c start /b $baseCommand");
+            return $taskStatus;
         }
         // assume anything not windows to be unix
         // unix use nohup
@@ -209,6 +232,7 @@ public function start(): void
             $timeoutClause = static::$timeoutCmdName . " -s 2 {$this->timeLimit}";
         }
         $this->runnerProcess = Process::quietly()->start("nohup $timeoutClause $baseCommand >/dev/null 2>&1");
+        return $taskStatus;
     }
 
     /**

src/AsyncTaskRunnerCommand.php

@@ -14,7 +14,7 @@ class AsyncTaskRunnerCommand extends Command
      *
      * @var string
      */
-    protected $signature = 'async:run {task}';
+    protected $signature = 'async:run {task} {--id=}';
 
     /**
      * The console command description.