redis_queued_locks 1.23.0 → 1.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c06bae2bc7f0b6164847caa6b7adb5c77a7aab5a85dc5f3ef8c45ac19b8ed80
-  data.tar.gz: 6a73267ecd535b74c98f489066ee5cc6f2a8c2ea261eab6d5b5f6b84e4748585
+  metadata.gz: ad3786d20407687dc7cfdb06956fecec429c199c4fb50d984af30afa15899352
+  data.tar.gz: cd71e3b222e1267ddbb29b34c2f2de66be834d9100a97d86b3cb3e3fc952f87b
 SHA512:
-  metadata.gz: b3f34d6976337bcdfe4732b3c58034ed455922450f98758a0f4c90e36a885721d847e648c5dfa64357aac9b1b401138787649bda0491693777581669f932a187
-  data.tar.gz: 7d4e8769653ddfaf0f483a413c08ba10ea15d4f4d324e57dee1009e27222f7c2473789b0221380fc68a0047a5383083761963ed541179f7ab633876f68b3e891
+  metadata.gz: 44dff1c6e0b2321b75cea2efea7094ffa47c88e8a0e8095e49d030f823048ff0834916030feba524ca354f3559ef97afc5d803c3fe41b88017ff6751bf9c479d
+  data.tar.gz: 73ad1a2679f8c84b5672e95036c06831a415c02878683ac886ac752552352c2d7d1d444fc34e6daf6f0eeef4e21bce02d925b5c4821cdb7df0cae834e53de022

data/.claude/project-overview.md

@@ -174,7 +174,7 @@ AcquireLock Step 0.1 / LockSeries Step 0.1              name -> Integer, range -
 | `WithAcqTimeout` | Global acquisition timeout (`timeout`). |
 | `DelayExecution` | Retry delay + jitter between attempts. |
 | `DequeueFromLockQueue` | Removes the acquirer from the queue of the requested mode on timeout/failure. |
