redis_queued_locks 1.15.1 → 1.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f196a3e198011c805f10df6ba3c2110471b85e0f7e3629a8d6c0594329c6a61c
-  data.tar.gz: 00d1067ee165b563380b0e2061af8c73e37466e8a55b2f43c8f119069fd90b39
+  metadata.gz: 0bd0b3bb446d6ce5af47949de25834b0c4f87a3fcb1090bf9604fba129354468
+  data.tar.gz: b9c8c49560e193db92d63fc232c31fbdf1ea03b72b28fc778c3fcc22da3af1d1
 SHA512:
-  metadata.gz: 6b6066096f58daeafab9c6c06f815628be1d2b32a56374f1fc3d1d6cdcff4f7aba6271d20efc16c0439084e629b6867e66eeb58d0091454b5441e29310fcb83b
-  data.tar.gz: 43751ba0011d662474c47ad014620d2b43d4555f04ae41f1a23ac1f7072aa20736a430e5a7db2a494449fe3245331e48bcf8453b91ba56c4ceba08dafaf5ed42
+  metadata.gz: dcea0a7ee67e7a727fe0d92d88bf8f6b0a946c279fce3d43f34e6fe05844cf156e9679d91fcd12f450ebd9029a0aabd9f61b9c5224b7a88fa4551202bd716939
+  data.tar.gz: 0c0b132e65106ce28f68a41278adc7981150b3a50d73952f55bfa22d0b735e8713924a20adca4caedd0fb744587a5675cbab0a78339c02d695b516129a2bd480

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## [Unreleased]
 
