redis_queued_locks 1.22.0 → 1.23.1

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

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.22.0
+# @version 1.23.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
@@ -106,7 +106,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
-    # @option read_write_mode [Symbol]
+    # @option rw_mode [Symbol]
     #   - `:write` (default) - exclusive lock: waits for the write lock and for all read locks;
     #   - `:read` - shared lock: waits for the write lock only (read locks do not block each other);
     #   - `:queued` access strategy orders read and write requests in FIFO between modes
@@ -193,7 +193,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.22.0
+    # @version 1.23.1
     def acquire_lock(
       redis,
       lock_name,
@@ -220,7 +220,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
       priority:,
       lock_priorities:,
@@ -245,14 +245,14 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         )
       end
 
-      # Step 0.1 (RW): prevent :read_write_mode incompatabilities
-      case read_write_mode # NOTE: (steep) case/when narrows `Symbol` to `RQL::readWriteMode` below
+      # Step 0.1 (RW): prevent :rw_mode incompatabilities
+      case rw_mode # NOTE: (steep) case/when narrows `Symbol` to `RQL::readWriteMode` below
       when :read, :write then nil
       else
         raise(
           RedisQueuedLocks::ArgumentError,
-          "`:read_write_mode` argument should be `:read` or `:write`, " \
-          "got #{read_write_mode.inspect}."
+          "`:rw_mode` argument should be `:read` or `:write`, " \
+          "got #{rw_mode.inspect}."
         )
       end
 
@@ -383,7 +383,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       # NOTE: (RW) read lock data key is required by read lock requests only (write lock requests
       #   never obtain read locks: read-to-write lock upgrade is not supported);
       read_lock_key =
-        if read_write_mode == :read
+        if rw_mode == :read
           RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
         end
 
@@ -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
@@ -422,7 +423,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           redis,
           logger,
           lock_key,
-          read_write_mode,
+          rw_mode,
           lock_key_queue,
           read_lock_key_queue,
           queue_ttl,
@@ -436,7 +437,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
 
       LogVisitor.start_lock_obtaining(
         logger, log_sampled, lock_key,
-        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
+        queue_ttl, acquirer_id, host_id, access_strategy, rw_mode, priority
       )
 
       # Step 2: try to lock with timeout
@@ -457,7 +458,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
 
           LogVisitor.start_try_to_lock_cycle(
             logger, log_sampled, lock_key,
-            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
+            queue_ttl, acquirer_id, host_id, access_strategy, rw_mode, priority
           )
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
@@ -468,10 +469,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock
 
             LogVisitor.dead_score_reached__reset_acquirer_position(
               logger, log_sampled, lock_key,
-              queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
+              queue_ttl, acquirer_id, host_id, access_strategy, rw_mode, priority
             )
           end
 
+          acq_process[:try_start_time] = clock_gettime
+
           # NOTE: (steep ignorance) pattern matching is not supported in steep
           # steep:ignore:start
           try_to_lock(
@@ -479,7 +482,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             logger,
             log_lock_try,
             lock_key,
-            read_write_mode,
+            rw_mode,
             lock_key_queue,
             read_lock_key_queue,
             lock_readers_key,
@@ -522,11 +525,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # instrumetnation: (reentrant lock with ttl extension)
               LogVisitor.extendable_reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, rw_mode,
                 priority
               )
               InstrVisitor.extendable_reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -534,11 +537,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # instrumetnation: (reentrant lock without ttl extension)
               LogVisitor.reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, rw_mode,
                 priority
               )
               InstrVisitor.reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -547,11 +550,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # NOTE: classic is: acq_process[:result][:process] == :lock_obtaining
               LogVisitor.lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, rw_mode,
                 priority
               )
               InstrVisitor.lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -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)
 
@@ -708,7 +717,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instrumenter,
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
-                read_write_mode,
+                rw_mode,
                 priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
@@ -724,7 +733,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instrumenter,
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
-                read_write_mode,
+                rw_mode,
                 priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
