Add Fiber-native concurrent task groups

README.md

@@ -38,6 +38,32 @@ Every package here is versioned and released alongside the core. Add what your a
 
 Thank you for considering contributing to the Doppar framework! The contribution guide can be found in the [Doppar documentation](https://doppar.com/versions/4.x/contributions).
 
+## Concurrent tasks
+
+Independent non-blocking operations can run together in a named task group:
+
+```php
+use Phaseolies\Support\Concurrency\Task;
+use Phaseolies\Support\Concurrency\TaskGroup;
+
+$results = TaskGroup::run([
+    'profile' => function (Task $task) use ($client) {
+        return $task->await(function ($resolve, $reject) use ($client) {
+            $request = $client->fetch('/profile', $resolve, $reject);
+
+            return fn () => $request->cancel();
+        });
+    },
+    'settings' => fn () => loadSettings(),
+], timeout: 2.0);
+```
+
+The cleanup callback returned by `Task::await()` cancels the pending operation
+when a sibling fails or the shared deadline expires. Task groups use the
+configured React `LoopInterface`; when that loop is already running, call the
+group from a Fiber so the parent Fiber can suspend without restarting or
+stopping the loop. Blocking PDO, filesystem, and HTTP calls remain blocking.
+
 ## Code of Conduct
 
 In order to ensure that the Doppar community is welcoming to all, please review and abide by the [Code of Conduct](https://doppar.com/versions/4.x/contributions#code-of-conduct).

src/Phaseolies/Application.php

@@ -16,6 +16,9 @@
 use Phaseolies\Config\Config;
 use Phaseolies\Support\DeferScope;
 use Phaseolies\Support\ExecutionContext;
+use Phaseolies\Support\Concurrency\TaskGroup;
+use React\EventLoop\Loop;
+use React\EventLoop\LoopInterface;
 use Phaseolies\ApplicationBuilder;
 use Devium\Toml\Toml;
 use RuntimeException;
@@ -821,6 +824,8 @@ protected function bindSingletonClasses(): void
 
         $this->singleton('request', fn() => Request::capture());
 
+        $this->singleton(LoopInterface::class, fn() => Loop::get());
+
         $this->bindHttpGateway();
 
         $this->singleton('route', Router::class);
@@ -1547,13 +1552,17 @@ public function dispatch($request): DispatchResult
 
             $response = $this->handle($request);
 
+            TaskGroup::assertNothingPending($context->id());
+
             $response->prepare($request)->send();
 
             $this->suspendDeferScope($deferScope);
             $this->suspendContext($context);
 
             return new DispatchResult($this, $request, $response, null, $deferScope, $context);
         } catch (HttpException $e) {
+            TaskGroup::cancelPending($e, $context->id());
+
             try {
                 Response::dispatchHttpException($e);
             } catch (\Throwable $renderFailure) {
@@ -1568,6 +1577,7 @@ public function dispatch($request): DispatchResult
 
             return new DispatchResult($this, $request, null, $e, $deferScope, $context);
         } catch (\Throwable $e) {
+            TaskGroup::cancelPending($e, $context->id());
             $this->endDeferScope($deferScope, $e);
             $this->endContext($context, $e);
 

src/Phaseolies/Support/Concurrency/Exceptions/DeadlineExceededException.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Phaseolies\Support\Concurrency\Exceptions;
+
+class DeadlineExceededException extends \RuntimeException
+{
+    /**
+     * @param float $timeout
+     */
+    public function __construct(protected readonly float $timeout)
+    {
+        parent::__construct("Task group deadline of {$timeout} seconds was exceeded.");
+    }
+
+    /**
+     * Get the configured timeout in seconds.
+     *
+     * @return float
+     */
+    public function timeout(): float
+    {
+        return $this->timeout;
+    }
+}

src/Phaseolies/Support/Concurrency/Exceptions/TaskCancelledException.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Phaseolies\Support\Concurrency\Exceptions;
+
+class TaskCancelledException extends \RuntimeException
+{
+    /**
+     * Create a cancellation exception for a named task.
+     *
+     * @param string $taskName
+     * @param \Throwable|null $reason
+     */
+    public function __construct(string $taskName, ?\Throwable $reason = null)
+    {
+        parent::__construct("Task [{$taskName}] was cancelled.", 0, $reason);
+    }
+}

src/Phaseolies/Support/Concurrency/Exceptions/TaskFailedException.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Phaseolies\Support\Concurrency\Exceptions;
+
+class TaskFailedException extends \RuntimeException
+{
+    /**
+     * @param string $taskName
+     * @param \Throwable $failure
+     */
+    public function __construct(
+        protected readonly string $taskName,
+        \Throwable $failure
+    ) {
+        parent::__construct(
+            "Task [{$taskName}] failed: {$failure->getMessage()}",
+            0,
+            $failure
+        );
+    }
+
+    /**
+     * Get the name of the failed task.
+     *
+     * @return string
+     */
+    public function taskName(): string
+    {
+        return $this->taskName;
+    }
+}