-| `YieldExpire` | Runs the user block (optionally `timed`), then releases/expires the lock of the held mode (write: `EXPIRE 0`; read: `ZREM` own reader + `DEL` own read lock data; extendable reentrant: decrease). Known limitation (kept by the user's decision, documented in README): the write release and the write ttl decrease have no owner check, so a block longer than the ttl can delete/shorten the lock of another acquirer. |
+| `YieldExpire` | Runs the user block (optionally `timed`: budget = `ttl` - time from the start of the successful attempt - `REDIS_TIMESHIFT_ERROR`, always within the lock lifetime; no budget left => the block is not invoked, `LockTtlTimeBudgetIsSpentError`; the budget exceeded => `TimedBlockExceedsLockTtlError`; `Timeout.timeout(0)` means no timeout; a long `ensure` of the block, `rescue Exception` and non-interruptible code can still outlive the lock), then releases/expires the lock of the held mode (write: `EXPIRE 0`; read: `ZREM` own reader + `DEL` own read lock data; extendable reentrant: decrease). Known limitation (kept by the user's decision, documented in README): the write release and the write ttl decrease have no owner check, so a block longer than the ttl can delete/shorten the lock of another acquirer. |
 | `LogVisitor` / `InstrVisitor` | One method per lifecycle event for logs and instrumentation. |
 
 ### Lock series (`acquirer/lock_series.rb`)
@@ -483,7 +483,7 @@ log event: `dead_request_removed` (`dead_acq_id`, `dead_priority`: a dead blocki
 
 Global base errors per branch (`logic.md#15`): `RedisQueuedLocks::Error < StandardError` (the main
 hierarchy: `LockAlreadyObtainedError`, `LockAcquirementTimeoutError`, `LockAcquirementRetryLimitError`,
-`TimedLockTimeoutError`, `ConflictLockObtainError`, `SwarmError`, `ConfigError` (`ConfigNotFoundError`,
+`TimedLockTimeoutError` (`LockTtlTimeBudgetIsSpentError`, `TimedBlockExceedsLockTtlError`), `ConflictLockObtainError`, `SwarmError`, `ConfigError` (`ConfigNotFoundError`,
 `ConfigValidationError`)), `RedisQueuedLocks::ArgumentError < ::ArgumentError` (`SwarmArgumentError`),
 `RedisQueuedLocks::Exception < ::Exception` (`@api private`, super exceptional cases only: the internal
 `*IntermediateTimeoutError`s of `Timeout.timeout` for `timeout` and `timed`; like `Timeout::ExitException`,

data/.claude/rules/acquirer.md

@@ -65,6 +65,7 @@ paths:
   - `TryToLock` attempt (both modes): `multi(watch:)` (write: `[lock_key, lock_readers_key]`, read: `[lock_key]`) → one pipelined state read (`HGET acq_id`, `TIME`, own reader score, longest reader: write requests only, the write-only tail of the pipeline) → same-process conflict detection (`sp_conflict_rw_mode` = held `:write`/`:read`) → the lock request queueing in one pipelined round trip (`queue_lock_request`: prune dead requests of the request's priority band in **both** queues (before `ZADD NX`: the old dead position of a requeued request is dropped before its new position is added; the reverse order keeps the old position with `NX` and drops it: the request is missing in the queue for the attempt) → `ZADD NX` into the queue of the requested mode (the position is shifted by the priority band) → queue heads of both queues (`WITHSCORES`) → (the enabled lock index only) request queue `PEXPIRE NX`+`GT` → lock index `ZADD GT` → lock index pruning (5 replies, 9 with the lock index; new commands go to the end, replies after the queue heads are not read); eager queueing (`:wait_for_lock`/`:dead_locking` without `fail_fast`) sends these commands in the state pipeline right after its head, so `lock {}` = 4 round trips; the queueing log events are still emitted in the classic branch in the same order) → Step 2.2 (priorities, `:queued`, also in the pre-check, before the obstacle decision): the dead blocking requests of other bands (the write queue head for writers and the earlier opposite-mode request, decoded from their scores by `dead_request_priority`) are dropped with their bands in both queues and both heads are re-read in one more round trip (`drop_dead_requests_ahead`: one or two bands per round trip, the heads are read from the end of the pipeline, up to `MAX_DEAD_REQUEST_REMOVALS` round trips, `try_lock.dead_request_removed` log per dropped request, written by the caller (`log_dropped_requests`) after the queueing events; no round trip while the blocking requests are alive; a live write queue head stops the removal) (`:queued`: write must be first in its queue; any mode waits for an earlier `(score, acq_id)` request of the opposite mode) → lock state (write held → `:lock_is_still_acquired`; live readers for write / own live read for read → `:read_lock_is_still_acquired`) → MULTI (write: `ZREM` + `HSET` + `PEXPIRE` (+ lock index `ZADD GT`); read: `ZREM` + prune registry + `ZADD expiry` + registry `PEXPIRE NX`+`GT` + reader data `DEL`+`HSET`+`PEXPIRE` (+ lock index `ZADD GT`)). With the enabled lock index the `:extendable_work_through` extension `MULTI` ends with the lock index `ZADD XX INCR` (write: 4 replies, 5 with the lock index: `result.size == (lock_index_enabled ? 5 : 4)`).
   - The try result carries internal `rw_mode` (the **held** lock mode); `acquire_lock` stores it as `acq_process[:held_rw_mode]` and passes it to `yield_expire`, which releases/decreases the held lock. The public `lock` result shape does not include it.
   - Read lock data (`rql:lock_reader:<name>:<acq_id>`) uses the write-lock field format without `acq_id`/`hst_id` (`ts`, `ini_ttl`, meta, `spc_*`: both ids are derived from the acquirer id, `LockInfo.read_lock_info`/`Locks.read_lock_info` put them first in each reader and still accept older data that contains them) and the read lock TTL; it is a data carrier only (writers never read it). Its key (`read_lock_key`) is built only for read lock requests (`nil` for write requests: they never hold read locks).
+  - `timed` budget (`AcquireLock`, `LockSeries`): `ttl - ttl_shift`, `ttl_shift` = time from `acq_process[:try_start_time]` (the start of the successful attempt: the ttl starts later: write: `EXEC`, read: `TIME` of the lock state read) + `REDIS_TIMESHIFT_ERROR` (a margin: it always shortens the budget); no budget left (`0.0`) => `yield_with_timeout` does not invoke the block (`Timeout.timeout(0)` means no timeout): `LockTtlTimeBudgetIsSpentError`; a block that exceeds the budget: `TimedBlockExceedsLockTtlError` (both are `TimedLockTimeoutError` subclasses).
   - Timing via monotonic `clock_gettime` (microseconds); wall time only for `at:`/`ts` fields.
 - **LockSeries** (`lock_series.rb`, `lock_series/try_to_lock_series.rb`, `lock_series/release_lock_series.rb`; overview "Lock series"):
   - The attempt is the single lock attempt for N locks, built from the shared `TryToLock` helpers: lock state and queueing commands (`pipeline_lock_state`, `queue_lock_request`), decisions (`same_process_conflict_status`, `find_opposite_request_ahead`, `lock_obstacle`, `find_dead_requests_ahead`, `pipeline_dead_requests_ahead_removal`), obtaining and reentrant commands (`transact_*`). A change of these helpers applies to both attempts; a change of the single lock attempt flow is checked against `try_to_lock_series`/`precheck_lock_series` (two copies of the flow, not of the commands).

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.23.1] = 2026-11-01
+### Added
+- `timed: true` of `#lock`/`#lock_series`: separate errors of the failures, both are `TimedLockTimeoutError` subclasses: `LockTtlTimeBudgetIsSpentError` (the block was not invoked: no time left) and `TimedBlockExceedsLockTtlError` (the block exceeded the lock TTL);
+### Fixed
+- `timed: true` of `#lock`/`#lock_series`: in some cases the time budget of the block could have been a little bit longer than the lock lifetime (2ms);
+
 ## [1.23.0] - 2026-11-01
 ### Changed
 - [**Breaking**] `#lock_series`/`#lock_series!` are no longer a proof of concept. The final feature design:

data/README.md

@@ -589,6 +589,11 @@ def lock(
   - the block is interrupted by an internal `RedisQueuedLocks::Exception` (an `::Exception`, like `Timeout::ExitException` of Ruby's `Timeout`): `rescue => e`,
     `rescue StandardError`, `rescue Timeout::Error` and `rescue nil` inside the block can not swallow it (only `rescue Exception`),
     `ensure` of the block still runs;
+  - the block gets the lock's TTL minus the time from the start of the successful acquirement attempt and minus a 2 ms margin;
+    with no time left the block is not invoked (`RedisQueuedLocks::LockTtlTimeBudgetIsSpentError`);
+  - both failures have the common superclass `RedisQueuedLocks::TimedLockTimeoutError`: `RedisQueuedLocks::TimedBlockExceedsLockTtlError` (the block exceeded the time) and `RedisQueuedLocks::LockTtlTimeBudgetIsSpentError` (the block was not invoked);
+  - (limitation) `timed` can only interrupt the block: a long `ensure` of the block, `rescue Exception` in the block and the code that
+    can not be interrupted (a C extension holding the GVL) can outlive the lock;
   - pre-configured in `config['is_timed_by_default']`;
   - `false` by default;
 - `retry_count` - (optional) `[Integer,NilClass]`
@@ -837,7 +842,7 @@ rql.lock("my_lock", ttl: 5_000, timed: true) { sleep(4) }
 # => OK
 
 rql.lock("my_lock", ttl: 5_000, timed: true) { sleep(6) }
-# => fails with RedisQueuedLocks::TimedLockTimeoutError
+# => fails with RedisQueuedLocks::TimedBlockExceedsLockTtlError (a RedisQueuedLocks::TimedLockTimeoutError)
 ```
 
 - infinite lock obtaining (no retry limit, no timeout limit):
@@ -3528,6 +3533,12 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **Major**:
+  - **Experimental feature**: (non-`timed` locks): per-ruby-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
+    the acquired lock for long-running blocks of code (that invoked "under" the lock
+    whose ttl may expire before the block execution completes). It makes sense for non-`timed` locks *only*;
+  - think about "thread priority" configuration :thinking:;
+  - add `hst_id` to all methods that works with queues info;
+  - try to return the `fiber object id` to the lock host identifier (we cant use fiber object id cuz `ObjectSpace` has no access to the fiber object space after the any ractor object initialization)
   - Swarm:
     - circuit-breaker for long-living failures of your infrastructure inside the swarm elements and supervisor:
       the supervisor will stop (for some period of time or while the some factor will return `true`)
@@ -3553,9 +3564,6 @@ Detalized event semantics and payload structure:
   - an ability to return all insturmentation metrics from the `lock` invocation (and after block `yield`ing);
   - think about a PG-like `stats`-data/table, that should be helpful for lock history acquirement analyzation :thinking: (suitable for cases when we want
     to check if the lock was acquired by some different parallel process durign the some period of time in the past or not);
-  - think about "thread priority" configuration :thinking:;
-  - add `hst_id` to all methods that works with queues info;
-  - try to return the `fiber object id` to the lock host identifier (we cant use fiber object id cuz `ObjectSpace` has no access to the fiber object space after the any ractor object initialization)
   - named RQL's threads (`Thread#name`) and RQL's ractors (`Ractor#name`) in order to have an ability to find and work with RQL's threads and ractors outside of RQL logic (stop threads before process forking, for example);
   - `#lock`/`#lock!` - `timeout:` option: support for granular periods (it supports only `seconds` at the moment, but we need `milliseconds`);
   - Add `after timeout hook` ability for timeout errors with an ability to access the binding context (if it possibly) of the thread where it failed;
@@ -3567,9 +3575,6 @@ Detalized event semantics and payload structure:
   - support for `Dragonfly` database backend (https://github.com/dragonflydb/dragonfly) (https://www.dragonflydb.io/);
   - (_research_) GVL-isolation for lock acquirement logic (try to bypass Ruby's "context-switching" in order to prevent any time-based affects on lock-acquirement logic);
   - Semantic error objects for unexpected Redis errors;
-  - **Experimental feature**: (non-`timed` locks): per-ruby-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
-    the acquired lock for long-running blocks of code (that invoked "under" the lock
-    whose ttl may expire before the block execution completes). It makes sense for non-`timed` locks *only*;
   - sized lock queues (with an ability of dynamically growing size);
   - better code stylization (+ some refactorings);
   - `RedisQueuedLocks::Acquirer::Try.try_to_lock` - detailed successful result analization;

data/lib/redis_queued_locks/acquirer/acquire_lock/yield_expire.rb

@@ -3,6 +3,7 @@
 # @api private
 # @since 1.3.0
 # @version 1.18.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   require_relative 'yield_expire/log_visitor'
 
@@ -158,21 +159,37 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   # @return [Any]
   #
   # @raise [RedisQueuedLocks::TimedLockTimeoutError]
+  # @raise [RedisQueuedLocks::LockTtlTimeBudgetIsSpentError]
+  # @raise [RedisQueuedLocks::TimedBlockExceedsLockTtlError]
   #
   # @api private
   # @since 1.3.0
-  # @version 1.21.0
+  # @version 1.23.1
   def yield_with_timeout(timeout, lock_key, lock_ttl, acquirer_id, host_id, meta, &block)
-    ::Timeout.timeout(timeout, RedisQueuedLocks::TimedLockIntermediateTimeoutError, &block)
-  rescue RedisQueuedLocks::TimedLockIntermediateTimeoutError
-    raise(
-      RedisQueuedLocks::TimedLockTimeoutError,
-      "Passed <timed> block of code exceeded the lock TTL " \
-      "(lock: \"#{lock_key}\", " \
-      "ttl: #{lock_ttl}, " \
-      "meta: #{meta ? meta.inspect : '<no-meta>'}, " \
-      "acq_id: \"#{acquirer_id}\", " \
-      "hst_id: \"#{host_id}\")"
-    )
+    # NOTE: no budget left => the block is not invoked (`Timeout.timeout(0)` means "no timeout")
+    if timeout == 0.0
+      raise(
+        RedisQueuedLocks::LockTtlTimeBudgetIsSpentError,
+        "Passed <timed> block of code was not invoked: the time budget of the lock TTL is spent " \
+        "(lock: \"#{lock_key}\", ttl: #{lock_ttl}, " \
+        "meta: #{meta ? meta.inspect : '<no-meta>'}, " \
+        "acq_id: \"#{acquirer_id}\", " \
+        "hst_id: \"#{host_id}\")"
+      )
+    else
+      begin
+        ::Timeout.timeout(timeout, RedisQueuedLocks::TimedLockIntermediateTimeoutError, &block)
+      rescue RedisQueuedLocks::TimedLockIntermediateTimeoutError
+        raise(
+          RedisQueuedLocks::TimedBlockExceedsLockTtlError,
+          "Passed <timed> block of code exceeded the lock TTL " \
+          "(lock: \"#{lock_key}\", ttl: #{lock_ttl}, " \
+          "meta: #{meta ? meta.inspect : '<no-meta>'}, " \
+          "acq_id: \"#{acquirer_id}\", " \
+          "hst_id: \"#{host_id}\")"
+        )
+      end
+    end
   end
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/acquirer/acquire_lock.rb

@@ -193,7 +193,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.23.0
+    # @version 1.23.1
     def acquire_lock(
       redis,
       lock_name,
@@ -412,6 +412,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         tries: 0,
         acquired: false,
         result: nil,
+        try_start_time: nil,
         acq_time: nil, # NOTE: in milliseconds
         hold_time: nil, # NOTE: in milliseconds
         rel_time: nil # NOTE: in milliseconds
@@ -472,6 +473,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             )
           end
 
+          acq_process[:try_start_time] = clock_gettime
+
           # NOTE: (steep ignorance) pattern matching is not supported in steep
           # steep:ignore:start
           try_to_lock(
@@ -662,8 +665,14 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           begin
             yield_time = clock_gettime
 
+            # NOTE: the budget of a `timed` block (see `Resource::REDIS_TIMESHIFT_ERROR`):
+            #   - the lock ttl starts inside the attempt (write: `EXEC` of the transaction,
+            #     read: `TIME` of the lock state read), this moment is unknown on the client:
+            #     the time is counted from the start of the successful attempt (it is
+            #     earlier, the budget can only be shorter than the real lifetime of the lock);
+            #   - the Redis time error is a margin: it decreases the budget;
             ttl_shift = (
-              (yield_time - acq_process[:acq_end_time]) / 1_000.0 -
+              (yield_time - acq_process[:try_start_time]) / 1_000.0 +
               RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
             ).ceil(2)
 

data/lib/redis_queued_locks/acquirer/lock_series.rb

@@ -126,7 +126,7 @@ module RedisQueuedLocks::Acquirer::LockSeries
     #
     # @api private
     # @since 1.23.0
-    # @version 1.23.0
+    # @version 1.23.1
     # rubocop:disable Metrics/MethodLength
     def lock_series(
       redis,
@@ -356,6 +356,7 @@ module RedisQueuedLocks::Acquirer::LockSeries
         ts: nil, # NOTE: see `try_to_lock_series`
         lock_processes: nil, # NOTE: see `try_to_lock_series`
         held_rw_modes: nil, # NOTE: see `try_to_lock_series`
+        try_start_time: nil,
         acq_time: nil, # NOTE: in milliseconds
         acq_end_time: nil,
         rel_ts: nil,
@@ -404,6 +405,8 @@ module RedisQueuedLocks::Acquirer::LockSeries
                 )
               end
 
+              acq_process[:try_start_time] = clock_gettime
+
               attempt = try_to_lock_series(
                 redis,
                 logger,
@@ -536,8 +539,14 @@ module RedisQueuedLocks::Acquirer::LockSeries
             host_id, acq_process[:ts], acq_process[:acq_time], reentrant_lock_keys, instrument
           )
 
+          # NOTE: the budget of a `timed` block (see `Resource::REDIS_TIMESHIFT_ERROR`):
+          #   - the lock ttl starts inside the attempt (write: `EXEC` of the transaction,
+          #     read: `TIME` of the lock state read), this moment is unknown on the client:
+          #     the time is counted from the start of the successful attempt (it is
+          #     earlier, the budget can only be shorter than the real lifetime of the lock);
+          #   - the Redis time error is a margin: it decreases the budget;
           ttl_shift = (
-            (clock_gettime - acq_process[:acq_end_time]) / 1_000.0 -
+            (clock_gettime - acq_process[:try_start_time]) / 1_000.0 +
             RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
           ).ceil(2)
 

data/lib/redis_queued_locks/errors.rb

@@ -67,6 +67,14 @@ module RedisQueuedLocks
   # @since 1.0.0
   class TimedLockTimeoutError < Error; end
 
+  # @api public
+  # @since 1.23.1
+  class LockTtlTimeBudgetIsSpentError < TimedLockTimeoutError; end
+
+  # @api public
+  # @since 1.23.1
+  class TimedBlockExceedsLockTtlError < TimedLockTimeoutError; end
+
   # @api public
   # @since 1.3.0
   class ConflictLockObtainError < Error; end

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.23.0
-  VERSION = '1.23.0'
+  # @version 1.23.1
+  VERSION = '1.23.1'
 end

data/sig/redis_queued_locks/errors.rbs

@@ -26,6 +26,12 @@ module RedisQueuedLocks
   class TimedLockTimeoutError < Error
   end
 
+  class LockTtlTimeBudgetIsSpentError < TimedLockTimeoutError
+  end
+
+  class TimedBlockExceedsLockTtlError < TimedLockTimeoutError
+  end
+
   class ConflictLockObtainError < Error
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.23.0
+  version: 1.23.1
 platform: ruby
 authors:
 - Rustam Ibragimov