redis_queued_locks 1.19.0 → 1.21.0

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

@@ -6,7 +6,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::WithAcqTimeout
   # @param redis [RedisClient]
   #   Redis connection manager required for additional data extraction for error message.
   # @param timeout [NilClass,Integer]
-  #   Time period after which the logic will fail with timeout error.
+  #   Time period after which the logic will fail with timeout error (`nil` and `0`: no timeout).
   # @param lock_key [String]
   #   Lock name in RQL notation (rql:lock:some-lock-name).
   # @param lock_name [String]
@@ -26,7 +26,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::WithAcqTimeout
   #
   # @api private
   # @since 1.0.0
-  # @version 1.11.0
+  # @version 1.21.0
   def with_acq_timeout(
     redis,
     timeout,

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

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.16.0
+# @version 1.18.0
 module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire::LogVisitor
   class << self
     # @param logger [::Logger,#debug]

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

@@ -19,7 +19,9 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   # @param logger [::Logger,#debug] Logger object.
   # @param lock_key [String] Obtained lock key that should be expired.
   # @param lock_readers_key [String] Registry of read lock holders.
-  # @param read_lock_key [String] Read lock data of the current acquirer.
+  # @param read_lock_key [String,NilClass]
+  #   Read lock data of the current acquirer (`nil` for write lock requests: they never obtain
+  #   read locks).
   # @param rw_mode [Symbol]
   #   - The mode of the obtained lock (`:read` or `:write`);
   #   - `:read` => only the read lock of the current acquirer is released/decreased;
@@ -28,7 +30,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   # @param access_strategy [Symbol] Lock obtaining strategy.
   # @param timed [Boolean] Should the lock be wrapped by Timeout with with lock's ttl
   # @param ttl_shift [Numeric] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
-  # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
+  # @param ttl [Integer] Lock's time to live (in ms). A positive Integer.
   # @param queue_ttl [Integer] Lock request lifetime.
   # @param meta [NilClass,Hash<String|Symbol,Any>] Custom metadata wich is passed to the lock data;
   # @param log_sampled [Boolean] Should the logic be logged or not.
@@ -43,7 +45,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.18.0
+  # @version 1.21.0
   # rubocop:disable Metrics/MethodLength
   def yield_expire(
     redis,
@@ -69,7 +71,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
     initial_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
 
     if block_given?
-      if timed && ttl != nil
+      if timed
         # NOTE:
         #   - steep is ignored cuz steep can not recognize `::Integer - ::Integer|::Float`
         #     operation here for some mystical reason (it tryes to find overloadd `-` method for
@@ -148,7 +150,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
 
   # @param timeout [Float]
   # @param lock_key [String]
-  # @param lock_ttl [Integer,NilClass]
+  # @param lock_ttl [Integer]
   # @param acquirer_id [String]
   # @param host_id [String]
   # @param meta [NilClass,Hash<Symbol|String,Any>]
@@ -159,7 +161,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.12.0
+  # @version 1.21.0
   def yield_with_timeout(timeout, lock_key, lock_ttl, acquirer_id, host_id, meta, &block)
     ::Timeout.timeout(timeout, RedisQueuedLocks::TimedLockIntermediateTimeoutError, &block)
   rescue RedisQueuedLocks::TimedLockIntermediateTimeoutError

data/lib/redis_queued_locks/acquirer/acquire_lock.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.20.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
@@ -42,12 +42,23 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   A current fiber that want to acquire a lock.
     # @option ractor_id [Integer,String]
     #   The current ractor that want to acquire a lock.
-    # @option ttl [Integer,NilClass]
-    #   Lock's time to live (in milliseconds). Nil means "without timeout".
+    # @option ttl [Integer]
+    #   Lock's time to live (in milliseconds). A positive Integer (both modes).
     # @option queue_ttl [Integer]
     #   Lifetime of the acuier's lock request. In seconds.
+    # @option lock_index_enabled [Boolean]
+    #   - Maintain the lock index (`rql:index:locks`): the lock request and the obtained lock are
+    #     indexed, the lock request queue gets TTL, expired lock names are dropped from the index;
+    #   - `config['lock_index_enabled']` (the client-wide mode, not a per-call option);
+    # @option lock_index_grace_period [Integer]
+    #   - The lock index score margin over the lock key lifetime (in milliseconds): the lock name
+    #     stays in the lock index for this period after the expiration of the lock keys;
+    #   - tolerance of the client clock skew (between hosts) and of the network latency;
+    #   - pre-configured in `config['lock_index_grace_period']`;
+    #   - used only with the enabled lock index (`lock_index_enabled`);
     # @option timeout [Integer,NilClass]
-    #   Time period whe should try to acquire the lock (in seconds).
+    #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout"
+    #   (`0` is the same as `nil`: `Timeout.timeout(0)` sets no timeout).
     # @option timed [Boolean]
     #   Limit the invocation time period of the passed block of code by the lock's TTL.
     # @option retry_count [Integer,NilClass]
@@ -121,7 +132,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   - works in tandem with <config['log_sampling_percent'] and <config['log_sampler']>;
     # @option log_sampling_percent [Integer]
     #   - the percent of cases that should be logged;
-    #   - take an effect when <config['log_sampling_enalbed']> is true;
+    #   - take an effect when <config['log_sampling_enabled']> is true;
     #   - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
     # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     #   - percent-based log sampler that decides should be RQL case logged or not;
@@ -142,7 +153,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
     # @option instr_sampling_percent [Integer]
     #   - the percent of cases that should be instrumented;
-    #   - take an effect when <config['instr_sampling_enalbed']> is true;
+    #   - take an effect when <config['instr_sampling_enabled']> is true;
     #   - works in tandem with <config['instr_sampling_enabled']>
     #     and <config['instr_sampler']> configs;
     # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
@@ -166,7 +177,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.21.0
     def acquire_lock(
       redis,
       lock_name,
@@ -176,6 +187,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       ractor_id:,
       ttl:,
       queue_ttl:,
+      lock_index_enabled:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -223,29 +236,79 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         )
       end
 
-      # Step 0.1 (RW): prevent read lock incompatabilities
-      #   - read lock expiration time is calculated from the lock ttl;
-      if read_write_mode == :read && (!ttl.is_a?(::Integer) || ttl <= 0)
+      # Step 0.1: prevent :ttl incompatibilities (both modes)
+      #   - write lock: `PEXPIRE` with a non-positive ttl deletes the just obtained lock key in the
+      #     obtaining transaction (the lock is "obtained" without the mutual exclusion);
+      #   - read lock: the read lock expiration time is calculated from the lock ttl;
+      if !ttl.is_a?(::Integer) || ttl <= 0
         raise(
           RedisQueuedLocks::ArgumentError,
-          "`:ttl` argument should be a positive Integer for read locks, got #{ttl.inspect}."
+          "`:ttl` argument should be a positive Integer, got #{ttl.inspect}."
+        )
+      end
+
+      # Step 0.1: prevent :queue_ttl, :timeout, :retry_* and :lock_index_grace_period
+      #   incompatibilities (the same ranges as their config keys):
+      #   - a non-positive queue ttl drops the own lock request in the queueing pipeline (the lock
+      #     request is always dead);
+      #   - a negative timeout/retry delay/retry jitter fails `Timeout.timeout`/`sleep` in the
+      #     middle of the acquirement (`0` timeout is the same as `nil`: no timeout);
+      if !queue_ttl.is_a?(::Integer) || queue_ttl <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:queue_ttl` argument should be a positive Integer, got #{queue_ttl.inspect}."
+        )
+      end
+      if timeout != nil && (!timeout.is_a?(::Integer) || timeout < 0)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:timeout` argument should be nil or a non-negative Integer, got #{timeout.inspect}."
+        )
+      end
+      if retry_count != nil && (!retry_count.is_a?(::Integer) || retry_count < 0)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_count` argument should be nil or a non-negative Integer, " \
+          "got #{retry_count.inspect}."
+        )
+      end
+      if !retry_delay.is_a?(::Integer) || retry_delay < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_delay` argument should be a non-negative Integer, got #{retry_delay.inspect}."
+        )
+      end
+      if !retry_jitter.is_a?(::Integer) || retry_jitter < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_jitter` argument should be a non-negative Integer, got #{retry_jitter.inspect}."
+        )
+      end
+      if !lock_index_grace_period.is_a?(::Integer) || lock_index_grace_period < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:lock_index_grace_period` argument should be a non-negative Integer, " \
+          "got #{lock_index_grace_period.inspect}."
         )
       end
 
       # Step 0.2: prevent :meta incompatabiltiies (structure)