+## [1.16.1] - 2026-01-28
+### Changed
+- `lock_series` PoC:
+  - added own instrumentation visitor and log ivsitor (`RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor` and
+   `RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor` respectively) and all `lock_series`-related
+   instrumentation/log methods were moved to these modules;
+  - documentaiton updates;
+- YARDOC documentaiton updates;
+### Added
+- `lock_series` PoC updates:
+  - added missing instrumentation event `lock_series_obtained`;
+  - added more data to the `detailed_event: true` lock invocation result:
+    - `locks_release_strategy` - `:immediate_release_after_yield` or `:redis_key_ttl`
+### Fixed
+- `lock_series` PoC:
+  - incorrect instrumentation/logs data:
+    - `expire_lock_series` log and instrumentation event should not be produced
+      when locks were obtained without a block of code (for this case obtained locks
+      lives in redis with their TTL);
+    - `locks_released_at` and `locks_hold_time` of the detailed invocation result (`detailed: true`)
+      has nil values in case when locks are obtained without a block of code
+      (lokcs are not released at this moment and lives in redis with their TTL);
+
+## [1.16.0] - 2026-01-27
+### Added
+- Brand new Feature **"Lock series of locks"**
+  - (*Proof of Concpet*-based implementation at the moment) 
+  - lock series of lock simultainously (and release them all at the finish of your the invocation of block of code under the obtained locks);
+  - exmaple: `client.lock_series("a", "b", "c")` (or in exceptional-based way `client.lock_series!("a", "b", "c")`;
+### Changed
+- YARDOC documentation updates in order to prearet to the 100% yardoc-coverage;
+- updated dev deps;
+### Fixed
+- fixed some yardoc documentation typos;
+
 ## [1.15.1] - 2025-10-22
 ### Fixed
 - **Config Layer**:

data/README.md

@@ -23,6 +23,8 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 - [Usage](#usage)
   - [lock](#lock---obtain-a-lock)
   - [lock!](#lock---exceptional-lock-obtaining)
+  - [lock_series (PoC)](#lock_series---poc-acquire-a-series-of-locks)
+  - [lock_series! (PoC)](#lock_series---poc-exceptional-lock_series)
   - [lock_info](#lock_info)
   - [queue_info](#queue_info)
   - [locked?](#locked)
@@ -850,6 +852,120 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 
 ---
 
+#### #lock_series - (PoC) acquire a series of locks
+
+> (IMPORTANT!) "Proof of Concept" realization. Will be reworked in the future (very-very soon)
+
+`lock_series` - acquire a series of locks simultaniously and hold them all while your block of code is executing
+or (if block is not passed) while all locks will not expire.
+
+If it is not possible to obtain all locks at the same time (taking into queue ttl, retry attempts count for each lock, etc)
+- no any lock will be acquired.
+
+Method options is the same as for `lock` method: `retry_count`, `retry_jitter`, `ttl`, `queue_ttl`, etc. Each option will be
+applied with the same value to the each lock acquirement process (for each lock in a series separately).
+
+**IMPORTANT DETAILS AND LIMITATIONS**:
+- (this behavior will be reworked with another algorithm in future);
+- each lock will be released with the next formula: 
+  - `lock position with reverse numbering` * `ttl`
+    - (positions exmaple: ["a", "b", "c"] => "a" position is 3, "b" position is 2, "c" position is 1);
+  - this means that in case of 3 locks (`lock_series("x", "y", "z", ttl: 5_000`) with `5 seconds TTL` your locks will be with the next TTL:
+    - `"x"` - 15 seconds
+    - `"y"` - 10 seconds
+    - `"z"` - 5 seconds
+- when your block of code has completed their execution - all locks will be released immediatly;
+- if you did not pass a block - all locks will be released with their forumla-based TTL described above;
+  - **HOW WILL THIS CASE WORK IN FUTURE RELESAE**: all locks will have the same TTL (`5 seconds` for our example, not `15/10/5 seconds`);
+
+##### How to use:
+
+- method signature is the same as the `lock` method;
+
+```ruby
+# typical logic-oriented way
+client.lock_series("a", "b", "c") { ...some_code... }
+
+# result-oriented way:
+# - (block is passed)
+detailed_result = client.lock_series('x', 'y', 'z', detailed_result: true) { 1 + 2 }
+detailed_result # =>
+{
+  yield_result: 3, # result of your block of code
+  lock_release_strategy: :immediate_release_after_yield, # (block is passed)
+  locks_released_at: 1769506100.676884, # (instrumentation) release time, epoch
+  locks_acq_time: 7.0, # (instrumentation) time spent to acquire all locks, milliseconds
+  locks_hold_time: 0.65, # (instrumentation) lock series hold period (hold preiod of all required locks), milliseconds
+  lock_series: ["x", "y", "z"], # your locks
+  rql_lock_series: ["rql:lock:x", "rql:lock:y", "rql:lock:z"] # internal RQL lock-keys of your locks
+}
+
+# - (block is not passed)
+detailed_result = client.lock_series('x', 'y', 'z', detailed_result: true)
+detailed_result # =>
+{
+  yield_result: nil, # block is not given - nothing to return
+  lock_release_strategy: :redis_key_ttl, # block is not given - locks are living in redis with their TTL
+  locks_released_at: nil, # (instrumentation) # block is not given - locks are living in redis with their TTL
+  locks_acq_time: 7.0, # (instrumentation) time spent to acquire all locks, milliseconds
+  locks_hold_time: nil, # (instrumentation) # block is not given - locks are living in redis with their TTL
+  lock_series: ["x", "y", "z"], # your locks
+  rql_lock_series: ["rql:lock:x", "rql:lock:y", "rql:lock:z"] # internal RQL lock-keys of your locks
+}
+```
+
+```ruby
+# (failed lock obtainig) when lock series can not be obtained for some reasons
+# for example: one of required lock in series is still obtained and can not be obtained now (and all retries are exhausted)
+
+# - lock 'a' is obtained with long ttl
+client.lock('a', ttl: 10_000_000)
+
+# - try to bobtain series of locks with `a` inside the series (`a` can not be obtained for now)
+client.lock_seires('c', 'a', 'b') # ... `a` is still obtained 
+# =>
+{
+  ok: false,
+  result: {
+    error: :failed_to_acquire_lock_series,
+    detailed_errors: { 'a' => { ok: false, result: :retry_limit_reached } },
+    lock_series: ["c", "a", "b"],
+    acquired_locks: ["c"],
+    missing_locks: ["a", "b"],
+    failed_on_lock: ["a"],
+  }
+}
+```
+
+##### New instrumentaiton events and logs:
+
+```ruby
+# NEW instrumentation events (examples)
+"redis_queued_locks.lock_series_obtained" => # {lock_keys: ["rql:lock:s", "rql:lock:t", "rql:lock:u"], ttl: 5000, acq_id: "rql:acq:4486/1696/1704/1712/e6fd0da7991e4303", hst_id: "rql:hst:4486/1696/1712/e6fd0da7991e4303", ts: "2026-01-28 22:05:06 +0300", acq_time: 2.61, instrument: nil}
+"redis_queued_locks.lock_series_hold_and_release" => # {lock_keys: ["rql:lock:x", "rql:lock:y", "rql:lock:z"], hold_time: 0.29, ttl: 5000, acq_id: "rql:acq:4486/1696/1704/1712/e6fd0da7991e4303", hst_id: "rql:hst:4486/1696/1712/e6fd0da7991e4303", ts: 1769627106.4717052, acq_time: 4.26, instrument: nil}
+```
+
+```shell
+# NEW logs (examples)
+[redis_queued_locks.start_lock_series_obtaining] lock_keys => '["rql:lock:a", "rql:lock:b"]'queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued'
+[redis_queued_locks.lock_series_obtained] lock_keys => '["rql:lock:a", "rql:lock:b"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' acq_time => 2.55 (ms)
+[redis_queued_locks.expire_lock_series] lock_keys => '["rql:lock:x", "rql:lock:y", "rql:lock:z"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued'
+```
+
+----
+
+#### #lock_series! - (PoC) exceptional `lock_series`
+
+> (IMPORTANT!) "Proof of Concept" realization. Will be reworked in the future (very-very soon)
+
+For more details see `lock_series` [docs](#lock_series---poc-acquire-a-series-of-locks)
+
+```ruby
+client.lock_series!("x", "y", "z") { ...some_code... }
+```
+
+----
+
 #### #lock_info
 
 <sup>\[[back to top](#usage)\]</sup>
@@ -2328,6 +2444,8 @@ Detalized event semantics and payload structure:
     - `write` - waits - `write`;
     - **write** mode is a default behavior for all RQL locks;
 - **Minor**:
+  - an ability to return all insturmentation metrics from the `lock` invocation (and after block `yield`ing);
+  - 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);
@@ -2358,6 +2476,8 @@ Detalized event semantics and payload structure:
   - **Research**: support for `Valkey` database backend (https://github.com/valkey-io/valkey) (https://valkey.io/);
   - **Research**: support for `Garnet` database backend (https://microsoft.github.io/) (https://github.com/microsoft/garnet);
   - add a library-level exception, when RQL-related key in Redis (required for its logic) has incompatible type (means: some other program uses our key with their own type and logic and RQL can't work properly);
+  - yardoc docs with CI check (full doc coverage check);
+
 ---
 
 ## Build and Develop

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

@@ -17,7 +17,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::WithAcqTimeout
   #   Add additional error data about lock queue and required lock to the timeout error or not.
   # @option on_timeout [Proc,NilClass]
   #   Callback invoked on Timeout::Error.
-  # @param block [Block] Custom logic that should be invoked under the obtained lock.
+  # @yield Custom logic that should be invoked under the obtained lock.
+  # @yieldreturn [Any]
   # @return [Any]
   #
   # @raise [RedisQueuedLocks::LockAcquirementIntermediateTimeoutError]

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 1.7.0
+# @since 1.16.0
 module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire::LogVisitor
   class << self
     # @param logger [::Logger,#debug]

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

@@ -32,7 +32,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   # @param should_decrease [Boolean]
   #   - Should decrease the lock TTL after the lock invocation;
   #   - It is suitable for extendable reentrant locks;
-  # @param block [Block] Custom logic that should be invoked under the obtained lock.
+  # @yield Custom logic that should be invoked under the obtained lock.
+  # @yieldreturn [Any]
   # @return [Any,NilClass] nil is returned when no block parametr is provided.
   #
   # @api private
@@ -122,7 +123,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   private
 
   # @param timeout [Float]
-  # @parma lock_key [String]
+  # @param lock_key [String]
   # @param lock_ttl [Integer,NilClass]
   # @param acquirer_id [String]
   # @param host_id [String]

data/lib/redis_queued_locks/acquirer/acquire_lock.rb

@@ -151,11 +151,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   - marks the method that everything should be instrumneted
     #     despite the enabled instrumentation sampling;
     #   - makes sense when instrumentation sampling is enabled;
-    # @param [Block]
-    #   A block of code that should be executed after the successfully acquired lock.
+    # @yield A block of code that should be executed after the successfully acquired lock.
+    # @yieldreturn [Any]
     # @return [Hash<Symbol,Any>,yield]
     #  - Format: { ok: true/false, result: Any }
-    #  - If block is given the result of block's yeld will be returned.
+    #  - If block is given the result of block's yield will be returned.
     #
     # @api private
     # @since 1.0.0

data/lib/redis_queued_locks/acquirer/lock_series_poc/instr_visitor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# NOTE: Lock Series PoC
+# steep:ignore
+# @api private
+# @since 1.16.1
+module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
+  class << self
+    # NOTE: Lock Series PoC
+    # @api private
+    # @since 1.16.1
+    def lock_series_obtained( # steep:ignore
+      instrumenter,
+      instr_sampled,
+      lock_keys,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_obtained', {
+        lock_keys:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+      }) rescue nil
+    end
+
+    # NOTE: Lock Series PoC
+    # @api private
+    # @since 1.16.1
+    def lock_series_hold_and_release( # steep:ignore
+      instrumenter,
+      instr_sampled,
+      lock_keys,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      hold_time,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_hold_and_release', {
+        lock_keys:, hold_time:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+      }) # rescue nil
+    end
+  end
+end
+# steep:ignore

data/lib/redis_queued_locks/acquirer/lock_series_poc/log_visitor.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# NOTE: Lock Series PoC
+# steep:ignore
+# @api private
+# @since 1.16.1
+module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
+  class << self
+    # NOTE: Lock Series PoC
+    # @api private
+    # @since 1.16.0
+    def start_lock_series_obtaining( # steep:ignore
+      logger,
+      log_sampled,
+      lock_keys,
+      queue_ttl,
+      acquirer_id,
+      host_id,
+      access_strategy
+    )
+      return unless log_sampled
+
+      logger.debug do
+        "[redis_queued_locks.start_lock_series_obtaining] " \
+        "lock_keys => '#{lock_keys.inspect}'" \
+        "queue_ttl => #{queue_ttl} " \
+        "acq_id => '#{acquirer_id}' " \
+        "hst_id => '#{host_id}' " \
+        "acs_strat => '#{access_strategy}'"
+      end # rescue nil
+    end
+
+    # NOTE: Lock Series PoC
+    # @api private
+    # @since 1.16.0
+    def lock_series_obtained( # steep:ignore
+      logger,
+      log_sampled,
+      lock_keys,
+      queue_ttl,
+      acquirer_id,
+      host_id,
+      acq_time,
+      access_strategy
+    )
+      return unless log_sampled
+
+      logger.debug do
+        "[redis_queued_locks.lock_series_obtained] " \
+        "lock_keys => '#{lock_keys.inspect}' " \
+        "queue_ttl => #{queue_ttl} " \
+        "acq_id => '#{acquirer_id}' " \
+        "hst_id => '#{host_id}' " \
+        "acs_strat => '#{access_strategy}' " \
+        "acq_time => #{acq_time} (ms)"
+      end # rescue nil
+    end
+
+    # NOTE: Lock Series PoC
+    # @api private
+    # @since 1.16.0
+    def expire_lock_series( # steep:ignore
+      logger,
+      log_sampled,
+      lock_series,
+      queue_ttl,
+      acquirer_id,
+      host_id,
+      access_strategy
+    )
+      return unless log_sampled
+
+      logger.debug do
+        "[redis_queued_locks.expire_lock_series] " \
+        "lock_keys => '#{lock_series.inspect}' " \
+        "queue_ttl => #{queue_ttl} " \
+        "acq_id => '#{acquirer_id}' " \
+        "hst_id => '#{host_id}' " \
+        "acs_strat => '#{access_strategy}'"
+      end rescue nil
+    end
+  end
+end

data/lib/redis_queued_locks/acquirer/lock_series_poc.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+# NOTE: Lock Series PoC
+# steep:ignore
+# rubocop:disable all
+# @api private
+# @since 1.16.0
+module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
+  require_relative 'lock_series_poc/log_visitor'
+  require_relative 'lock_series_poc/instr_visitor'
+
+  # @sine 1.16.0
+  extend RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
+
+  class << self
+    # @api private
+    # @since 1.16.0
+    # @version 1.16.1
+    def lock_series_poc( # steep:ignore
+      redis,
+      lock_names,
+      detailed_result:,
+      process_id:,
+      thread_id:,
+      fiber_id:,
+      ractor_id:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      timed:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      raise_errors:,
+      instrumenter:,
+      identity:,
+      fail_fast:,
+      meta:,
+      detailed_acq_timeout_error:,
+      instrument:,
+      logger:,
+      log_lock_try:,
+      conflict_strategy:,
+      read_write_mode:,
+      access_strategy:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      log_sample_this:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
+      instr_sample_this:,
+      &block
+    )
+      case meta
+      when Hash, NilClass then nil
+      else
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:meta` argument should be a type of NilClass or Hash, got #{meta.class}."
+        )
+      end
+
+      if meta.is_a?(::Hash) && (meta.any? do |key, _value|
+        key == 'acq_id' ||
+        key == 'hst_id' ||
+        key == 'ts' ||
+        key == 'ini_ttl' ||
+        key == 'lock_key' ||
+        key == 'rem_ttl' ||
+        key == 'spc_ext_ttl' ||
+        key == 'spc_cnt' ||
+        key == 'l_spc_ext_ini_ttl' ||
+        key == 'l_spc_ext_ts' ||
+        key == 'l_spc_ts'
+      end)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          '`:meta` keys can not overlap reserved lock data keys ' \
+          '"acq_id", "hst_id", "ts", "ini_ttl", "lock_key", "rem_ttl", "spc_cnt", ' \
+          '"spc_ext_ttl", "l_spc_ext_ini_ttl", "l_spc_ext_ts", "l_spc_ts"'
+        )
+      end
+
+      locks_count = lock_names.size
+
+      lock_acquirement_operations = lock_names.each_with_index.map do |lock_name, position|
+        lock_ttl =
+          ttl * (locks_count - position) +
+          retry_delay * (locks_count - position) +
+          retry_jitter * (locks_count - position)
+
+        { lock_name: lock_name, ttl: lock_ttl }
+      end
+
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
+
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sample_this,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
+      lock_keys_for_instrumentation = lock_names.map do |lock_name|
+        RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      end
+
+      acquirer_id_for_instrumentation = RedisQueuedLocks::Resource.acquirer_identifier(
+        process_id,
+        thread_id,
+        fiber_id,
+        ractor_id,
+        identity
+      )
+
+      host_id_for_instrumentation = RedisQueuedLocks::Resource.host_identifier(
+        process_id,
+        thread_id,
+        ractor_id,
+        identity
+      )
+
+      RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.start_lock_series_obtaining( # steep:ignore
+        logger, log_sampled, lock_keys_for_instrumentation,
+        queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, access_strategy
+      )
+
+      acq_start_time = RedisQueuedLocks::Utilities.clock_gettime
+      successfully_acquired_locks = [] # steep:ignore
+      failed_locks_and_errors = {} # steep:ignore
+      failed_on_lock = nil
+
+      lock_acquirement_operations.map do |lock_operation_options|
+        result =
+          begin
+            RedisQueuedLocks::Acquirer::AcquireLock.acquire_lock(
+              redis,
+              lock_operation_options[:lock_name],
+              process_id:,
+              thread_id:,
+              fiber_id:,
+              ractor_id:,
+              ttl: lock_operation_options[:ttl],
+              queue_ttl:,
+              timeout:,
+              timed:,
+              retry_count:,
+              retry_delay:,
+              retry_jitter:,
+              raise_errors:,
+              instrumenter:,
+              identity:,
+              fail_fast:,
+              meta:,
+              detailed_acq_timeout_error:,
+              instrument:,
+              logger:,
+              log_lock_try:,
+              conflict_strategy:,
+              read_write_mode:,
+              access_strategy:,
+              log_sampling_enabled:,
+              log_sampling_percent:,
+              log_sampler:,
+              log_sample_this:,
+              instr_sampling_enabled:,
+              instr_sampling_percent:,
+              instr_sampler:,
+              instr_sample_this:
+            )
+          rescue => error
+            if raise_errors && successfully_acquired_locks.any?
+              # NOTE: release all previously acquired locks if any next lock is already locked
+              successfully_acquired_locks.each do |operation_result|
+                lock_key = RedisQueuedLocks::Resource.prepare_lock_key(operation_result[:lock_name])
+                redis.with do |conn|
+                  conn.multi(watch: [lock_key]) do |transact|
+                    transact.call('DEL', lock_key)
+                  end
+                end
+              end
+            end
+            raise(error)
+          end
+
+        if result[:ok]
+          successfully_acquired_locks << {
+            lock_name: lock_operation_options[:lock_name],
+            ok: result[:ok],
+            result: result[:result]
+          }
+        else
+          failed_on_lock = lock_operation_options[:lock_name]
+          failed_locks_and_errors[lock_operation_options[:lock_name]] = result
+          break
+        end
+      end
+
+      if (successfully_acquired_locks.size == lock_names.size && (successfully_acquired_locks.all? { |res| res[:ok] }))
+        acq_end_time = RedisQueuedLocks::Utilities.clock_gettime
+        acq_time = ((acq_end_time - acq_start_time) / 1_000.0).ceil(2)
+        ts = Time.now.to_s
+
+        RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.lock_series_obtained( # steep:ignore
+          logger, log_sampled, lock_keys_for_instrumentation,
+          queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation,
+          acq_time, access_strategy
+        )
+
+        RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor.lock_series_obtained( # steep:ignore
+          instrumenter, instr_sampled, lock_keys_for_instrumentation,
+          ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, ts, acq_time, instrument
+        )
+
+        yield_time = RedisQueuedLocks::Utilities.clock_gettime
+        ttl_shift = (
+          (yield_time - acq_end_time) / 1_000.0 -
+          RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
+        ).ceil(2)
+
+        yield_result = yield_expire( # steep:ignore
+          redis,
+          logger,
+          lock_keys_for_instrumentation.last,
+          acquirer_id_for_instrumentation,
+          host_id_for_instrumentation,
+          access_strategy,
+          timed,
+          ttl_shift,
+          ttl,
+          queue_ttl,
+          meta,
+          log_sampled,
+          instr_sampled,
+          false, # should_expire (expire manually)
+          false, # should_decrease (expire manually)
+          &block
+        )
+
+        is_lock_manually_released = false
+
+        # expire locks manually
+        if block_given?
+          redis.with do |conn|
+            # use transaction in order to exclude any cross-locking during the group expiration
+            conn.multi(watch: lock_keys_for_instrumentation) do |transaction|
+              lock_keys_for_instrumentation.each do |lock_key|
+                transaction.call('EXPIRE', lock_key, '0')
+              end
+            end
+          end
+          is_lock_manually_released = true
+        end
+
+        rel_time = RedisQueuedLocks::Utilities.clock_gettime
+        hold_time = ((rel_time - acq_end_time) / 1_000.0).ceil(2)
+        ts = Time.now.to_f
+
+        RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.expire_lock_series( # steep:ignore
+          logger, log_sampled, lock_keys_for_instrumentation,
+          queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, access_strategy
+        ) if is_lock_manually_released
+
+        RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor.lock_series_hold_and_release( # steep:ignore
+          instrumenter,
+          instr_sampled,
+          lock_keys_for_instrumentation,
+          ttl,
+          acquirer_id_for_instrumentation,
+          host_id_for_instrumentation,
+          ts,
+          acq_time,
+          hold_time,
+          instrument
+        ) if is_lock_manually_released
+
+        if detailed_result
+          {
+            yield_result: yield_result,
+            locks_release_strategy: block_given? ? :immediate_release_after_yield : :redis_key_ttl,
+            locks_released_at: block_given? ? ts : nil,
+            locks_acq_time: acq_time,
+            locks_hold_time: is_lock_manually_released ? hold_time : nil,
+            lock_series: lock_names,
+            rql_lock_series: lock_keys_for_instrumentation
+          }
+        else
+          yield_result
+        end
+      else
+        acquired_locks = successfully_acquired_locks.map { |state| state[:lock_name] }
+        missing_locks = lock_names - acquired_locks
+
+        {
+          ok: false,
+          result: {
+            error: :failed_to_acquire_lock_series,
+            detailed_errors: failed_locks_and_errors,
+            lock_series: lock_names,
+            acquired_locks:,
+            missing_locks:,
+            failed_on_lock:,
+          }
+        }
+      end
+    end
+  end
+end
+# steep:ignore
+# rubocop:enable all

data/lib/redis_queued_locks/acquirer/queues.rb

@@ -42,7 +42,7 @@ module RedisQueuedLocks::Acquirer::Queues
     end
 
     # @param redis_client [RedisClient]
-    # @param lock_queus [Set<String>]
+    # @param lock_queues [Set<String>]
     # @return [Set<Hash<Symbol,Any>>]
     #
     # @api private

data/lib/redis_queued_locks/acquirer/release_all_locks.rb

@@ -18,7 +18,7 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
-    # @param isntrumenter [#notify]
+    # @param instrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param instrument [NilClass,Any]
     #    - Custom instrumentation data wich will be passed to the instrumenter's payload

data/lib/redis_queued_locks/acquirer/release_lock.rb

@@ -18,7 +18,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #   Redis connection client.
     # @param lock_name [String]
     #   The lock name that should be released.
-    # @param isntrumenter [#notify]
+    # @param instrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);

data/lib/redis_queued_locks/acquirer/release_locks_of.rb

@@ -24,7 +24,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
-    # @param isntrumenter [#notify]
+    # @param instrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param instrument [NilClass,Any]
     #    - Custom instrumentation data wich will be passed to the instrumenter's payload

data/lib/redis_queued_locks/acquirer.rb

@@ -4,6 +4,7 @@
 # @since 1.0.0
 module RedisQueuedLocks::Acquirer
   require_relative 'acquirer/acquire_lock'
+  require_relative 'acquirer/lock_series_poc'
   require_relative 'acquirer/release_lock'
   require_relative 'acquirer/release_all_locks'
   require_relative 'acquirer/release_locks_of'

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.14.0
+# @version 1.16.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @return [RedisClient]
@@ -301,11 +301,11 @@ class RedisQueuedLocks::Client
   #   - marks the method that everything should be instrumneted
   #     despite the enabled instrumentation sampling;
   #   - makes sense when instrumentation sampling is enabled;
-  # @param block [Block]
-  #   A block of code that should be executed after the successfully acquired lock.
+  # @yield A block of code that should be executed after the successfully acquired lock.
+  #   @yieldreturn [Any]
   # @return [Hash<Symbol,Any>,yield]
   #   - Format: { ok: true/false, result: Symbol/Hash }.
-  #   - If block is given the result of block's yeld will be returned.
+  #   - If block is given the result of block's yield will be returned.
   #
   # @api public
   # @since 1.0.0
@@ -381,12 +381,156 @@ class RedisQueuedLocks::Client
   end
   # rubocop:enable Metrics/MethodLength
 
+  # NOTE: Lock Series PoC
+  # rubocop:disable all
+  # @api public
+  # @since 1.16.0
+  def lock_series( # steep:ignore
+    *lock_names,
+    detailed_result: false,
+    ttl: config['default_lock_ttl'], # steep:ignore
+    queue_ttl: config['default_queue_ttl'], # steep:ignore
+    timeout: config['try_to_lock_timeout'], # steep:ignore
+    timed: config['is_timed_by_default'], # steep:ignore
+    retry_count: config['retry_count'], # steep:ignore
+    retry_delay: config['retry_delay'], # steep:ignore
+    retry_jitter: config['retry_jitter'], # steep:ignore
+    raise_errors: false,
+    fail_fast: false,
+    conflict_strategy: config['default_conflict_strategy'], # steep:ignore
+    read_write_mode: :write,
+    access_strategy: config['default_access_strategy'], # steep:ignore
+    identity: uniq_identity,
+    meta: nil,
+    detailed_acq_timeout_error: config['detailed_acq_timeout_error'], # steep:ignore
+    logger: config['logger'], # steep:ignore
+    log_lock_try: config['log_lock_try'], # steep:ignore
+    instrumenter: config['instrumenter'], # steep:ignore
+    instrument: nil,
+    log_sampling_enabled: config['log_sampling_enabled'], # steep:ignore
+    log_sampling_percent: config['log_sampling_percent'], # steep:ignore
+    log_sampler: config['log_sampler'], # steep:ignore
+    log_sample_this: false,
+    instr_sampling_enabled: config['instr_sampling_enabled'], # steep:ignore
+    instr_sampling_percent: config['instr_sampling_percent'], # steep:ignore
+    instr_sampler: config['instr_sampler'], # steep:ignore
+    instr_sample_this: false,
+    &block
+  )
+    RedisQueuedLocks::Acquirer::LockSeriesPoC.lock_series_poc( # steep:ignore
+      redis_client,
+      lock_names,
+      detailed_result:,
+      process_id: RedisQueuedLocks::Resource.get_process_id,
+      thread_id: RedisQueuedLocks::Resource.get_thread_id,
+      fiber_id: RedisQueuedLocks::Resource.get_fiber_id,
+      ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      timed:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      raise_errors:,
+      instrumenter:,
+      identity:,
+      fail_fast:,
+      conflict_strategy:,
+      read_write_mode:,
+      access_strategy:,
+      meta:,
+      detailed_acq_timeout_error:,
+      logger:,
+      log_lock_try:,
+      instrument:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      log_sample_this:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
+      instr_sample_this:,
+      &block
+    )
+  end
+  # rubocop:enable all
+
+  # NOTE: Lock Series PoC
+  # rubocop:disable all
+  # @api public
+  # @since 1.16.0
+  def lock_series!( # steep:ignore
+    *lock_names,
+    detailed_result: false,
+    ttl: config['default_lock_ttl'], # steep:ignore
+    queue_ttl: config['default_queue_ttl'], # steep:ignore
+    timeout: config['try_to_lock_timeout'], # steep:ignore
+    timed: config['is_timed_by_default'], # steep:ignore
+    retry_count: config['retry_count'], # steep:ignore
+    retry_delay: config['retry_delay'], # steep:ignore
+    retry_jitter: config['retry_jitter'], # steep:ignore
+    fail_fast: false,
+    conflict_strategy: config['default_conflict_strategy'], # steep:ignore
+    read_write_mode: :write,
+    access_strategy: config['default_access_strategy'], # steep:ignore
+    identity: uniq_identity,
+    meta: nil,
+    detailed_acq_timeout_error: config['detailed_acq_timeout_error'], # steep:ignore
+    logger: config['logger'], # steep:ignore
+    log_lock_try: config['log_lock_try'], # steep:ignore
+    instrumenter: config['instrumenter'], # steep:ignore
+    instrument: nil,
+    log_sampling_enabled: config['log_sampling_enabled'], # steep:ignore
+    log_sampling_percent: config['log_sampling_percent'], # steep:ignore
+    log_sampler: config['log_sampler'], # steep:ignore
+    log_sample_this: false,
+    instr_sampling_enabled: config['instr_sampling_enabled'], # steep:ignore
+    instr_sampling_percent: config['instr_sampling_percent'], # steep:ignore
+    instr_sampler: config['instr_sampler'], # steep:ignore
+    instr_sample_this: false,
+    &block
+  )
+    lock_series( # steep:ignore
+      *lock_names, # steep:ignore
+      detailed_result:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      timed:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      raise_errors: true,
+      fail_fast:,
+      conflict_strategy:,
+      read_write_mode:,
+      access_strategy:,
+      identity:,
+      meta:,
+      detailed_acq_timeout_error:,
+      logger:,
+      log_lock_try:,
+      instrumenter:,
+      instrument:,
+      log_sampling_enabled:,
+      log_sampling_percent:,
+      log_sampler:,
+      log_sample_this:,
+      instr_sampling_enabled:,
+      instr_sampling_percent:,
+      instr_sampler:,
+      instr_sample_this:,
+      &block
+    )
+  end
+
   # @note See #lock method signature.
   #
   # @api public
   # @since 1.0.0
   # @version 1.13.0
-  # rubocop:disable Metrics/MethodLength
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'], # steep:ignore

data/lib/redis_queued_locks/config/dsl.rb

@@ -16,7 +16,7 @@ module RedisQueuedLocks::Config::DSL
     #
     # @api private
     # @since 1.13.0
-    def config_setters()= @config_setters # rubocop:disable Style/DefWithParentheses
+    def config_setters()= @config_setters
 
     # NOTE:
     #   1. Style/DefWithParentheses rubocop's cop incorrectly drops `()` from method definition
@@ -28,7 +28,7 @@ module RedisQueuedLocks::Config::DSL
     #
     # @api private
     # @since 1.13.0
-    def config_validators()= @config_validators # rubocop:disable Style/DefWithParentheses
+    def config_validators()= @config_validators
 
     # @param config_key [String]
     # @param validator [Block]

data/lib/redis_queued_locks/logging/void_logger.rb

@@ -5,7 +5,8 @@
 module RedisQueuedLocks::Logging::VoidLogger
   class << self
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -13,7 +14,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def warn(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -21,7 +23,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def unknown(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -29,7 +32,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def log(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -37,7 +41,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def info(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -45,7 +50,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def error(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -53,7 +59,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     def fatal(progname = nil, &block); end
 
     # @param progname [Any]
-    # @parma block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -63,7 +70,8 @@ module RedisQueuedLocks::Logging::VoidLogger
     # @param severity [Any]
     # @param message [Any]
     # @param progname [Any]
-    # @param block [Block]
+    # @yield
+    # @yieldreturn [Any]
     # @return [void]
     #
     # @api public
@@ -71,7 +79,7 @@ module RedisQueuedLocks::Logging::VoidLogger
     def add(severity = nil, message = nil, progname = nil, &block); end
 
     # @param message [Any]
-    # @retorun [void]
+    # @return [void]
     #
     # @api public
     # @since 1.0.0

data/lib/redis_queued_locks/logging.rb

@@ -75,10 +75,8 @@ module RedisQueuedLocks::Logging
       #     - see https://github.com/reidmorrison/semantic_logger
       #   - convinient/conventional way to support the popular `broadcast` RubyOnRails's logger;
       #     - see https://api.rubyonrails.org/classes/ActiveSupport/BroadcastLogger.html
-      # rubocop:disable Layout/LineLength
       return true if defined?(::SemanticLogger::Logger) && logger.is_a?(::SemanticLogger::Logger)
       return true if defined?(::ActiveSupport::BroadcastLogger) && logger.is_a?(::ActiveSupport::BroadcastLogger)
-      # rubocop:enable Layout/LineLength
 
       # NOTE: should provide `#debug` method.
       return false unless logger.respond_to?(:debug)

data/lib/redis_queued_locks/resource.rb

@@ -152,7 +152,7 @@ module RedisQueuedLocks::Resource
     # @param acquirer_position [Float]
     #   A time (epoch, seconds.milliseconds) that represents
     #   the acquirer position in lock request queue.
-    # @parma queue_ttl [Integer]
+    # @param queue_ttl [Integer]
     #   In second.
     # @return [Boolean]
     #   Is the lock request time limit has reached or not.

data/lib/redis_queued_locks/swarm/flush_zombies.rb

@@ -5,7 +5,7 @@
 class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElement::Isolated
   class << self
     # @param redis_client [RedisClient]
-    # @parma zombie_ttl [Integer]
+    # @param zombie_ttl [Integer]
     # @param lock_scan_size [Integer]
     # @param queue_scan_size [Integer]
     # @return [Hash<Symbol,Boolean|Set<String>]] Format:

data/lib/redis_queued_locks/swarm/swarm_element/isolated.rb

@@ -154,7 +154,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   #
   # @api private
   # @since 1.9.0
-  # rubocop:disable Layout/ClassStructure, Lint/IneffectiveAccessModifier
+  # rubocop:disable Layout/ClassStructure, Lint/IneffectiveAccessModifier, Metrics/MethodLength
   def self.swarm_loop(&main_loop_spawner)
     # NOTE:
     #   This self.-related part of code is placed in the middle of class in order
@@ -177,7 +177,10 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
             # @type var main_loop: Thread
             RedisQueuedLocks::Utilities.thread_state(main_loop)
           end
-        Ractor.yield({ main_loop: { alive: main_loop_alive, state: main_loop_state } })
+        # NOTE: (will be reworked with Ractor::Port in the next RQL release (~1.17))
+        Ractor.yield({ # steep:ignore
+          main_loop: { alive: main_loop_alive, state: main_loop_state }
+        })
       when :is_active
         Ractor.yield(main_loop != nil && main_loop.alive?) # steep:ignore
       when :start
@@ -191,7 +194,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
       end
     end
   end
-  # rubocop:enable Layout/ClassStructure, Lint/IneffectiveAccessModifier
+  # rubocop:enable Layout/ClassStructure, Lint/IneffectiveAccessModifier, Metrics/MethodLength
 
   # @return [Boolean]
   #

data/lib/redis_queued_locks/utilities/lock.rb

@@ -12,7 +12,8 @@ class RedisQueuedLocks::Utilities::Lock
     @lock = ::Monitor.new
   end
 
-  # @param block [Block]
+  # @yield
+  # @yieldreturn [Any]
   # @return [Any]
   #
   # @api private

data/lib/redis_queued_locks/utilities.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.14.0
+# @version 1.16.0
 module RedisQueuedLocks::Utilities
   require_relative 'utilities/lock'
 
@@ -36,7 +36,14 @@ module RedisQueuedLocks::Utilities
   # @since 1.9.0
   RACTOR_STATUS_PATTERN = /\A.*?\s(?<status>\w+)>\z/i
 
-  # @param block [Block]
+  # @return [Boolean]
+  #
+  # @api public
+  # @since ?.?.?
+  RUBY_OVER_4 = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('4.0.0')
+
+  # @yield
+  # @yieldreturn [Any]
   # @return [Any]
   #
   # @api private
@@ -86,7 +93,7 @@ module RedisQueuedLocks::Utilities
   #   - "failed" (thread is terminated with an exception);
   # See Thread#status official documentation.
   #
-  # @param [Thread]
+  # @param thread [Thread]
   # @return [String]
   #
   # @api private
@@ -97,4 +104,12 @@ module RedisQueuedLocks::Utilities
     return 'failed' if status == nil
     status #: String
   end
+
+  # @return [Boolean]
+  #
+  # @api public
+  # @since 1.16.0
+  def ruby_over_4?
+    RUBY_OVER_4
+  end
 end

data/lib/redis_queued_locks/version.rb

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

data/sig/redis_queued_locks/utilities.rbs

@@ -2,11 +2,13 @@ module RedisQueuedLocks
   module Utilities
     RACTOR_LIVENESS_PATTERN: Regexp
     RACTOR_STATUS_PATTERN: Regexp
+    RUBY_OVER_4: bool
 
     def self?.run_non_critical: () { (?) -> untyped } -> untyped?
     def self?.ractor_status: (Ractor ractor) -> String
     def self?.ractor_alive?: (Ractor ractor) -> bool
     def self?.thread_state: (Thread thread) -> String
     def self?.clock_gettime: () -> Integer
+    def self?.ruby_over_4?: () -> bool
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.15.1
+  version: 1.16.1
 platform: ruby
 authors:
 - Rustam Ibragimov
@@ -65,6 +65,9 @@ files:
 - lib/redis_queued_locks/acquirer/is_queued.rb
 - lib/redis_queued_locks/acquirer/keys.rb
 - lib/redis_queued_locks/acquirer/lock_info.rb
+- lib/redis_queued_locks/acquirer/lock_series_poc.rb
+- lib/redis_queued_locks/acquirer/lock_series_poc/instr_visitor.rb
+- lib/redis_queued_locks/acquirer/lock_series_poc/log_visitor.rb
 - lib/redis_queued_locks/acquirer/locks.rb
 - lib/redis_queued_locks/acquirer/queue_info.rb
 - lib/redis_queued_locks/acquirer/queues.rb