-

Signed-off-by: azjezz <azjezz@protonmail.com>

Makefile

@@ -22,8 +22,8 @@ compare-benchmark-to-reference:
 	./vendor/bin/phpbench run --config config/phpbench.json --ref=benchmark_reference
 
 static-analysis:                                                                ## run static analysis checks
-	./vendor/bin/psalm -c config/psalm.xml --show-info=true --no-cache --threads=1
-	./vendor/bin/psalm -c config/psalm.xml tests/static-analysis --no-cache --threads=1
+	./vendor/bin/psalm -c config/psalm.xml --show-info=true --no-cache --threads=2
+	./vendor/bin/psalm -c config/psalm.xml tests/static-analysis --no-cache --threads=2
 
 type-coverage:                                                                  ## send static analysis type coverage metrics to https://shepherd.dev/
 	./vendor/bin/psalm -c config/psalm.xml --shepherd --stats --threads=1

docs/component/file.md

@@ -28,9 +28,9 @@
 #### `Classes`
 
 - [Lock](./../../src/Psl/File/Lock.php#L9)
-- [ReadHandle](./../../src/Psl/File/ReadHandle.php#L10)
-- [ReadWriteHandle](./../../src/Psl/File/ReadWriteHandle.php#L11)
-- [WriteHandle](./../../src/Psl/File/WriteHandle.php#L11)
+- [ReadHandle](./../../src/Psl/File/ReadHandle.php#L11)
+- [ReadWriteHandle](./../../src/Psl/File/ReadWriteHandle.php#L12)
+- [WriteHandle](./../../src/Psl/File/WriteHandle.php#L12)
 
 #### `Enums`
 

docs/component/io.md

@@ -16,7 +16,7 @@
 - [input_handle](./../../src/Psl/IO/input_handle.php#L20)
 - [output_handle](./../../src/Psl/IO/output_handle.php#L20)
 - [pipe](./../../src/Psl/IO/pipe.php#L24)
-- [streaming](./../../src/Psl/IO/streaming.php#L38)
+- [streaming](./../../src/Psl/IO/streaming.php#L41)
 - [write](./../../src/Psl/IO/write.php#L21)
 - [write_error](./../../src/Psl/IO/write_error.php#L23)
 - [write_error_line](./../../src/Psl/IO/write_error_line.php#L23)
@@ -41,7 +41,7 @@
 - [CloseWriteHandleInterface](./../../src/Psl/IO/CloseWriteHandleInterface.php#L7)
 - [CloseWriteStreamHandleInterface](./../../src/Psl/IO/CloseWriteStreamHandleInterface.php#L9)
 - [HandleInterface](./../../src/Psl/IO/HandleInterface.php#L21)
-- [ReadHandleInterface](./../../src/Psl/IO/ReadHandleInterface.php#L10)
+- [ReadHandleInterface](./../../src/Psl/IO/ReadHandleInterface.php#L12)
 - [ReadStreamHandleInterface](./../../src/Psl/IO/ReadStreamHandleInterface.php#L9)
 - [ReadWriteHandleInterface](./../../src/Psl/IO/ReadWriteHandleInterface.php#L7)
 - [ReadWriteStreamHandleInterface](./../../src/Psl/IO/ReadWriteStreamHandleInterface.php#L9)
@@ -54,32 +54,32 @@
 - [SeekWriteHandleInterface](./../../src/Psl/IO/SeekWriteHandleInterface.php#L7)
 - [SeekWriteStreamHandleInterface](./../../src/Psl/IO/SeekWriteStreamHandleInterface.php#L9)
 - [StreamHandleInterface](./../../src/Psl/IO/StreamHandleInterface.php#L9)
-- [WriteHandleInterface](./../../src/Psl/IO/WriteHandleInterface.php#L10)
+- [WriteHandleInterface](./../../src/Psl/IO/WriteHandleInterface.php#L12)
 - [WriteStreamHandleInterface](./../../src/Psl/IO/WriteStreamHandleInterface.php#L9)
 
 #### `Classes`
 
-- [CloseReadStreamHandle](./../../src/Psl/IO/CloseReadStreamHandle.php#L12)
-- [CloseReadWriteStreamHandle](./../../src/Psl/IO/CloseReadWriteStreamHandle.php#L12)
-- [CloseSeekReadStreamHandle](./../../src/Psl/IO/CloseSeekReadStreamHandle.php#L12)
-- [CloseSeekReadWriteStreamHandle](./../../src/Psl/IO/CloseSeekReadWriteStreamHandle.php#L12)
+- [CloseReadStreamHandle](./../../src/Psl/IO/CloseReadStreamHandle.php#L13)
+- [CloseReadWriteStreamHandle](./../../src/Psl/IO/CloseReadWriteStreamHandle.php#L13)
+- [CloseSeekReadStreamHandle](./../../src/Psl/IO/CloseSeekReadStreamHandle.php#L13)
+- [CloseSeekReadWriteStreamHandle](./../../src/Psl/IO/CloseSeekReadWriteStreamHandle.php#L13)
 - [CloseSeekStreamHandle](./../../src/Psl/IO/CloseSeekStreamHandle.php#L10)
-- [CloseSeekWriteStreamHandle](./../../src/Psl/IO/CloseSeekWriteStreamHandle.php#L12)
+- [CloseSeekWriteStreamHandle](./../../src/Psl/IO/CloseSeekWriteStreamHandle.php#L13)
 - [CloseStreamHandle](./../../src/Psl/IO/CloseStreamHandle.php#L10)
-- [CloseWriteStreamHandle](./../../src/Psl/IO/CloseWriteStreamHandle.php#L12)
-- [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#L16)
-- [SeekReadStreamHandle](./../../src/Psl/IO/SeekReadStreamHandle.php#L12)
-- [SeekReadWriteStreamHandle](./../../src/Psl/IO/SeekReadWriteStreamHandle.php#L12)
+- [CloseWriteStreamHandle](./../../src/Psl/IO/CloseWriteStreamHandle.php#L13)
+- [MemoryHandle](./../../src/Psl/IO/MemoryHandle.php#L14)
+- [ReadStreamHandle](./../../src/Psl/IO/ReadStreamHandle.php#L13)
+- [ReadWriteStreamHandle](./../../src/Psl/IO/ReadWriteStreamHandle.php#L13)
+- [Reader](./../../src/Psl/IO/Reader.php#L17)
+- [SeekReadStreamHandle](./../../src/Psl/IO/SeekReadStreamHandle.php#L13)
+- [SeekReadWriteStreamHandle](./../../src/Psl/IO/SeekReadWriteStreamHandle.php#L13)
 - [SeekStreamHandle](./../../src/Psl/IO/SeekStreamHandle.php#L10)
-- [SeekWriteStreamHandle](./../../src/Psl/IO/SeekWriteStreamHandle.php#L12)
-- [WriteStreamHandle](./../../src/Psl/IO/WriteStreamHandle.php#L12)
+- [SeekWriteStreamHandle](./../../src/Psl/IO/SeekWriteStreamHandle.php#L13)
+- [WriteStreamHandle](./../../src/Psl/IO/WriteStreamHandle.php#L13)
 
 #### `Traits`
 
-- [ReadHandleConvenienceMethodsTrait](./../../src/Psl/IO/ReadHandleConvenienceMethodsTrait.php#L15)
-- [WriteHandleConvenienceMethodsTrait](./../../src/Psl/IO/WriteHandleConvenienceMethodsTrait.php#L16)
+- [ReadHandleConvenienceMethodsTrait](./../../src/Psl/IO/ReadHandleConvenienceMethodsTrait.php#L16)
+- [WriteHandleConvenienceMethodsTrait](./../../src/Psl/IO/WriteHandleConvenienceMethodsTrait.php#L17)
 
 

docs/component/shell.md

@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [execute](./../../src/Psl/Shell/execute.php#L41)
+- [execute](./../../src/Psl/Shell/execute.php#L42)
 - [stream_unpack](./../../src/Psl/Shell/stream_unpack.php#L30)
 - [unpack](./../../src/Psl/Shell/unpack.php#L16)
 

docs/component/tcp.md

@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [connect](./../../src/Psl/TCP/connect.php#L18)
+- [connect](./../../src/Psl/TCP/connect.php#L19)
 
 #### `Classes`
 

docs/component/unix.md

@@ -12,7 +12,7 @@
 
 #### `Functions`
 
-- [connect](./../../src/Psl/Unix/connect.php#L18)
+- [connect](./../../src/Psl/Unix/connect.php#L19)
 
 #### `Classes`
 

examples/async/usleep.php

@@ -11,7 +11,7 @@
 require __DIR__ . '/../../vendor/autoload.php';
 
 Async\main(static function (): int {
-    $start = DateTime\Timestamp::now();
+    $start = DateTime\Timestamp::monotonic();
 
     Async\concurrently([
         static fn() => Async\sleep(DateTime\Duration::hours(0)),
@@ -23,7 +23,7 @@
         static fn() => Async\sleep(DateTime\Duration::milliseconds(2000)),
     ]);
 
-    $duration = DateTime\Timestamp::now()->since($start);
+    $duration = DateTime\Timestamp::monotonic()->since($start);
 
     IO\write_error_line("duration : %s.", $duration->toString(max_decimals: 5));
 

examples/channel/main.php

@@ -6,6 +6,7 @@
 
 use Psl\Async;
 use Psl\Channel;
+use Psl\DateTime\Duration;
 use Psl\IO;
 
 require __DIR__ . '/../../vendor/autoload.php';
@@ -16,7 +17,7 @@
  */
 [$receiver, $sender] = Channel\unbounded();
 
-Async\Scheduler::delay(1, static function () use ($sender) {
+Async\Scheduler::delay(Duration::seconds(1), static function () use ($sender) {
     $sender->send('Hello, World!');
 });
 

examples/io/benchmark.php

@@ -28,7 +28,7 @@
     $args = getopt('i:o:t:');
     $input_file = $args['i'] ?? '/dev/zero';
     $output_file = $args['o'] ?? '/dev/null';
-    $seconds = (int)($args['t'] ?? 5);
+    $seconds = DateTime\Duration::seconds((int)($args['t'] ?? 5));
 
     // passing file descriptors requires mapping paths (https://bugs.php.net/bug.php?id=53465)
     $input_file = Regex\replace($input_file, '(^/dev/fd/)', 'php://fd/');
@@ -41,7 +41,7 @@
 
     Async\Scheduler::delay($seconds, static fn() => $input->close());
 
-    $start = DateTime\Timestamp::now();
+    $start = DateTime\Timestamp::monotonic();
     $i = 0;
     try {
         while ($chunk = $input->read(65536)) {
@@ -53,7 +53,7 @@
     } catch (IO\Exception\AlreadyClosedException) {
     }
 
-    $duration = DateTime\Timestamp::now()->since($start);
+    $duration = DateTime\Timestamp::monotonic()->since($start);
     $bytes = $i * 65536;
     $bytes_formatted = Math\round($bytes / 1024 / 1024 / $duration->getTotalSeconds(), 1);
 

examples/io/pipe.php

@@ -5,6 +5,7 @@
 namespace Psl\Example\IO;
 
 use Psl\Async;
+use Psl\DateTime\Duration;
 use Psl\IO;
 
 require __DIR__ . '/../../vendor/autoload.php';
@@ -16,7 +17,7 @@
         static function() use($read): void {
             IO\write_error_line("< sleeping.");
 
-            Async\sleep(0.01);
+            Async\sleep(Duration::milliseconds(10));
 
             IO\write_error_line("< waiting for content.");
 
@@ -30,7 +31,7 @@ static function() use($read): void {
         static function() use($write): void {
             IO\write_error_line('> sleeping.');
 
-            Async\sleep(0.1);
+            Async\sleep(Duration::milliseconds(100));
 
             IO\write_error_line('> writing.');
 

examples/io/queued.php

@@ -15,7 +15,7 @@
 
     $he = Async\run(static fn(): string => $read->readFixedSize(2));
 
-    Async\sleep(0.001);
+    Async\sleep(Psl\DateTime\Duration::milliseconds(200));
 
     $write->write("hello");
 

examples/run.php

@@ -35,9 +35,9 @@
             IO\write_error_line('- %s/%s   -> started', $component, $script);
 
             $awaitables[] = Async\run(static function() use($component, $script, $file): array {
-                $start = DateTime\Timestamp::now();
+                $start = DateTime\Timestamp::monotonic();
                 Shell\execute(PHP_BINARY, [$file]);
-                $duration = DateTime\Timestamp::now()->since($start);
+                $duration = DateTime\Timestamp::monotonic()->since($start);
 
                 return [$component, $script, $duration];
             });
@@ -47,7 +47,7 @@
     foreach (Async\Awaitable::iterate($awaitables) as $awaitable) {
         [$component, $script, $duration] = $awaitable->await();
 
-        IO\write_error_line('+ %s/%s   -> finished in %s', $component, $script, $duration);
+        IO\write_error_line('+ %s/%s   -> finished in %s', $component, $script, $duration->toString(10));
     }
 
     return 0;

examples/shell/timeout.php

@@ -5,14 +5,15 @@
 namespace Psl\Example\Shell;
 
 use Psl\Async;
+use Psl\DateTime;
 use Psl\IO;
 use Psl\Shell;
 
 require __DIR__ . '/../../vendor/autoload.php';
 
 Async\main(static function (): void {
     try {
-        Shell\execute('sleep', ['1'], timeout: 0.5);
+        Shell\execute('sleep', ['1'], timeout: DateTime\Duration::milliseconds(500));
     } catch (Shell\Exception\TimeoutException $exception) {
         IO\write_error_line($exception->getMessage());
     }

sample.php

@@ -11,11 +11,24 @@
 require 'vendor/autoload.php';
 
 Async\main(static function(): void {
+    $a = DateTime\Timestamp::now();
+    $b = DateTime\Timestamp::now();
+
+    var_dump($b->since($a)->toString(20));
+
+    $a = DateTime\Timestamp::monotonic();
+    $b = DateTime\Timestamp::monotonic();
+
+    var_dump($b->since($a)->toString(20));
+
     $someday = DateTime\DateTime::fromTimestamp(
-        DateTime\Timestamp::fromRaw(1711846900),
         DateTime\Timezone::EuropeLondon,
+        DateTime\Timestamp::fromRaw(1711846900),
     );
 
+    var_dump($someday->format(DateTime\DatePattern::Http->value));
+    die();
+
     IO\write_line('The offset of the timezone: %s', $someday->getTimezone()->getOffset($someday)->getTotalMinutes());
     IO\write_line('The raw offset of the timezone: %s', $someday->getTimezone()->getRawOffset()->getTotalMinutes());
     IO\write_line('The dst savings of the timezone: %s', $someday->getTimezone()->getDaylightSavingTimeSavings()->getTotalMinutes());

src/Psl/Async/OptionalIncrementalTimeout.php

@@ -5,8 +5,8 @@
 namespace Psl\Async;
 
 use Closure;
-
-use function microtime;
+use Psl\DateTime\Duration;
+use Psl\DateTime\Timestamp;
 
 /**
  * Manages optional incremental timeouts for asynchronous operations.
@@ -16,47 +16,59 @@
  * particularly useful in asynchronous programming where operations
  * might need to be interrupted or handled differently if they take
  * too long to complete.
+ *
+ * @psalm-suppress MissingThrowsDocblock
  */
 final class OptionalIncrementalTimeout
 {
     /**
-     * @var ?float The end time in microseconds.
+     * @var ?Timestamp The end time.
      */
-    private ?float $end;
+    private ?Timestamp $end;
 
     /**
-     * @var (Closure(): ?float) The handler to be called upon timeout.
+     * @var (Closure(): ?Duration) 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.
+     * @param null|Duration $timeout The timeout duration. Null to disable timeout.
+     * @param (Closure(): ?Duration) $handler The handler to be executed if the timeout is reached.
      */
-    public function __construct(?float $timeout, Closure $handler)
+    public function __construct(?Duration $timeout, Closure $handler)
     {
         $this->handler = $handler;
 
-        $this->end = $timeout !== null ? (microtime(true) + $timeout) : null;
+        if (null === $timeout) {
+            $this->end = null;
+
+            return;
+        }
+
+        if (!$timeout->isPositive()) {
+            $this->end = Timestamp::monotonic();
+        } else {
+            $this->end = Timestamp::monotonic()->plus($timeout);
+        }
     }
 
     /**
      * 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.
+     * @return Duration|null The remaining time duration, null if no timeout is set, or the handler's return value if the timeout is exceeded.
      *
      * @external-mutation-free
      */
-    public function getRemaining(): ?float
+    public function getRemaining(): ?Duration
     {
         if ($this->end === null) {
             return null;
         }
 
-        $remaining = $this->end - microtime(true);
+        $remaining = $this->end->since(Timestamp::monotonic());
 
-        return $remaining <= 0 ? ($this->handler)() : $remaining;
+        return $remaining->isPositive() ? $remaining : ($this->handler)();
     }
 }