+      #   - Symbol keys are written to the lock data as Strings (`Symbol#name`, as redis-client
+      #     does it) and would overwrite the reserved lock data fields too;
       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' ||
-        key == 'rw_mode'
+        meta_key = key.is_a?(::Symbol) ? key.name : key
+        meta_key == 'acq_id' ||
+        meta_key == 'hst_id' ||
+        meta_key == 'ts' ||
+        meta_key == 'ini_ttl' ||
+        meta_key == 'lock_key' ||
+        meta_key == 'rem_ttl' ||
+        meta_key == 'spc_ext_ttl' ||
+        meta_key == 'spc_cnt' ||
+        meta_key == 'l_spc_ext_ini_ttl' ||
+        meta_key == 'l_spc_ext_ts' ||
+        meta_key == 'l_spc_ts' ||
+        meta_key == 'rw_mode'
       end)
         raise(
           RedisQueuedLocks::ArgumentError,
@@ -276,7 +339,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       # NOTE: (RW) write lock requests use the classic lock queue (lock_key_queue)
       read_lock_key_queue = RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
       lock_readers_key = RedisQueuedLocks::Resource.prepare_lock_readers(lock_name)
-      read_lock_key = RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+      # 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
+          RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+        end
 
       acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position
 
@@ -329,6 +397,9 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       )
 
       # Step 2: try to lock with timeout