@@ -755,10 +764,10 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         acq_time = ((clock_gettime - acq_start_time) / 1_000.0).ceil(2)
         LogVisitor.lock_obtaining_failed(
           logger, log_sampled, lock_key, queue_ttl, acquirer_id, host_id,
-          acq_time, access_strategy, read_write_mode, priority, acq_process[:result]
+          acq_time, access_strategy, rw_mode, priority, acq_process[:result]
         )
         InstrVisitor.lock_obtaining_failed(
-          instrumenter, instr_sampled, lock_key, read_write_mode, priority, lock_ttl, acquirer_id,
+          instrumenter, instr_sampled, lock_key, rw_mode, priority, lock_ttl, acquirer_id,
           host_id, Time.now.to_f, acq_time, acq_process[:result], instrument
         )
         { ok: false, result: acq_process[:result] } #: { ok: bool, result: Symbol }
@@ -780,10 +789,10 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         acq_time = ((clock_gettime - acq_start_time) / 1_000.0).ceil(2)
         LogVisitor.lock_obtaining_failed(
           logger, log_sampled, lock_key, queue_ttl, acquirer_id, host_id,
-          acq_time, access_strategy, read_write_mode, priority, acq_process[:result]
+          acq_time, access_strategy, rw_mode, priority, acq_process[:result]
         )
         InstrVisitor.lock_obtaining_failed(
-          instrumenter, instr_sampled, lock_key, read_write_mode, priority, lock_ttl, acquirer_id,
+          instrumenter, instr_sampled, lock_key, rw_mode, priority, lock_ttl, acquirer_id,
           host_id, Time.now.to_f, acq_time, acq_process[:result], instrument
         )
       end

data/lib/redis_queued_locks/acquirer/extend_lock_ttl.rb

@@ -26,7 +26,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     # @param lock_name [String]
     # @param milliseconds [Integer]
     #   How many milliseconds should be added: a positive Integer.
-    # @param read_write_mode [Symbol]
+    # @param rw_mode [Symbol]
     #   - `:write` - extends the write lock (of any acquirer);
     #   - `:read` - extends the read lock of the given acquirer (other read locks are not affected)
     #     or all live read locks of the lock (see `all_read_locks`);
@@ -52,13 +52,13 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     #
     # @api private
     # @since 1.0.0
-    # @version 1.21.0
+    # @version 1.23.0
     # rubocop:disable Metrics/MethodLength
     def extend_lock_ttl(
       redis_client,
       lock_name,
       milliseconds,
-      read_write_mode,
+      rw_mode,
       all_read_locks,
       acquirer_id,
       lock_index_enabled,
@@ -74,13 +74,13 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
       instr_sampler,
       instr_sample_this
     )
-      case read_write_mode # NOTE: (steep) case/when narrows `Symbol` to `RQL::readWriteMode` below
+      case rw_mode # NOTE: (steep) case/when narrows `Symbol` to `RQL::readWriteMode` below
       when :read, :write then nil
       else
         raise(
           RedisQueuedLocks::ArgumentError,
-          "`:read_write_mode` argument should be `:read` or `:write`, " \
-          "got #{read_write_mode.inspect}."
+          "`:rw_mode` argument should be `:read` or `:write`, " \
+          "got #{rw_mode.inspect}."
         )
       end
 
@@ -92,7 +92,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
         )
       end
 
