From e1f72da9e7aab55197aaf08a4ca70a72af3b7e08 Mon Sep 17 00:00:00 2001 From: Alexander Strizhak Date: Wed, 8 Jul 2026 20:18:02 +0300 Subject: [PATCH] Document RoadRunnerStore ttl / waitTtl options; fix wrong defaults MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The constructor docblock claimed `$initialTtl` "Defaults to 0 (forever)", but the actual default is 300 seconds. `$initialWaitTtl` had no explanation of what its default of 0 does. `withTtl()` carried the same misleading "Defaults to 0 (forever)" text for a required `$ttl` argument. - Fix the `$initialTtl` default (300, not 0) in the constructor docblock. - Document `$initialWaitTtl`: default 0 is effectively non-blocking (the RoadRunner server caps a 0 wait at 1ms), a positive value blocks. - Clean up the `withTtl()` docblock (no bogus default; describe null waitTtl). - Add a "Store options" section to the README with a defaults table and a withTtl() example. Docs only — no behavior changes. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 14 ++++++++++++++ src/RoadRunnerStore.php | 16 +++++++++++----- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 427aa03..c9c713a 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,20 @@ $factory = new LockFactory( ); ``` +### Store options + +`RoadRunnerStore` accepts two timing options: + +| Option | Default | Description | +|------------------|---------------|-------------| +| `$initialTtl` | `300.0` | Default lock time-to-live, in seconds. When it elapses the lock is released automatically; `0` means it never expires on its own. | +| `$initialWaitTtl`| `0` | Default time to wait for the lock to become free, in seconds. `0` is effectively **non-blocking**: the RoadRunner server caps a `0` wait at `1ms`, so acquiring an already-held lock fails almost immediately. A positive value blocks for up to that duration. | + +```php +// Wait up to 5 seconds for the lock, and hold it for at most 30 seconds. +$store = (new RoadRunnerStore($lock))->withTtl(ttl: 30.0, waitTtl: 5.0); +``` + Read more about using Symfony Lock component [here](https://symfony.com/doc/current/components/lock.html). ## Contributing diff --git a/src/RoadRunnerStore.php b/src/RoadRunnerStore.php index 3c064fc..dbdd03c 100644 --- a/src/RoadRunnerStore.php +++ b/src/RoadRunnerStore.php @@ -18,8 +18,12 @@ final class RoadRunnerStore implements SharedLockStoreInterface, BlockingStoreIn use ExpiringStoreTrait; /** - * @param float $initialTtl The time-to-live of the lock, in seconds. Defaults to 0 (forever). - * @param float $initialWaitTtl How long to wait to acquire lock until returning false. + * @param float $initialTtl Default lock time-to-live, in seconds. Defaults to 300. When it elapses the lock is + * released automatically; 0 means the lock never expires on its own. + * @param float $initialWaitTtl Default time to wait for the lock to become free before giving up, in seconds. + * Defaults to 0, which is effectively non-blocking: the RoadRunner server caps a 0 + * wait at 1ms, so acquiring an already-held lock fails (throws LockConflictedException) + * almost immediately. A positive value blocks for up to that duration. */ public function __construct( private readonly RR\LockInterface $lock, @@ -32,9 +36,11 @@ public function __construct( } /** - * Clone current instance with another values of ttl. - * @param float $ttl The time-to-live of the lock, in seconds. Defaults to 0 (forever). - * @param float $waitTtl How long to wait to acquire lock until returning false, in seconds. + * Clone the current instance with different ttl / waitTtl values. + * + * @param float $ttl Lock time-to-live, in seconds. 0 means the lock never expires on its own. + * @param float|null $waitTtl Time to wait for the lock to become free, in seconds. Null keeps the current + * instance's waitTtl. See the constructor for the meaning of 0 (non-blocking). */ public function withTtl(float $ttl, ?float $waitTtl = null): self {