From bf578c301518df0b74bb418d5adb8af4224847c4 Mon Sep 17 00:00:00 2001
From: azjezz <azjezz@protonmail.com>
Date: Sun, 31 Mar 2024 12:45:00 +0100
Subject: [PATCH] feat(async): introduce optional incremental timeout to the
 public API

Signed-off-by: azjezz <azjezz@protonmail.com>
---
 docs/component/io.md                          |  2 +-
 src/Psl/Async/OptionalIncrementalTimeout.php  | 62 +++++++++++++++++++
 .../Internal/OptionalIncrementalTimeout.php   | 52 ----------------
 .../IO/ReadHandleConvenienceMethodsTrait.php  |  2 +-
 src/Psl/IO/Reader.php                         |  7 ++-
 .../IO/WriteHandleConvenienceMethodsTrait.php |  2 +-
 src/Psl/Internal/Loader.php                   |  2 +-
 7 files changed, 70 insertions(+), 59 deletions(-)
 create mode 100644 src/Psl/Async/OptionalIncrementalTimeout.php
 delete mode 100644 src/Psl/IO/Internal/OptionalIncrementalTimeout.php

diff --git a/docs/component/io.md b/docs/component/io.md
index c067e6ab..66083467 100644
--- a/docs/component/io.md
+++ b/docs/component/io.md
@@ -70,7 +70,7 @@
 - [MemoryHandle](./../../src/Psl/IO/MemoryHandle.php#L13)
 - [ReadStreamHandle](./../../src/Psl/IO/ReadStreamHandle.php#L12)
 - [ReadWriteStreamHandle](./../../src/Psl/IO/ReadWriteStreamHandle.php#L12)
-- [Reader](./../../src/Psl/IO/Reader.php#L15)
+- [Reader](./../../src/Psl/IO/Reader.php#L16)
 - [SeekReadStreamHandle](./../../src/Psl/IO/SeekReadStreamHandle.php#L12)
 - [SeekReadWriteStreamHandle](./../../src/Psl/IO/SeekReadWriteStreamHandle.php#L12)
 - [SeekStreamHandle](./../../src/Psl/IO/SeekStreamHandle.php#L10)
diff --git a/src/Psl/Async/OptionalIncrementalTimeout.php b/src/Psl/Async/OptionalIncrementalTimeout.php
new file mode 100644
index 00000000..99a7349d
--- /dev/null
+++ b/src/Psl/Async/OptionalIncrementalTimeout.php
@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psl\Async;
+
+use Closure;
+
+use function microtime;
+
+/**
+ * Manages optional incremental timeouts for asynchronous operations.
+ *
+ * This class provides a way to specify a timeout for an operation and
+ * execute a handler function if the timeout is exceeded. It can be
+ * particularly useful in asynchronous programming where operations
+ * might need to be interrupted or handled differently if they take
+ * too long to complete.
+ */
+final class OptionalIncrementalTimeout
+{
+    /**
+     * @var ?float The end time in microseconds.
+     */
+    private ?float $end;
+
+    /**
+     * @var (Closure(): ?float) The handler to be called upon timeout.
+     */
+    private Closure $handler;
+
+    /**
+     * @param float|null $timeout The timeout duration in seconds. Null to disable timeout.
+     * @param (Closure(): ?float) $handler The handler to be executed if the timeout is reached.
+     */
+    public function __construct(?float $timeout, Closure $handler)
+    {
+        $this->handler = $handler;
+
+        $this->end = $timeout !== null ? (microtime(true) + $timeout) : null;
+    }
+
+    /**
+     * Retrieves the remaining time until the timeout is reached, or null if no timeout is set.
+     *
+     * If the timeout has already been exceeded, the handler is invoked, and its return value is provided.
+     *
+     * @return float|null The remaining time in seconds, null if no timeout is set, or the handler's return value if the timeout is exceeded.
+     *
+     * @external-mutation-free
+     */
+    public function getRemaining(): ?float
+    {
+        if ($this->end === null) {
+            return null;
+        }
+
+        $remaining = $this->end - microtime(true);
+
+        return $remaining <= 0 ? ($this->handler)() : $remaining;
+    }
+}
diff --git a/src/Psl/IO/Internal/OptionalIncrementalTimeout.php b/src/Psl/IO/Internal/OptionalIncrementalTimeout.php
deleted file mode 100644
index 685f2199..00000000
--- a/src/Psl/IO/Internal/OptionalIncrementalTimeout.php
+++ /dev/null
@@ -1,52 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Psl\IO\Internal;
-
-use Closure;
-
-use function microtime;
-
-/**
- * @internal
- *
- * @codeCoverageIgnore
- */
-final class OptionalIncrementalTimeout
-{
-    private ?float $end;
-    /**
-     * @var (Closure(): ?int)
-     */
-    private $handler;
-
-    /**
-     * @param (Closure(): ?int) $handler
-     */
-    public function __construct(?float $timeout, Closure $handler)
-    {
-        $this->handler = $handler;
-        if ($timeout === null) {
-            $this->end = null;
-            return;
-        }
-
-        $this->end = microtime(true) + $timeout;
-    }
-
-    public function getRemaining(): ?float
-    {
-        if ($this->end === null) {
-            return null;
-        }
-
-        $remaining =  $this->end - microtime(true);
-        if ($remaining <= 0) {
-            $th = $this->handler;
-            return $th();
-        }
-
-        return $remaining;
-    }
-}
diff --git a/src/Psl/IO/ReadHandleConvenienceMethodsTrait.php b/src/Psl/IO/ReadHandleConvenienceMethodsTrait.php
index a2461676..e48fa411 100644
--- a/src/Psl/IO/ReadHandleConvenienceMethodsTrait.php
+++ b/src/Psl/IO/ReadHandleConvenienceMethodsTrait.php
@@ -36,7 +36,7 @@ public function readAll(?int $max_bytes = null, ?float $timeout = null): string
 
         /** @var Psl\Ref<string> $data */
         $data = new Psl\Ref('');
-        $timer = new Internal\OptionalIncrementalTimeout(
+        $timer = new Psl\Async\OptionalIncrementalTimeout(
             $timeout,
             static function () use ($data): void {
                 // @codeCoverageIgnoreStart
diff --git a/src/Psl/IO/Reader.php b/src/Psl/IO/Reader.php
index 2d801408..906e609f 100644
--- a/src/Psl/IO/Reader.php
+++ b/src/Psl/IO/Reader.php
@@ -4,6 +4,7 @@
 
 namespace Psl\IO;
 
+use Psl\Async;
 use Psl\Str;
 
 use function strlen;
@@ -58,7 +59,7 @@ public function reachedEndOfDataSource(): bool
      */
     public function readFixedSize(int $size, ?float $timeout = null): string
     {
-        $timer = new Internal\OptionalIncrementalTimeout(
+        $timer = new Async\OptionalIncrementalTimeout(
             $timeout,
             function (): void {
                 // @codeCoverageIgnoreStart
@@ -129,7 +130,7 @@ public function readByte(?float $timeout = null): string
      */
     public function readLine(?float $timeout = null): ?string
     {
-        $timer = new Internal\OptionalIncrementalTimeout(
+        $timer = new Async\OptionalIncrementalTimeout(
             $timeout,
             static function (): void {
                 // @codeCoverageIgnoreStart
@@ -173,7 +174,7 @@ public function readUntil(string $suffix, ?float $timeout = null): ?string
             return substr($buf, 0, $idx);
         }
 
-        $timer = new Internal\OptionalIncrementalTimeout(
+        $timer = new Async\OptionalIncrementalTimeout(
             $timeout,
             static function () use ($suffix): void {
                 // @codeCoverageIgnoreStart
diff --git a/src/Psl/IO/WriteHandleConvenienceMethodsTrait.php b/src/Psl/IO/WriteHandleConvenienceMethodsTrait.php
index 19cceb7e..2b5ddd1f 100644
--- a/src/Psl/IO/WriteHandleConvenienceMethodsTrait.php
+++ b/src/Psl/IO/WriteHandleConvenienceMethodsTrait.php
@@ -42,7 +42,7 @@ public function writeAll(string $bytes, ?float $timeout = null): void
          */
         $written = new Psl\Ref(0);
 
-        $timer = new Internal\OptionalIncrementalTimeout(
+        $timer = new Psl\Async\OptionalIncrementalTimeout(
             $timeout,
             static function () use ($written): void {
                 // @codeCoverageIgnoreStart
diff --git a/src/Psl/Internal/Loader.php b/src/Psl/Internal/Loader.php
index 8c384e2b..a34e4f01 100644
--- a/src/Psl/Internal/Loader.php
+++ b/src/Psl/Internal/Loader.php
@@ -760,7 +760,7 @@ final class Loader
         'Psl\\IO\\SeekReadWriteStreamHandle' => 'Psl/IO/SeekReadWriteStreamHandle.php',
         'Psl\\IO\\SeekWriteStreamHandle' => 'Psl/IO/SeekWriteStreamHandle.php',
         'Psl\\IO\\WriteStreamHandle' => 'Psl/IO/WriteStreamHandle.php',
-        'Psl\\IO\\Internal\\OptionalIncrementalTimeout' => 'Psl/IO/Internal/OptionalIncrementalTimeout.php',
+        'Psl\\Async\\OptionalIncrementalTimeout' => 'Psl/Async/OptionalIncrementalTimeout.php',
         'Psl\\File\\Exception\\AlreadyLockedException' => 'Psl/File/Exception/AlreadyLockedException.php',
         'Psl\\File\\Exception\\RuntimeException' => 'Psl/File/Exception/RuntimeException.php',
         'Psl\\File\\Internal\\AbstractHandleWrapper' => 'Psl/File/Internal/AbstractHandleWrapper.php',