Merge pull request #58 from patchlevel/psr-clock

Use a PSR-20 clock for time measurement

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;
+    }
+}