Improve documentation

README.md

@@ -47,8 +47,12 @@ $lock = new Lock(RPC::create('tcp://127.0.0.1:6001'));
 
 ### Acquire lock
 
-Locks a resource so that it can be accessed by one process at a time. When a resource is locked, other processes that
-attempt to lock the same resource will be blocked until the lock is released.
+Locks a resource so that it can be accessed by one process at a time.
+
+By default the call is **non-blocking**: if the resource is already locked, it returns `false` almost immediately
+(the RoadRunner server caps the default `wait` window at `1ms`). Pass a positive `wait` to block until the lock is
+released — the call then returns the lock id as soon as the lock becomes free, or `false` when the `wait` timeout
+elapses.
 
 ```php
 $id = $lock->lock('pdf:create');
@@ -70,8 +74,11 @@ $id = $lock->lock('pdf:create', id: '14e1b600-9e97-11d8-9f32-f2801f1b9fd1');
 ### Acquire read lock
 
 Locks a resource for shared access, allowing multiple processes to access the resource simultaneously. When a resource
-is locked for shared access, other processes that attempt to lock the resource for exclusive access will be blocked
-until all shared locks are released.
+is locked for shared access, other processes that attempt to lock the resource for exclusive access will fail to do so
+while any shared lock is held.
+
+As with `lock()`, the `wait` parameter is non-blocking by default (`false` is returned almost immediately, within the
+server's `1ms` window); pass a positive `wait` to block for up to that duration for the lock to become available.
 
 ```php
 $id = $lock->lockRead('pdf:create', ttl: 10);

src/Lock.php

@@ -25,13 +25,19 @@ public function __construct(
     /**
      * Lock a resource for exclusive access
      *
-     * Locks a resource so that it can be accessed by one process at a time. When a resource is locked,
-     * other processes that attempt to lock the same resource will be blocked until the lock is released.
+     * Locks a resource so that it can be accessed by one process at a time. By default the call is non-blocking:
+     * if the resource is already locked, it returns false immediately. Pass a positive $waitTTL to wait for the
+     * lock to be released instead.
      *
      * @param non-empty-string $resource The name of the resource to be locked.
      * @param non-empty-string|null $id The lock ID. If not specified, a random UUID will be generated.
      * @param int|float|DateInterval $ttl The time-to-live of the lock, in seconds. Defaults to 0 (forever).
-     * @param int|float|DateInterval $waitTTL How long to wait to acquire lock until returning false.
+     * @param int|float|DateInterval $waitTTL How long to wait for the lock to become free before giving up, in seconds.
+     *                                         Defaults to 0. With 0 the call is effectively non-blocking: the RoadRunner
+     *                                         server caps the acquire window at defaultImmediateTimeout (1ms), so false
+     *                                         is returned almost immediately when the resource is already locked. A
+     *                                         positive value blocks for up to that duration, returning the lock id as
+     *                                         soon as the lock is released, or false on timeout.
      * @return false|non-empty-string Returns lock ID if the lock was acquired successfully, false otherwise.
      *
      * @throws \InvalidArgumentException If ttl is negative.
@@ -63,7 +69,12 @@ public function lock(
      * @param non-empty-string $resource The name of the resource to be locked.
      * @param non-empty-string|null $id The lock ID. If not specified, a random UUID will be generated.
      * @param int|float|DateInterval $ttl The time-to-live of the lock, in seconds. Defaults to 0 (forever).
-     * @param int|float|DateInterval $waitTTL How long to wait to acquire lock until returning false.
+     * @param int|float|DateInterval $waitTTL How long to wait for the lock to become free before giving up, in seconds.
+     *                                         Defaults to 0. With 0 the call is effectively non-blocking: the RoadRunner
+     *                                         server caps the acquire window at defaultImmediateTimeout (1ms), so false
+     *                                         is returned almost immediately when the resource is already locked. A
+     *                                         positive value blocks for up to that duration, returning the lock id as
+     *                                         soon as the lock is released, or false on timeout.
      * @return false|non-empty-string Returns lock ID if the lock was acquired successfully, false otherwise.
      *
      * @throws \InvalidArgumentException If ttl is negative.

src/LockInterface.php

@@ -9,13 +9,19 @@ interface LockInterface
     /**
      * Lock a resource for exclusive access.
      *
-     * Locks a resource so that it can be accessed by one process at a time. When a resource is locked,
-     * other processes that attempt to lock the same resource will be blocked until the lock is released.
+     * Locks a resource so that it can be accessed by one process at a time. By default the call is non-blocking:
+     * if the resource is already locked, it returns false immediately. Pass a positive $waitTTL to wait for the
+     * lock to be released instead.
      *
      * @param non-empty-string $resource The name of the resource to be locked.
      * @param non-empty-string|null $id The lock ID. If not specified, a random UUID will be generated.
      * @param int|float|\DateInterval $ttl The time-to-live of the lock, in seconds. Defaults to 0 (forever).
-     * @param int|float|\DateInterval $waitTTL How long to wait to acquire lock until returning false.
+     * @param int|float|\DateInterval $waitTTL How long to wait for the lock to become free before giving up, in seconds.
+     *                                          Defaults to 0. With 0 the call is effectively non-blocking: the RoadRunner
+     *                                          server caps the acquire window at defaultImmediateTimeout (1ms), so false
+     *                                          is returned almost immediately when the resource is already locked. A
+     *                                          positive value blocks for up to that duration, returning the lock id as
+     *                                          soon as the lock is released, or false on timeout.
      * @return false|non-empty-string Returns lock ID if the lock was acquired successfully, false otherwise.
      */
     public function lock(
@@ -35,7 +41,12 @@ public function lock(
      * @param non-empty-string $resource The name of the resource to be locked.
      * @param non-empty-string|null $id The lock ID. If not specified, a random UUID will be generated.
      * @param int|float|\DateInterval $ttl The time-to-live of the lock, in seconds. Defaults to 0 (forever).
-     * @param int|float|\DateInterval $waitTTL How long to wait to acquire lock until returning false.
+     * @param int|float|\DateInterval $waitTTL How long to wait for the lock to become free before giving up, in seconds.
+     *                                          Defaults to 0. With 0 the call is effectively non-blocking: the RoadRunner
+     *                                          server caps the acquire window at defaultImmediateTimeout (1ms), so false
+     *                                          is returned almost immediately when the resource is already locked. A
+     *                                          positive value blocks for up to that duration, returning the lock id as
+     *                                          soon as the lock is released, or false on timeout.
      * @return false|non-empty-string Returns lock ID if the lock was acquired successfully, false otherwise.
      */
     public function lockRead(