Add support for fractional seconds timeout (#55)

mvorisek · web-flow · commit 0e9cad7abb83 · 2024-12-03T01:03:04.000+01:00
diff --git a/src/mutex/CASMutex.php b/src/mutex/CASMutex.php
@@ -27,10 +27,10 @@ class CASMutex extends Mutex
      *
      * The default is 3 seconds.
      *
-     * @param int $timeout The timeout in seconds.
+     * @param float $timeout The timeout in seconds.
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(int $timeout = 3)
+    public function __construct(float $timeout = 3)
     {
         $this->loop = new Loop($timeout);
     }
diff --git a/src/mutex/FlockMutex.php b/src/mutex/FlockMutex.php
@@ -16,7 +16,7 @@
  */
 class FlockMutex extends LockMutex
 {
-    public const INFINITE_TIMEOUT = -1;
+    public const INFINITE_TIMEOUT = -1.0;
 
     /**
      * @internal
@@ -39,22 +39,22 @@ class FlockMutex extends LockMutex
     private $fileHandle;
 
     /**
-     * @var int
+     * @var float
      */
     private $timeout;
 
     /**
-     * @var int
+     * @var self::STRATEGY_*
      */
     private $strategy;
 
     /**
      * Sets the file handle.
      *
      * @param resource $fileHandle The file handle.
-     * @param int $timeout
+     * @param float    $timeout
      */
-    public function __construct($fileHandle, int $timeout = self::INFINITE_TIMEOUT)
+    public function __construct($fileHandle, float $timeout = self::INFINITE_TIMEOUT)
     {
         if (!is_resource($fileHandle)) {
             throw new \InvalidArgumentException('The file handle is not a valid resource.');
@@ -65,9 +65,12 @@ public function __construct($fileHandle, int $timeout = self::INFINITE_TIMEOUT)
         $this->strategy = $this->determineLockingStrategy();
     }
 
-    private function determineLockingStrategy()
+    /**
+     * @return self::STRATEGY_*
+     */
+    private function determineLockingStrategy(): int
     {
-        if ($this->timeout == self::INFINITE_TIMEOUT) {
+        if ($this->timeout === self::INFINITE_TIMEOUT) {
             return self::STRATEGY_BLOCK;
         }
 
@@ -94,7 +97,9 @@ private function lockBlocking(): void
      */
     private function lockPcntl(): void
     {
-        $timebox = new PcntlTimeout($this->timeout);
+        $timeoutInt = (int) ceil($this->timeout);
+
+        $timebox = new PcntlTimeout($timeoutInt);
 
         try {
             $timebox->timeBoxed(
@@ -103,7 +108,7 @@ function (): void {
                 }
             );
         } catch (DeadlineException $e) {
-            throw TimeoutException::create($this->timeout);
+            throw TimeoutException::create($timeoutInt);
         }
     }
 
diff --git a/src/mutex/MemcachedMutex.php b/src/mutex/MemcachedMutex.php
@@ -24,20 +24,24 @@ class MemcachedMutex extends SpinlockMutex
      *
      * @param string    $name     The lock name.
      * @param Memcached $memcache The connected Memcached API.
-     * @param int       $timeout  The time in seconds a lock expires, default is 3.
+     * @param float     $timeout  The time in seconds a lock expires, default is 3.
      *
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(string $name, Memcached $memcache, int $timeout = 3)
+    public function __construct(string $name, Memcached $memcache, float $timeout = 3)
     {
         parent::__construct($name, $timeout);
 
         $this->memcache = $memcache;
     }
 
-    protected function acquire(string $key, int $expire): bool
+    protected function acquire(string $key, float $expire): bool
     {
-        return $this->memcache->add($key, true, $expire);
+        // memcached supports only integer expire
+        // https://github.com/memcached/memcached/wiki/Commands#standard-protocol
+        $expireInt = (int) ceil($expire);
+
+        return $this->memcache->add($key, true, $expireInt);
     }
 
     protected function release(string $key): bool
diff --git a/src/mutex/MySQLMutex.php b/src/mutex/MySQLMutex.php
@@ -20,11 +20,11 @@ class MySQLMutex extends LockMutex
      */
     private $name;
     /**
-     * @var int
+     * @var float
      */
     private $timeout;
 
-    public function __construct(\PDO $PDO, string $name, int $timeout = 0)
+    public function __construct(\PDO $PDO, string $name, float $timeout = 0)
     {
         $this->pdo = $PDO;
 
@@ -43,9 +43,15 @@ public function lock(): void
     {
         $statement = $this->pdo->prepare('SELECT GET_LOCK(?,?)');
 
+        // MySQL rounds the value to whole seconds, sadly rounds, not ceils
+        // TODO MariaDB supports microseconds precision since 10.1.2 version,
+        // but we need to detect the support reliably first
+        // https://github.com/MariaDB/server/commit/3e792e6cbccb5d7bf5b84b38336f8a40ad232020
+        $timeoutInt = (int) ceil($this->timeout);
+
         $statement->execute([
             $this->name,
-            $this->timeout,
+            $timeoutInt,
         ]);
 
         $statement->setFetchMode(\PDO::FETCH_NUM);
diff --git a/src/mutex/PHPRedisMutex.php b/src/mutex/PHPRedisMutex.php
@@ -29,12 +29,12 @@ class PHPRedisMutex extends RedisMutex
      * called already.
      *
      * @param array<\Redis|\RedisCluster> $redisAPIs The Redis connections.
-     * @param string $name The lock name.
-     * @param int $timeout The time in seconds a lock expires after. Default is
-     *                     3 seconds.
+     * @param string                      $name      The lock name.
+     * @param float                       $timeout   The time in seconds a lock expires after. Default is
+     *                                               3 seconds.
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(array $redisAPIs, string $name, int $timeout = 3)
+    public function __construct(array $redisAPIs, string $name, float $timeout = 3)
     {
         parent::__construct($redisAPIs, $name, $timeout);
     }
@@ -43,12 +43,14 @@ public function __construct(array $redisAPIs, string $name, int $timeout = 3)
      * @param \Redis|\RedisCluster $redisAPI The Redis or RedisCluster connection.
      * @throws LockAcquireException
      */
-    protected function add($redisAPI, string $key, string $value, int $expire): bool
+    protected function add($redisAPI, string $key, string $value, float $expire): bool
     {
+        $expireMillis = (int) ceil($expire * 1000);
+
         /** @var \Redis $redisAPI */
         try {
             //  Will set the key, if it doesn't exist, with a ttl of $expire seconds
-            return $redisAPI->set($key, $value, ['nx', 'ex' => $expire]);
+            return $redisAPI->set($key, $value, ['nx', 'px' => $expireMillis]);
         } catch (RedisException $e) {
             $message = sprintf(
                 "Failed to acquire lock for key '%s'",
diff --git a/src/mutex/PredisMutex.php b/src/mutex/PredisMutex.php
@@ -20,24 +20,26 @@ class PredisMutex extends RedisMutex
      * Sets the Redis connections.
      *
      * @param ClientInterface[] $clients The Redis clients.
-     * @param string   $name    The lock name.
-     * @param int      $timeout The time in seconds a lock expires, default is 3.
+     * @param string            $name    The lock name.
+     * @param float             $timeout The time in seconds a lock expires, default is 3.
      *
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(array $clients, string $name, int $timeout = 3)
+    public function __construct(array $clients, string $name, float $timeout = 3)
     {
         parent::__construct($clients, $name, $timeout);
     }
 
     /**
      * @throws LockAcquireException
      */
-    protected function add($redisAPI, string $key, string $value, int $expire): bool
+    protected function add($redisAPI, string $key, string $value, float $expire): bool
     {
+        $expireMillis = (int) ceil($expire * 1000);
+
         /** @var ClientInterface $redisAPI */
         try {
-            return $redisAPI->set($key, $value, 'EX', $expire, 'NX') !== null;
+            return $redisAPI->set($key, $value, 'PX', $expireMillis, 'NX') !== null;
         } catch (PredisException $e) {
             $message = sprintf(
                 "Failed to acquire lock for key '%s'",
diff --git a/src/mutex/RedisMutex.php b/src/mutex/RedisMutex.php
@@ -34,19 +34,19 @@ abstract class RedisMutex extends SpinlockMutex implements LoggerAwareInterface
      *
      * @param array  $redisAPIs The Redis APIs.
      * @param string $name      The lock name.
-     * @param int    $timeout   The time in seconds a lock expires, default is 3.
+     * @param float  $timeout   The time in seconds a lock expires, default is 3.
      *
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(array $redisAPIs, string $name, int $timeout = 3)
+    public function __construct(array $redisAPIs, string $name, float $timeout = 3)
     {
         parent::__construct($name, $timeout);
 
         $this->redisAPIs = $redisAPIs;
         $this->logger = new NullLogger();
     }
 
-    protected function acquire(string $key, int $expire): bool
+    protected function acquire(string $key, float $expire): bool
     {
         // 1. This differs from the specification to avoid an overflow on 32-Bit systems.
         $time = microtime(true);
@@ -149,14 +149,14 @@ private function isMajority(int $count): bool
     /**
      * Sets the key only if such key doesn't exist at the server yet.
      *
-     * @param mixed $redisAPI The connected Redis API.
-     * @param string $key The key.
-     * @param string $value The value.
-     * @param int $expire The TTL seconds.
+     * @param mixed  $redisAPI The connected Redis API.
+     * @param string $key      The key.
+     * @param string $value    The value.
+     * @param float  $expire   The TTL seconds.
      *
      * @return bool True, if the key was set.
      */
-    abstract protected function add($redisAPI, string $key, string $value, int $expire): bool;
+    abstract protected function add($redisAPI, string $key, string $value, float $expire): bool;
 
     /**
      * @param mixed  $redisAPI The connected Redis API.
diff --git a/src/mutex/SpinlockMutex.php b/src/mutex/SpinlockMutex.php
@@ -22,7 +22,7 @@ abstract class SpinlockMutex extends LockMutex
     private const PREFIX = 'lock_';
 
     /**
-     * @var int The timeout in seconds a lock may live.
+     * @var float The timeout in seconds a lock may live.
      */
     private $timeout;
 
@@ -44,11 +44,11 @@ abstract class SpinlockMutex extends LockMutex
     /**
      * Sets the timeout.
      *
-     * @param int $timeout The time in seconds a lock expires, default is 3.
+     * @param float $timeout The time in seconds a lock expires, default is 3.
      *
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(string $name, int $timeout = 3)
+    public function __construct(string $name, float $timeout = 3)
     {
         $this->timeout = $timeout;
         $this->loop = new Loop($this->timeout);
@@ -92,13 +92,13 @@ protected function unlock(): void
     /**
      * Tries to acquire a lock.
      *
-     * @param string $key The lock key.
-     * @param int $expire The timeout in seconds when a lock expires.
+     * @param string $key    The lock key.
+     * @param float  $expire The timeout in seconds when a lock expires.
      *
      * @throws LockAcquireException An unexpected error happened.
      * @return bool True, if the lock could be acquired.
      */
-    abstract protected function acquire(string $key, int $expire): bool;
+    abstract protected function acquire(string $key, float $expire): bool;
 
     /**
      * Tries to release a lock.
diff --git a/src/mutex/TransactionalMutex.php b/src/mutex/TransactionalMutex.php
@@ -40,12 +40,12 @@ class TransactionalMutex extends Mutex
      * As this implementation spans a transaction over a unit of work,
      * PDO::ATTR_AUTOCOMMIT SHOULD not be enabled.
      *
-     * @param \PDO $pdo     The PDO.
-     * @param int  $timeout The timeout in seconds, default is 3.
+     * @param \PDO  $pdo     The PDO.
+     * @param float $timeout The timeout in seconds, default is 3.
      *
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(\PDO $pdo, int $timeout = 3)
+    public function __construct(\PDO $pdo, float $timeout = 3)
     {
         if ($pdo->getAttribute(\PDO::ATTR_ERRMODE) !== PDO::ERRMODE_EXCEPTION) {
             throw new InvalidArgumentException('The pdo must have PDO::ERRMODE_EXCEPTION set.');
diff --git a/src/util/Loop.php b/src/util/Loop.php
@@ -29,7 +29,7 @@ class Loop
     private const MAXIMUM_WAIT_US = 5e5; // 0.50 seconds
 
     /**
-     * @var int The timeout in seconds.
+     * @var float The timeout in seconds.
      */
     private $timeout;
 
@@ -41,10 +41,10 @@ class Loop
     /**
      * Sets the timeout. The default is 3 seconds.
      *
-     * @param int $timeout The timeout in seconds. The default is 3 seconds.
+     * @param float $timeout The timeout in seconds. The default is 3 seconds.
      * @throws \LengthException The timeout must be greater than 0.
      */
-    public function __construct(int $timeout = 3)
+    public function __construct(float $timeout = 3)
     {
         if ($timeout <= 0) {
             throw new LengthException(\sprintf(
diff --git a/src/util/PcntlTimeout.php b/src/util/PcntlTimeout.php
@@ -14,6 +14,8 @@
  *
  * This class requires the pcntl module and supports the cli sapi only.
  *
+ * Only integer timeout is supported - https://github.com/php/php-src/issues/11828.
+ *
  * @internal
  */
 final class PcntlTimeout
diff --git a/tests/mutex/MutexConcurrencyTest.php b/tests/mutex/MutexConcurrencyTest.php
@@ -197,18 +197,18 @@ function ($timeout = 3) use ($dsn, $user, $password) {
      */
     public function testExecutionIsSerializedWhenLocked(callable $mutexFactory)
     {
-        $timestamp = hrtime(true);
+        $time = \microtime(true);
 
-        $this->fork(5, function () use ($mutexFactory): void {
+        $this->fork(6, function () use ($mutexFactory): void {
             /** @var Mutex $mutex */
             $mutex = $mutexFactory();
             $mutex->synchronized(function (): void {
-                \usleep(200000);
+                \usleep(200 * 1000);
             });
         });
 
-        $delta = \hrtime(true) - $timestamp;
-        $this->assertGreaterThan(1e9, $delta);
+        $delta = \microtime(true) - $time;
+        $this->assertGreaterThan(1.201, $delta);
     }
 
     /**
diff --git a/tests/mutex/PredisMutexTest.php b/tests/mutex/PredisMutexTest.php
diff --git a/tests/mutex/RedisMutexTest.php b/tests/mutex/RedisMutexTest.php
diff --git a/tests/mutex/SpinlockMutexTest.php b/tests/mutex/SpinlockMutexTest.php
diff --git a/tests/util/LoopTest.php b/tests/util/LoopTest.php

Original file line number	Diff line number	Diff line change
`@@ -27,10 +27,10 @@ class CASMutex extends Mutex`
`27`	`27`	`*`
`28`	`28`	`* The default is 3 seconds.`
`29`	`29`	`*`
`30`		`- * @param int $timeout The timeout in seconds.`
	`30`	`+ * @param float $timeout The timeout in seconds.`
`31`	`31`	`* @throws \LengthException The timeout must be greater than 0.`
`32`	`32`	`*/`
`33`		`- public function __construct(int $timeout = 3)`
	`33`	`+ public function __construct(float $timeout = 3)`
`34`	`34`	`{`
`35`	`35`	`$this->loop = new Loop($timeout);`
`36`	`36`	`}`
Original file line number	Diff line number	Diff line change
`@@ -24,20 +24,24 @@ class MemcachedMutex extends SpinlockMutex`
`24`	`24`	`*`
`25`	`25`	`* @param string $name The lock name.`
`26`	`26`	`* @param Memcached $memcache The connected Memcached API.`
`27`		`- * @param int $timeout The time in seconds a lock expires, default is 3.`
	`27`	`+ * @param float $timeout The time in seconds a lock expires, default is 3.`
`28`	`28`	`*`
`29`	`29`	`* @throws \LengthException The timeout must be greater than 0.`
`30`	`30`	`*/`
`31`		`- public function __construct(string $name, Memcached $memcache, int $timeout = 3)`
	`31`	`+ public function __construct(string $name, Memcached $memcache, float $timeout = 3)`
`32`	`32`	`{`
`33`	`33`	`parent::__construct($name, $timeout);`
`34`	`34`
`35`	`35`	`$this->memcache = $memcache;`
`36`	`36`	`}`
`37`	`37`
`38`		`- protected function acquire(string $key, int $expire): bool`
	`38`	`+ protected function acquire(string $key, float $expire): bool`
`39`	`39`	`{`
`40`		`- return $this->memcache->add($key, true, $expire);`
	`40`	`+ // memcached supports only integer expire`
	`41`	`+ // https://github.com/memcached/memcached/wiki/Commands#standard-protocol`
	`42`	`+ $expireInt = (int) ceil($expire);`
	`43`	`+`
	`44`	`+ return $this->memcache->add($key, true, $expireInt);`
`41`	`45`	`}`
`42`	`46`
`43`	`47`	`protected function release(string $key): bool`
Original file line number	Diff line number	Diff line change
`@@ -34,19 +34,19 @@ abstract class RedisMutex extends SpinlockMutex implements LoggerAwareInterface`
`34`	`34`	`*`
`35`	`35`	`* @param array $redisAPIs The Redis APIs.`
`36`	`36`	`* @param string $name The lock name.`
`37`		`- * @param int $timeout The time in seconds a lock expires, default is 3.`
	`37`	`+ * @param float $timeout The time in seconds a lock expires, default is 3.`
`38`	`38`	`*`
`39`	`39`	`* @throws \LengthException The timeout must be greater than 0.`
`40`	`40`	`*/`
`41`		`- public function __construct(array $redisAPIs, string $name, int $timeout = 3)`
	`41`	`+ public function __construct(array $redisAPIs, string $name, float $timeout = 3)`
`42`	`42`	`{`
`43`	`43`	`parent::__construct($name, $timeout);`
`44`	`44`
`45`	`45`	`$this->redisAPIs = $redisAPIs;`
`46`	`46`	`$this->logger = new NullLogger();`
`47`	`47`	`}`
`48`	`48`
`49`		`- protected function acquire(string $key, int $expire): bool`
	`49`	`+ protected function acquire(string $key, float $expire): bool`
`50`	`50`	`{`
`51`	`51`	`// 1. This differs from the specification to avoid an overflow on 32-Bit systems.`
`52`	`52`	`$time = microtime(true);`
`@@ -149,14 +149,14 @@ private function isMajority(int $count): bool`
`149`	`149`	`/**`
`150`	`150`	`* Sets the key only if such key doesn't exist at the server yet.`
`151`	`151`	`*`
`152`		`- * @param mixed $redisAPI The connected Redis API.`
`153`		`- * @param string $key The key.`
`154`		`- * @param string $value The value.`
`155`		`- * @param int $expire The TTL seconds.`
	`152`	`+ * @param mixed $redisAPI The connected Redis API.`
	`153`	`+ * @param string $key The key.`
	`154`	`+ * @param string $value The value.`
	`155`	`+ * @param float $expire The TTL seconds.`
`156`	`156`	`*`
`157`	`157`	`* @return bool True, if the key was set.`
`158`	`158`	`*/`
`159`		`- abstract protected function add($redisAPI, string $key, string $value, int $expire): bool;`
	`159`	`+ abstract protected function add($redisAPI, string $key, string $value, float $expire): bool;`
`160`	`160`
`161`	`161`	`/**`
`162`	`162`	`* @param mixed $redisAPI The connected Redis API.`
Original file line number	Diff line number	Diff line change
`@@ -40,12 +40,12 @@ class TransactionalMutex extends Mutex`
`40`	`40`	`* As this implementation spans a transaction over a unit of work,`
`41`	`41`	`* PDO::ATTR_AUTOCOMMIT SHOULD not be enabled.`
`42`	`42`	`*`
`43`		`- * @param \PDO $pdo The PDO.`
`44`		`- * @param int $timeout The timeout in seconds, default is 3.`
	`43`	`+ * @param \PDO $pdo The PDO.`
	`44`	`+ * @param float $timeout The timeout in seconds, default is 3.`
`45`	`45`	`*`
`46`	`46`	`* @throws \LengthException The timeout must be greater than 0.`
`47`	`47`	`*/`
`48`		`- public function __construct(\PDO $pdo, int $timeout = 3)`
	`48`	`+ public function __construct(\PDO $pdo, float $timeout = 3)`
`49`	`49`	`{`
`50`	`50`	`if ($pdo->getAttribute(\PDO::ATTR_ERRMODE) !== PDO::ERRMODE_EXCEPTION) {`
`51`	`51`	`throw new InvalidArgumentException('The pdo must have PDO::ERRMODE_EXCEPTION set.');`