-      if read_write_mode == :read && all_read_locks != true && all_read_locks != false
+      if rw_mode == :read && all_read_locks != true && all_read_locks != false
         raise(
           RedisQueuedLocks::ArgumentError,
           "`:all_read_locks` argument should be a boolean, got #{all_read_locks.inspect}."
@@ -103,7 +103,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
 
       ext_start_time = clock_gettime
       result = fully_extend_lock_ttl(
-        redis_client, lock_name, lock_key, milliseconds, read_write_mode, all_read_locks,
+        redis_client, lock_name, lock_key, milliseconds, rw_mode, all_read_locks,
         acquirer_id, lock_index_enabled
       )
       time_at = Time.now.to_f
@@ -129,7 +129,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
         logger.debug do
           "[redis_queued_locks.extend_lock_ttl] " \
           "lock_key => '#{lock_key}' " \
-          "rw_mode => '#{read_write_mode}' " \
+          "rw_mode => '#{rw_mode}' " \
           "all_read_locks => #{all_read_locks} " \
           "ext_ttl => #{milliseconds} " \
           "extended_locks_count => #{extended_locks_count} " \
@@ -141,7 +141,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
       run_non_critical do
         instrumenter.notify('redis_queued_locks.extend_lock_ttl', {
           lock_key: lock_key,
-          rw_mode: read_write_mode,
+          rw_mode:,
           all_read_locks: all_read_locks,
           ext_ttl: milliseconds,
           extended_locks_count: extended_locks_count,
@@ -163,7 +163,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     # @param lock_name [String]
     # @param lock_key [String]
     # @param milliseconds [Integer]
-    # @param read_write_mode [Symbol]
+    # @param rw_mode [Symbol]
     # @param all_read_locks [Boolean]
     # @param acquirer_id [String]
     # @param lock_index_enabled [Boolean]
@@ -177,12 +177,12 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
       lock_name,
       lock_key,
       milliseconds,
-      read_write_mode,
+      rw_mode,
       all_read_locks,
       acquirer_id,
       lock_index_enabled
     )
-      if read_write_mode == :read
+      if rw_mode == :read
         # NOTE: (RW) all live read locks of the lock
         if all_read_locks
           return extend_all_read_locks_ttl(

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

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.23.0
+# rubocop:disable Metrics/ModuleLength
+module RedisQueuedLocks::Acquirer::LockSeries::InstrVisitor
+  # rubocop:disable Metrics/ClassLength
+  class << self
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_key [String] The lock of the series.
+    # @param lock_keys [Array<String>] All locks of the series.
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_intermediate_lock_obtained(
+      instrumenter,
+      instr_sampled,
+      lock_key,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_intermediate_lock_obtained', {
+        lock_key:, lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:,
+        instrument:
+      }) rescue nil
+    end
+
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_key [String] The lock of the series.
+    # @param lock_keys [Array<String>] All locks of the series.
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_lock_obtained(
+      instrumenter,
+      instr_sampled,
+      lock_key,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_lock_obtained', {
+        lock_key:, lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:,
+        instrument:
+      }) rescue nil
+    end
+
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_key [String] The lock that blocks the series.
+    # @param lock_keys [Array<String>] All locks of the series.
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param result [Symbol] The failure result (`:timeout_reached`, `:retry_limit_reached`, ...).
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_lock_obtaining_failed(
+      instrumenter,
+      instr_sampled,
+      lock_key,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      result,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_lock_obtaining_failed', {
+        lock_key:, lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, result:,
+        instrument:
+      }) rescue nil
+    end
+
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_keys [Array<String>]
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param reentrant_lock_keys [Array<String>]
+    #   The locks of the series that are obtained by the outer logic of the current acquirer.
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_obtained(
+      instrumenter,
+      instr_sampled,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      reentrant_lock_keys,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_obtained', {
+        lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:,
+        reentrant_lock_keys:, instrument:
+      }) rescue nil
+    end
+
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_keys [Array<String>]
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param hold_time [Numeric]
+    # @param reentrant_lock_keys [Array<String>]
+    #   The locks of the series that are obtained by the outer logic of the current acquirer.
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_hold_and_release(
+      instrumenter,
+      instr_sampled,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      hold_time,
+      reentrant_lock_keys,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_hold_and_release', {
+        lock_keys:, rw_mode:, priority:, hold_time:, ttl:, acq_id:, hst_id:, ts:, acq_time:,
+        reentrant_lock_keys:, instrument:
+      }) rescue nil
+    end
+
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_keys [Array<String>]
+    # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param result [Symbol] The failure result (`:timeout_reached`, `:retry_limit_reached`, ...).
+    # @param failed_lock_key [String,NilClass]
+    #   The lock of the series that blocks the series (`nil`: unknown, an attempt was not finished
+    #   or some lock state was changed during the attempt).
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.23.0
+    def lock_series_obtaining_failed(
+      instrumenter,
+      instr_sampled,
+      lock_keys,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      result,
+      failed_lock_key,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_series_obtaining_failed', {
+        lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, result:,
+        failed_lock_key:, instrument:
+      }) rescue nil
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end
+# rubocop:enable Metrics/ModuleLength