+      # NOTE: the acquirement start time is defined out of the timeout block: the failed
+      #   acquirement reports the acquirement time too (Steps 3.b and 3.c);
+      acq_start_time = clock_gettime
       with_acq_timeout(
         redis,
         timeout,
@@ -338,8 +409,6 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         detailed_acq_timeout_error,
         on_timeout: acq_dequeue
       ) do
-        acq_start_time = clock_gettime
-
         # Step 2.1: cyclically try to obtain the lock
         while acq_process[:should_try]
 
@@ -371,15 +440,19 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             read_lock_key_queue,
             lock_readers_key,
             read_lock_key,
+            lock_name,
             acquirer_id,
             host_id,
             acquirer_position,
             lock_ttl,
             queue_ttl,
+            lock_index_enabled,
+            lock_index_grace_period,
             fail_fast,
             conflict_strategy,
             access_strategy,
             meta,
+            acq_process[:tries] > 0, # NOTE: retry attempt (see "pre-check" in `try_to_lock`)
             log_sampled,
             instr_sampled
           ) => { ok:, result: }
@@ -629,8 +702,43 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           acq_process[:result] = :timeout_reached
         end
         # Step 3.b: lock is not acquired (acquirer is dequeued by timeout callback)
+        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, acq_process[:result]
+        )
+        InstrVisitor.lock_obtaining_failed(
+          instrumenter, instr_sampled, lock_key, read_write_mode, 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 }
       end
+    rescue RedisQueuedLocks::LockAlreadyObtainedError,
+           RedisQueuedLocks::ConflictLockObtainError,
+           RedisQueuedLocks::LockAcquirementRetryLimitError,
+           RedisQueuedLocks::LockAcquirementTimeoutError => error
+      # Step 3.c: (raise_errors) the failed acquirement is reported before the error is raised
+      #   (like Step 3.b); errors of the block of code under the obtained lock are not reported;
+      # NOTE: (steep) the locals of the method body are nilable in the method-level `rescue` for
+      #   Steep, but these errors are raised by the acquirement only (after Step 1: the locals
+      #   are assigned);
+      # steep:ignore:start
+      unless acq_process[:acquired]
+        if error.is_a?(RedisQueuedLocks::LockAcquirementTimeoutError)
+          acq_process[:result] = :timeout_reached
+        end
+        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, acq_process[:result]
+        )
+        InstrVisitor.lock_obtaining_failed(
+          instrumenter, instr_sampled, lock_key, read_write_mode, lock_ttl, acquirer_id, host_id,
+          Time.now.to_f, acq_time, acq_process[:result], instrument
+        )
+      end
+      # steep:ignore:end
+      raise
     end
   end
 end

data/lib/redis_queued_locks/acquirer/clear_dead_requests.rb

@@ -2,11 +2,32 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.21.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::ClearDeadRequests
+  # @since 1.21.0
+  extend RedisQueuedLocks::Utilities
+
+  # rubocop:disable Metrics/ClassLength
   class << self
+    # Drops dead lock requests (requests older than `dead_ttl`) from the lock queues (write and
+    # read):
+    #   - the disabled lock index: the lock queues found in one SCAN pass, one round trip per batch
+    #     of `scan_size` lock queues (batches are collected across SCAN pages);
+    #   - the enabled lock index: the lock queues of the locks of the lock index: one ZSCAN pass
+    #     over the lock names (the keyspace is never scanned), one round trip per batch of
+    #     `scan_size` lock names (both lock queues of each lock name); expired lock names are
+    #     dropped from the lock index first;
+    #   - the operation is reported with one log and one instrumentation event
+    #     (`redis_queued_locks.clear_dead_requests`) with the time of the whole operation;
+    #
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
+    #   SCAN count and the number of lock queues in one batch (the disabled lock index) or ZSCAN
+    #   count and the number of lock names in one batch (the enabled lock index).
     # @param dead_ttl [Integer] In milliseconds
