Use a PSR-20 clock for time measurement

DefaultWorker and StopWorkerOnTimeLimitListener accept an optional
ClockInterface, falling back to a new SystemClock. This makes time based
behaviour testable without reflection or real sleeps.

The time limit is now checked with millisecond precision, so the worker
stops once the limit is reached instead of up to a second later.

Author: DavidBadura

composer.json

@@ -20,6 +20,7 @@
   ],
   "require": {
     "php": "~8.2.0 || ~8.3.0 || ~8.4.0  || ~8.5.0",
+    "psr/clock": "^1.0",
     "psr/log": "^1.1 || ^2.0 || ^3.0",
     "symfony/event-dispatcher": "^5.4.26 || ^6.4.0 || ^7.0.0 || ^8.0.0"
   },

composer.lock

@@ -85,3 +85,24 @@ Iteration details use the `debug` level; stop reasons (limit exceeded, signal re
 
 With the `ConsoleLogger` from the [Symfony command example](integration.md#symfony), run the command with `-v`
 to see stop reasons or `-vvv` to see everything.
+
+## Clock
+
+The worker uses a [PSR-20](https://www.php-fig.org/psr/psr-20/) clock to measure the job's run time
+and to check the `timeLimit`. By default it uses the system clock. You can pass your own clock to `create`,
+e.g. a mock clock to test time-dependent behaviour without actually waiting:
+
+```php
+use Patchlevel\Worker\DefaultWorker;
+use Symfony\Component\Clock\MockClock;
+
+$worker = DefaultWorker::create(
+    $job,
+    ['timeLimit' => 3600],
+    $logger,
+    clock: new MockClock(),
+);
+```
+:::note
+The clock is only used for measuring time. The sleep between iterations still waits for real.
+:::

docs/getting-started.md

@@ -12,30 +12,29 @@
 use Patchlevel\Worker\Listener\StopWorkerOnMemoryLimitListener;
 use Patchlevel\Worker\Listener\StopWorkerOnSignalListener;
 use Patchlevel\Worker\Listener\StopWorkerOnTimeLimitListener;
+use Psr\Clock\ClockInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
 use Symfony\Component\EventDispatcher\EventDispatcher;
 use Symfony\Component\EventDispatcher\EventDispatcherInterface;
 
 use function max;
-use function microtime;
-use function round;
 use function usleep;
 
 final class DefaultWorker implements Worker
 {
     private bool $shouldStop = false;
 
-    /** @var Closure():int  */
-    private Closure $timeMeasure;
+    private readonly ClockInterface $clock;
 
     /** @param Closure(Closure):void $job */
     public function __construct(
         private readonly Closure $job,
         private readonly EventDispatcherInterface $eventDispatcher,
         private readonly LoggerInterface|null $logger = null,
+        ClockInterface|null $clock = null,
     ) {
-        $this->timeMeasure = static fn () => (int)round(microtime(true) * 1000);
+        $this->clock = $clock ?? new SystemClock();
     }
 
     /** @param positive-int|0 $sleepTimer in milliseconds */
@@ -48,11 +47,11 @@ public function run(int $sleepTimer = 1000): void
         while (!$this->shouldStop) {
             $this->logger?->debug('Worker starting job run');
 
-            $startTime = ($this->timeMeasure)();
+            $startTime = $this->milliseconds();
 
             ($this->job)($this->stop(...));
 
-            $endTime = ($this->timeMeasure)();
+            $endTime = $this->milliseconds();
             $ranTime = $endTime - $startTime;
 
             $this->logger?->debug('Worker finished job run ({ranTime}ms)', ['ranTime' => $ranTime]);
@@ -97,6 +96,7 @@ public static function create(
         array $options = [],
         LoggerInterface $logger = new NullLogger(),
         EventDispatcherInterface|null $eventDispatcher = null,
+        ClockInterface|null $clock = null,
     ): self {
         if ($eventDispatcher === null) {
             $eventDispatcher = new EventDispatcher();
@@ -118,14 +118,20 @@ public static function create(
 
         if (isset($options['timeLimit'])) {
             $eventDispatcher->addSubscriber(
-                new StopWorkerOnTimeLimitListener($options['timeLimit'], $logger),
+                new StopWorkerOnTimeLimitListener($options['timeLimit'], $logger, $clock),
             );
         }
 
         return new self(
             $job,
             $eventDispatcher,
             $logger,
+            $clock,
         );
     }
+
+    private function milliseconds(): int
+    {
+        return (int)$this->clock->now()->format('Uv');
+    }
 }

src/DefaultWorker.php

@@ -4,32 +4,38 @@
 
 namespace Patchlevel\Worker\Listener;
 
+use DateInterval;
+use DateTimeImmutable;
 use Patchlevel\Worker\Event\WorkerRunningEvent;
 use Patchlevel\Worker\Event\WorkerStartedEvent;
+use Patchlevel\Worker\SystemClock;
+use Psr\Clock\ClockInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\EventDispatcher\EventSubscriberInterface;
 
-use function time;
-
 final class StopWorkerOnTimeLimitListener implements EventSubscriberInterface
 {
-    private float $endTime = 0;
+    private DateTimeImmutable|null $endTime = null;
+
+    private readonly ClockInterface $clock;
 
     /** @param positive-int $timeLimit in seconds */
     public function __construct(
         private readonly int $timeLimit,
         private readonly LoggerInterface|null $logger = null,
+        ClockInterface|null $clock = null,
     ) {
+        $this->clock = $clock ?? new SystemClock();
     }
 
     public function onWorkerStarted(): void
     {
-        $this->endTime = time() + $this->timeLimit;
+        $this->endTime = $this->clock->now()->add(new DateInterval('PT' . $this->timeLimit . 'S'));
     }
 
     public function onWorkerRunning(WorkerRunningEvent $event): void
     {
-        if ($this->endTime >= time()) {
+        if ($this->endTime !== null && $this->clock->now() < $this->endTime) {
             return;
         }
 

src/Listener/StopWorkerOnTimeLimitListener.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Worker;
+
+use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
+
+final class SystemClock implements ClockInterface
+{
+    public function now(): DateTimeImmutable
+    {
+        return new DateTimeImmutable();
+    }
+}

src/SystemClock.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Patchlevel\Worker\Tests;
+
+use DateTimeImmutable;
+use Psr\Clock\ClockInterface;
+
+use function intdiv;
+use function sprintf;
+
+final class TestClock implements ClockInterface
+{
+    private int $milliseconds = 1_767_225_600_000;
+
+    /** @param int $tick milliseconds the clock moves forward on every now() call */
+    public function __construct(
+        private readonly int $tick = 0,
+    ) {
+    }
+
+    public function now(): DateTimeImmutable
+    {
+        $now = new DateTimeImmutable(sprintf('@%d.%03d', intdiv($this->milliseconds, 1000), $this->milliseconds % 1000));
+
+        $this->milliseconds += $this->tick;
+
+        return $now;
+    }
+
+    public function advance(int $milliseconds): void
+    {
+        $this->milliseconds += $milliseconds;
+    }
+}