+    # @param lock_index_enabled [Boolean]
+    #   Find lock queues via the lock index instead of the keyspace SCAN.
     # @param logger [::Logger,#debug]
     # @param instrumenter [#notify]
     # @param instrument [NilClass,Any]
@@ -22,11 +43,13 @@ module RedisQueuedLocks::Acquirer::ClearDeadRequests
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.21.0
+    # rubocop:disable Metrics/MethodLength
     def clear_dead_requests(
       redis_client,
       scan_size,
       dead_ttl,
+      lock_index_enabled,
       logger,
       instrumenter,
       instrument,
@@ -39,48 +62,230 @@ module RedisQueuedLocks::Acquirer::ClearDeadRequests
       instr_sampler,
       instr_sample_this
     )
+      # NOTE: (arguments) the same ranges as the config keys: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching, a non-positive dead ttl drops all lock requests;
+      if !scan_size.is_a?(::Integer) || scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:scan_size` argument should be a positive Integer, got #{scan_size.inspect}."
+        )
+      end
+      if !dead_ttl.is_a?(::Integer) || dead_ttl <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:dead_ttl` argument should be a positive Integer, got #{dead_ttl.inspect}."
+        )
+      end
+
+      rel_start_time = clock_gettime
+      processed_queues = fully_clear_dead_requests(
+        redis_client, scan_size, dead_ttl, lock_index_enabled
+      )
+      time_at = Time.now.to_f
+      rel_end_time = clock_gettime
+      rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)
+
+      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
+      )
+
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.clear_dead_requests] " \
+          "dead_ttl => #{dead_ttl} " \
+          "prc_queue_cnt => #{processed_queues.size} " \
+          "rel_time => #{rel_time} " \
+          "at => #{time_at}"
+        end
+      end if log_sampled
+
+      run_non_critical do
+        instrumenter.notify('redis_queued_locks.clear_dead_requests', {
+          dead_ttl: dead_ttl,
+          prc_queue_cnt: processed_queues.size,
+          rel_time: rel_time,
+          at: time_at,
+          instrument: instrument
+        })
+      end if instr_sampled
+
+      { ok: true, result: { processed_queues: } }
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+    # Drops dead lock requests from the lock queues (see `clear_dead_requests`).
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @param dead_ttl [Integer] In milliseconds
+    # @param lock_index_enabled [Boolean]
+    # @return [Set<String>] The processed lock queues (write and read lock request queues).
+    #
+    # @api private
+    # @since 1.21.0
+    def fully_clear_dead_requests(redis_client, scan_size, dead_ttl, lock_index_enabled)
       dead_score = RedisQueuedLocks::Resource.acquirer_dead_score(dead_ttl / 1_000.0)
 
-      # @type var result: Set[String]
-      result = Set.new.tap do |processed_queues|
+      Set.new.tap do |processed_queues|
         # @type var processed_queues: Set[String]
         redis_client.with do |rconn|
-          each_lock_queue(rconn, scan_size) do |lock_queue|
-            rconn.call('ZREMRANGEBYSCORE', lock_queue, '-inf', dead_score)
-            processed_queues << lock_queue
+          if lock_index_enabled
+            # Step 1 (lock index): drop the expired lock names from the lock index
+            #   (all their keys are expired);
+            rconn.call(
+              'ZREMRANGEBYSCORE', RedisQueuedLocks::Resource::LOCK_INDEX_KEY,
+              '-inf', RedisQueuedLocks::Resource.lock_index_time - 1
+            )
+
+            # Step 2 (lock index): drop dead requests from the lock queues of the lock index
+            each_lock_name_batch(rconn, scan_size) do |lock_names|
+              drop_dead_requests_of_locks(rconn, lock_names, dead_score, processed_queues)
+            end
+          else
+            # Step 1 (keyspace): drop dead requests from the lock queues found in one SCAN pass
+            # NOTE: dead requests are dropped with one pipeline per batch of `scan_size` queues
+            #   (batches are collected across SCAN pages: lock queues can be rare among other keys);
+            # @type var lock_queues: Array[String]
+            lock_queues = []
+
+            each_lock_queue(rconn, scan_size) do |lock_queue|
+              processed_queues << lock_queue
+              lock_queues << lock_queue
+              next if lock_queues.size < scan_size
+
+              drop_dead_requests(rconn, lock_queues, dead_score)
+              lock_queues.clear
+            end
+
+            drop_dead_requests(rconn, lock_queues, dead_score) unless lock_queues.empty?
           end
         end
       end
-
-      { ok: true, result: { processed_queues: result } }
     end
 
-    private
-
+    # Write and read lock queues in one SCAN pass (the disabled lock index).
+    #
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
     # @yield [lock_queue]
     # @yieldparam lock_queue [String]
     # @yieldreturn [void]
-    # @return [Enumerator]
+    # @return [void]
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
-    def each_lock_queue(redis_client, scan_size, &block)
-      redis_client.scan(
-        'MATCH',
-        RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
-        count: scan_size,
-        &block
-      )
-      # NOTE: (RW) read lock queues
+    # @version 1.20.0
+    def each_lock_queue(redis_client, scan_size)
       redis_client.scan(
         'MATCH',
-        RedisQueuedLocks::Resource::READ_LOCK_QUEUE_PATTERN,
-        count: scan_size,
-        &block
-      )
+        RedisQueuedLocks::Resource::ALL_LOCK_QUEUES_PATTERN,
+        count: scan_size
+      ) do |key|
+        # NOTE: the pattern matches other keys too (lock names with `queue:`): lock queues only
+        family = RedisQueuedLocks::Resource.lock_key_family(key)
+        yield(key) if family == :lock_queue || family == :read_lock_queue
+      end
+    end
+
+    # Drops dead requests of the given lock queues in one round trip (the disabled lock index).
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_queues [Array<String>]
+    # @param dead_score [Float]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.20.0
+    def drop_dead_requests(redis_client, lock_queues, dead_score)
+      redis_client.pipelined do |pipeline|
+        lock_queues.each do |lock_queue|
+          pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', dead_score)
+        end
+      end
+    end
+
+    # Drops dead requests of both lock queues of the given lock names in one round trip
+    # (the enabled lock index).
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_names [Array<String>]
+    # @param dead_score [Float]
+    # @param processed_queues [Set<String>] Collects the existing (processed) lock queues.
+    # @return [void]
+    #
+    # @api private
+    # @since 1.20.0
+    def drop_dead_requests_of_locks(redis_client, lock_names, dead_score, processed_queues)
+      # NOTE: (pipeline layout) two replies per lock queue (two lock queues per lock name) in
+      #   the batch order: EXISTS (the queue is processed when it exists), ZREMRANGEBYSCORE;
+      # @type var replies: Array[Integer]
+      replies = redis_client.pipelined do |pipeline|
+        lock_names.each do |lock_name|
+          lock_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+          read_lock_queue = RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
+          pipeline.call('EXISTS', lock_queue)
+          pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', dead_score)
+          pipeline.call('EXISTS', read_lock_queue)
+          pipeline.call('ZREMRANGEBYSCORE', read_lock_queue, '-inf', dead_score)
+        end
+      end
+
+      lock_names.each_with_index do |lock_name, index|
+        if replies[index * 4] == 1
+          processed_queues << RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+        end
+        if replies[(index * 4) + 2] == 1
+          processed_queues << RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
+        end
+      end
+    end
+
+    # Iterates over the lock names of the lock index (one ZSCAN pass) in batches of `scan_size`
+    # lock names (batches are collected across ZSCAN pages). Expired lock names (not dropped from
+    # the index yet) are skipped: all their keys are expired.
+    #
+    # NOTE: each operation module iterates over the lock index by itself (duplicated on purpose:
+    #   operation modules are independent of each other, see `Locks.each_lock_name_batch`);
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer] ZSCAN count and the number of lock names in one batch.
+    # @yield [lock_names]
+    # @yieldparam lock_names [Array<String>] The batch of lock names (reused between batches).
+    # @return [void]
+    #
+    # @api private
+    # @since 1.20.0
+    def each_lock_name_batch(redis_client, scan_size)
+      lock_index_time = RedisQueuedLocks::Resource.lock_index_time
+      # @type var lock_names: Array[String]
+      lock_names = []
+
+      redis_client.zscan(
+        RedisQueuedLocks::Resource::LOCK_INDEX_KEY, count: scan_size
+      ) do |lock_name, lock_index_score|
+        next if lock_index_score.to_f < lock_index_time
+
+        lock_names << lock_name
+        next if lock_names.size < scan_size
+
+        yield(lock_names)
+        lock_names.clear
+      end
+
+      yield(lock_names) unless lock_names.empty?
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ModuleLength