redis_queued_locks 1.20.0 → 1.22.0

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

@@ -19,8 +19,9 @@
 #     - write lock request should be the first in the write lock queue (the classic lock queue)
 #       and should wait for all earlier read lock requests;
 #     - read lock request should wait for all earlier write lock requests;
-#   - `:random` access strategy ignores both queues (no ordering between modes, so
-#     a continuous flow of readers can starve writers);
+#   - `:random` access strategy ignores the order of both queues (no ordering between modes, so
+#     a continuous flow of readers can starve writers); its own lock request is queued like any
+#     lock request (`:queued` lock requests wait for it);
 #
 # Lock index (`RedisQueuedLocks::Resource::LOCK_INDEX_KEY`): only with the enabled lock index
 # (`lock_index_enabled`, `config['lock_index_enabled']`); with the disabled lock index (default)
@@ -37,9 +38,21 @@
 #   - each queueing drops the expired lock names from the index (`ZREMRANGEBYSCORE`): the index
 #     is maintained by the lock acquirement itself (no background jobs);
 #
+# Lock request priorities (`priority`, see `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`):
+#   - the position of the lock request (the score) is the enqueue time shifted by the priority
+#     band: requests of a higher priority are ahead of the requests of a lower priority in both
+#     queues (FIFO inside the same priority), so the queue heads and the order between modes
+#     (`find_opposite_request_ahead`) work with the positions as is;
+#   - dead lock requests are dropped per priority band (each band has its own time barrier):
+#     the band of the current request before the request is queued and the queue heads are read
+#     (both queues); a dead request of another band is dropped when it blocks the current request
+#     (the queue head or the earlier request of the opposite mode): its band and its enqueue time
+#     are decoded from its position, so the cost of an attempt does not depend on the number of
+#     priorities (see `drop_dead_requests_ahead`);
+#
 # @api private
 # @since 1.0.0
-# @version 1.20.0
+# @version 1.22.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   require_relative 'try_to_lock/log_visitor'
@@ -101,8 +114,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @since 1.20.0
   LOCK_STATE_QUEUE_REPLIES_AT = 3
 
-  # Position of the first request of the request queue (`ZRANGE`) in the replies of the lock
-  # request queueing commands (`queue_lock_request`), relative to their first reply.
+  # Position of the first request of the request queue (`ZRANGE WITHSCORES`) in the replies of
+  # the lock request queueing commands (`queue_lock_request`), relative to their first reply.
   #
   # @return [Integer]
   #
@@ -120,6 +133,17 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @since 1.20.0
   OPPOSITE_QUEUE_HEAD_REPLY = 4
 
+  # The maximum number of the round trips of one call of `drop_dead_requests_ahead` (the attempt or
+  # its pre-check; each round trip drops the dead blocking requests, the head of the write lock
+  # queue and the earlier request of the opposite mode, with the dead requests of their priority
+  # bands): the attempt fails when more dead lock requests block it (the next attempts drop them).
+  #
+  # @return [Integer]
+  #
+  # @api private
+  # @since 1.22.0
+  MAX_DEAD_REQUEST_REMOVALS = 5
+
   # @param redis [RedisClient]
   # @param logger [::Logger,#debug]
   # @param log_lock_try [Boolean]
@@ -135,6 +159,9 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @param acquirer_id [String]
   # @param host_id [String]
   # @param acquirer_position [Numeric]
+  #   The position of the lock request (the score: the enqueue time shifted by the priority band).
+  # @param priority [Integer]
+  #   The lock request priority (the band of `acquirer_position`).
   # @param ttl [Integer]
   # @param queue_ttl [Integer]
   # @param lock_index_enabled [Boolean]
@@ -154,7 +181,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   #
   # @api private
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.22.0
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
@@ -170,6 +197,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     acquirer_id,
     host_id,
     acquirer_position,
+    priority,
     ttl,
     queue_ttl,
     lock_index_enabled,
@@ -234,7 +262,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
         inter_result = precheck_lock(
           rconn, logger, log_sampled, log_lock_try, lock_key, read_write_mode, lock_readers_key,
           request_queue, opposite_request_queue, lock_name, acquirer_id, host_id,
-          acquirer_position, acquirer_dead_score, queue_ttl, lock_index_enabled,
+          acquirer_position, priority, acquirer_dead_score, queue_ttl, lock_index_enabled,
           lock_index_grace_period, fail_fast, access_strategy
         )
         next if inter_result
@@ -255,14 +283,14 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
         #   - read lock expiration of the current acquirer;
         #   - the longest read lock (the last one in the readers registry): write lock requests
         #     only (read lock requests do not wait for other readers);
-        #   - (eager queueing) the lock request queueing: Steps 1, 2.1, 3 (`queue_lock_request`);
+        #   - (eager queueing) the lock request queueing: Steps 2.1, 1, 3 (`queue_lock_request`);
         # NOTE: replies are read by their positions: see "pipeline layout" in `pipeline_lock_state`
         # @type var lock_state: Array[untyped]
         lock_state = rconn.pipelined do |pipeline|
           pipeline_lock_state(
             pipeline, lock_key, lock_readers_key, acquirer_id, read_mode, eager_queueing,
-            request_queue, opposite_request_queue, acquirer_position, acquirer_dead_score,
-            lock_name, queue_ttl, lock_index_enabled, lock_index_grace_period
+            request_queue, opposite_request_queue, acquirer_position, priority,
+            acquirer_dead_score, lock_name, queue_ttl, lock_index_enabled, lock_index_grace_period
           )
         end
         # @type var current_lock_obtainer: String?
@@ -493,11 +521,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
           # Fast-Step X1: lock is already obtained. fail fast leads to "no try".
           inter_result = :fail_fast_no_try
         else
-          # Step 1: add an acquirer to the lock acquirement queue
           # Step 2.1: drop expired acquirers from the lock queues
+          # Step 1: add an acquirer to the lock acquirement queue
           # Step 3: get the actual acquirer waiting in the queue
           #   - one round trip for all of them (see `queue_lock_request`);
           #   - eager queueing: already done in the lock state round trip (Step 0.1);
+          #   - Step 2.2 (priorities) runs after them (see below);
           # @type var queue_replies: Array[untyped]
           queue_replies =
             if eager_queueing
@@ -506,30 +535,51 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
               rconn.pipelined do |pipeline|
                 queue_lock_request(
                   pipeline, request_queue, opposite_request_queue,
-                  acquirer_position, acquirer_id, acquirer_dead_score,
+                  acquirer_position, priority, acquirer_id, acquirer_dead_score,
                   lock_name, queue_ttl, lock_index_enabled, lock_index_grace_period
                 )
               end
             end
           # NOTE: the position of the first queueing reply (see "pipeline layout" in Step 0.1)
           queue_replies_at = eager_queueing ? LOCK_STATE_QUEUE_REPLIES_AT : 0
-          # @type var waiting_acquirer: String?
-          waiting_acquirer = queue_replies[queue_replies_at + QUEUE_HEAD_REPLY].first
+          # @type var waiting_request: [String, Float]?
+          waiting_request = queue_replies[queue_replies_at + QUEUE_HEAD_REPLY].first
           # @type var opposite_waiting_request: [String, Float]?
           opposite_waiting_request =
             queue_replies[queue_replies_at + OPPOSITE_QUEUE_HEAD_REPLY].first
 
           LogVisitor.acq_added_to_queue(
             logger, log_sampled, log_lock_try, lock_key,
-            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
+            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
           )
           LogVisitor.remove_expired_acqs(
             logger, log_sampled, log_lock_try, lock_key,
             queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
           )
+
+          # Step 2.2: (priorities) drop the dead lock requests of other priority bands that block
+          #   the current one (the queue head or the earlier request of the opposite mode) and get
+          #   the actual queue heads (no round trips while no dead request blocks the current one);
+          actual_queue_heads = drop_dead_requests_ahead(
+            rconn, read_write_mode, request_queue, opposite_request_queue, acquirer_id,
+            acquirer_position, acquirer_dead_score, access_strategy, waiting_request,
+            opposite_waiting_request
+          )
+          if actual_queue_heads
+            waiting_request, opposite_waiting_request, dropped_requests = actual_queue_heads
+            log_dropped_requests(
+              logger, log_sampled, log_lock_try, lock_key, queue_ttl, acquirer_id, host_id,
+              access_strategy, read_write_mode, dropped_requests
+            )
+          end
+          waiting_acquirer = waiting_request ? waiting_request[0] : nil
+          # NOTE: the priority of the first request is decoded for logs only
+          waiting_priority = logged_request_priority(log_sampled, log_lock_try, waiting_request)
+
           LogVisitor.get_first_from_queue(
             logger, log_sampled, log_lock_try, lock_key,
-            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer
+            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer,
+            waiting_priority
           )
 
           # Step 3.1 (RW) + Steps PRE-4.x, ROLLBACK 1.1, 1.2, 2, 3: the obstacle to the lock
@@ -549,7 +599,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
             log_lock_obstacle(
               rconn, obstacle, logger, log_sampled, log_lock_try, lock_key, queue_ttl,
               acquirer_id, host_id, access_strategy, read_write_mode,
-              waiting_acquirer, opposite_request_ahead, current_lock_obtainer
+              waiting_acquirer, waiting_priority, opposite_waiting_request, current_lock_obtainer
             )
             inter_result = obstacle
           elsif read_mode
@@ -648,6 +698,17 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
           end
         end
       end
+    rescue RedisQueuedLocks::LockAcquirementIntermediateTimeoutError,
+           RedisQueuedLocks::TimedLockIntermediateTimeoutError,
+           ::Timeout::ExitException
+      # NOTE: (timeouts) the timeout can interrupt the attempt inside the WATCH block:
+      #   redis-client sends `UNWATCH` only on `StandardError` (the internal timeouts and the
+      #   `Timeout.timeout` of the user without an exception class are `::Exception`s), and the
+      #   connection would return to the pool with the active WATCH (an EXEC of the next
+      #   transaction on it is aborted when a watched key is changed);
+      #   - the closed connection drops the WATCH state and is reconnected on the next use;
+      rconn.close
+      raise
     end
 
     # Step 7: Analyze the aquirement attempt:
@@ -818,24 +879,27 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
 
   private
 
-  # Queues the lock request and reads the lock queue state (Steps 1, 2.1, 3 and 3.2-3.4 of
+  # Queues the lock request and reads the lock queue state (Steps 2.1, 1, 3 and 3.2-3.4 of
   # the attempt): the commands are added to the given pipeline (one round trip with other
   # pipelined commands).
-  # Replies (positions relative to the first one): [0] ZADD NX, [1] ZREMRANGEBYSCORE (request
-  # queue), [2] ZREMRANGEBYSCORE (opposite request queue), [QUEUE_HEAD_REPLY] ZRANGE (the first
-  # request of the request queue), [OPPOSITE_QUEUE_HEAD_REPLY] ZRANGE WITHSCORES (the first
-  # request of the opposite request queue); the enabled lock index only: [5] PEXPIRE NX, [6]
-  # PEXPIRE GT (the request queue TTL), [7] ZADD GT (the lock index), [8] ZREMRANGEBYSCORE
-  # (expired lock names of the lock index). Update these constants when the commands change
-  # (new commands go to the end: the replies are not read after `OPPOSITE_QUEUE_HEAD_REPLY`, so
-  # the conditional lock index commands do not shift the read replies).
+  # Replies (positions relative to the first one): [0] ZREMRANGEBYSCORE (request queue, the
+  # priority band of the request), [1] ZREMRANGEBYSCORE (opposite request queue, the priority band
+  # of the request), [2] ZADD NX, [QUEUE_HEAD_REPLY] ZRANGE WITHSCORES (the first request of
+  # the request queue), [OPPOSITE_QUEUE_HEAD_REPLY] ZRANGE WITHSCORES (the first request of
+  # the opposite request queue); the enabled lock index only: [5] PEXPIRE NX, [6] PEXPIRE GT (the
+  # request queue TTL), [7] ZADD GT (the lock index), [8] ZREMRANGEBYSCORE (expired lock names of
+  # the lock index). Update these constants when the commands change (new commands go to the end:
+  # the replies are not read after `OPPOSITE_QUEUE_HEAD_REPLY`, so the conditional lock index
+  # commands do not shift the read replies).
   #
   # @param pipeline [RedisClient::Pipeline]
   # @param request_queue [String] Queue of the requests of the requested lock mode.
   # @param opposite_request_queue [String] Queue of the requests of the opposite lock mode.
-  # @param acquirer_position [Numeric]
+  # @param acquirer_position [Numeric] The enqueue time shifted by the priority band.
+  # @param priority [Integer] The priority band of `acquirer_position`.
   # @param acquirer_id [String]
-  # @param acquirer_dead_score [Float] Requests queued before this score are expired.
+  # @param acquirer_dead_score [Float]
+  #   Requests queued before this time are expired (the barrier of the default priority band).
   # @param lock_name [String] The lock name (the member of the lock index).
   # @param queue_ttl [Integer] Lifetime of the lock request (in seconds).
   # @param lock_index_enabled [Boolean] Send the lock index commands (Steps 3.2-3.4).
@@ -844,11 +908,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   #
   # @api private
   # @since 1.20.0
+  # @version 1.22.0
   def queue_lock_request(
     pipeline,
     request_queue,
     opposite_request_queue,
     acquirer_position,
+    priority,
     acquirer_id,
     acquirer_dead_score,
     lock_name,
@@ -856,6 +922,22 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     lock_index_enabled,
     lock_index_grace_period
   )
+    # Step 2.1: drop expired acquirers from the lock queues
+    #   - (RW) both queues are cleared: an expired request of the opposite mode should not
+    #     block the current request forever;
+    #   - (priorities) the requests of the priority band of the current request (the band has its
+    #     own time barrier, see `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`); a dead request of
+    #     another band is dropped when it blocks the current request (`drop_dead_requests_ahead`),
+    #     requests of lower priorities are never ahead of the current request;
+    #   - before the queueing (Step 1): the old (dead) position of the requeued request (its
+    #     position is reset after `queue_ttl`, see `dead_score_reached?`) is dropped first, so
+    #     `ZADD NX` adds its new position in the same round trip (after `ZADD NX` the old position
+    #     would be kept by `NX` and dropped by the removal: the request would be missing in the
+    #     queue in this attempt);
+    pipeline_dead_requests_removal(
+      pipeline, request_queue, opposite_request_queue, acquirer_dead_score, priority
+    )
+
     # Step 1: add an acquirer to the lock acquirement queue
     # NOTE:
     #   'NX' means "Only add new elements. Don't update already existing elements."
@@ -865,15 +947,10 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     #       not in the queue now>>;
     pipeline.call('ZADD', request_queue, 'NX', acquirer_position, acquirer_id)
 
-    # Step 2.1: drop expired acquirers from the lock queues
-    #   - (RW) both queues are cleared: an expired request of the opposite mode should not
-    #     block the current request forever;
-    pipeline.call('ZREMRANGEBYSCORE', request_queue, '-inf', acquirer_dead_score)
-    pipeline.call('ZREMRANGEBYSCORE', opposite_request_queue, '-inf', acquirer_dead_score)
-
-    # Step 3: get the actual acquirer waiting in the queue
+    # Step 3: get the actual acquirer waiting in the queue (with its position: the band and
+    #   the liveness of the queue head are decoded from it, see `drop_dead_requests_ahead`)
     #   - (RW) and the first request of the opposite mode;
-    pipeline.call('ZRANGE', request_queue, '0', '0')
+    pipeline.call('ZRANGE', request_queue, '0', '0', 'WITHSCORES')
     pipeline.call('ZRANGE', opposite_request_queue, '0', '0', 'WITHSCORES')
 
     # NOTE: the disabled lock index: no lock index commands, lock request queues have no TTL
@@ -910,6 +987,34 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     )
   end
 
+  # Adds the removal of the dead lock requests of the given priority band (both lock queues) to
+  # the given pipeline (see `queue_lock_request` and `drop_dead_requests_ahead`).
+  #
+  # @param pipeline [RedisClient::Pipeline]
+  # @param request_queue [String]
+  # @param opposite_request_queue [String]
+  # @param acquirer_dead_score [Float]
+  #   Requests queued before this time are expired (the barrier of the default priority band).
+  # @param priority [Integer]
+  #   The priority band (see `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`).
+  # @return [void]
+  #
+  # @api private
+  # @since 1.22.0
+  def pipeline_dead_requests_removal(
+    pipeline,
+    request_queue,
+    opposite_request_queue,
+    acquirer_dead_score,
+    priority
+  )
+    band_floor = RedisQueuedLocks::Resource.lock_priority_band_floor(priority)
+    band_dead_score =
+      RedisQueuedLocks::Resource.lock_priority_band_dead_score(acquirer_dead_score, priority)
+    pipeline.call('ZREMRANGEBYSCORE', request_queue, band_floor, band_dead_score)
+    pipeline.call('ZREMRANGEBYSCORE', opposite_request_queue, band_floor, band_dead_score)
+  end
+
   # Adds the lock state commands to the given pipeline (the lock state of the attempt and of
   # the pre-check: one round trip).
   #
@@ -938,6 +1043,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @param request_queue [String]
   # @param opposite_request_queue [String]
   # @param acquirer_position [Numeric]
+  # @param priority [Integer]
   # @param acquirer_dead_score [Float]
   # @param lock_name [String] The lock name (the member of the lock index).
   # @param queue_ttl [Integer] In seconds.
@@ -947,6 +1053,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   #
   # @api private
   # @since 1.20.0
+  # @version 1.22.0
   def pipeline_lock_state(
     pipeline,
     lock_key,
@@ -957,6 +1064,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     request_queue,
     opposite_request_queue,
     acquirer_position,
+    priority,
     acquirer_dead_score,
     lock_name,
     queue_ttl,
@@ -970,7 +1078,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     if queueing
       queue_lock_request(
         pipeline, request_queue, opposite_request_queue,
-        acquirer_position, acquirer_id, acquirer_dead_score,
+        acquirer_position, priority, acquirer_id, acquirer_dead_score,
         lock_name, queue_ttl, lock_index_enabled, lock_index_grace_period
       )
     end
@@ -980,6 +1088,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
 
   # (RW) The request of the opposite mode that should obtain the lock earlier
   #   - FIFO between modes (`:queued` access strategy only);
+  #   - (priorities) positions are shifted by the priority bands: a request of a higher priority
+  #     is ahead of any request of a lower priority, requests of the same priority are FIFO;
   #   - equal positions are ordered by acquirer ids;
   #
   # @param access_strategy [Symbol]
@@ -1071,12 +1181,17 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @param access_strategy [Symbol]
   # @param read_write_mode [Symbol]
   # @param waiting_acquirer [String,NilClass]
-  # @param opposite_request_ahead [String,NilClass]
+  # @param waiting_priority [Integer,NilClass]
+  #   The priority of the first request (decoded for logs only: `nil` without logs).
+  # @param opposite_waiting_request [Array<String,Float>,NilClass]
+  #   The first request of the opposite queue (the request ahead of the `*_request_is_ahead`
+  #   obstacles, see `find_opposite_request_ahead`).
   # @param current_lock_obtainer [String,NilClass]
   # @return [void]
   #
   # @api private
   # @since 1.20.0
+  # @version 1.22.0
   # rubocop:disable Metrics/MethodLength
   def log_lock_obstacle(
     rconn,
@@ -1091,7 +1206,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     access_strategy,
     read_write_mode,
     waiting_acquirer,
-    opposite_request_ahead,
+    waiting_priority,
+    opposite_waiting_request,
     current_lock_obtainer
   )
     case obstacle
@@ -1104,44 +1220,270 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
       LogVisitor.exit__no_first(
         logger, log_sampled, log_lock_try, lock_key,
         queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer,
+        waiting_priority,
         # NOTE: lock data is extracted for logs only
         ((log_sampled && log_lock_try) ? rconn.call('HGETALL', lock_key).to_h : NO_LOCK_DATA)
       )
-    when :write_request_is_ahead
-      LogVisitor.exit__write_request_ahead(
-        logger, log_sampled, log_lock_try, lock_key,
-        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode,
-        opposite_request_ahead #: String
-      )
-    when :read_request_is_ahead
-      LogVisitor.exit__read_request_ahead(
-        logger, log_sampled, log_lock_try, lock_key,
-        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode,
-        opposite_request_ahead #: String
-      )
+    when :write_request_is_ahead, :read_request_is_ahead
+      ahead_request = opposite_waiting_request #: [String, Float]
+      # NOTE: the priority of the request ahead is decoded for logs only
+      ahead_priority = logged_request_priority(log_sampled, log_lock_try, ahead_request)
+      if obstacle == :write_request_is_ahead
+        LogVisitor.exit__write_request_ahead(
+          logger, log_sampled, log_lock_try, lock_key,
+          queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode,
+          ahead_request[0], ahead_priority
+        )
+      else
+        LogVisitor.exit__read_request_ahead(
+          logger, log_sampled, log_lock_try, lock_key,
+          queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode,
+          ahead_request[0], ahead_priority
+        )
+      end
     when :lock_is_still_acquired
       LogVisitor.exit__lock_still_obtained(
         logger, log_sampled, log_lock_try, lock_key,
         queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode,
-        waiting_acquirer, current_lock_obtainer, #: String
+        waiting_acquirer, waiting_priority,
+        current_lock_obtainer, #: String
         # NOTE: lock data is extracted for logs only
         ((log_sampled && log_lock_try) ? rconn.call('HGETALL', lock_key).to_h : NO_LOCK_DATA)
       )
     when :read_lock_is_still_acquired
       LogVisitor.exit__read_lock_still_obtained(
         logger, log_sampled, log_lock_try, lock_key,
-        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer
+        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer,
+        waiting_priority
       )
     end
   end
   # rubocop:enable Metrics/MethodLength
 
+  # (priorities) The priority of the lock request for the try-lock logs (the first request of
+  # the queue, the request ahead): decoded only when the try-lock logs are written (log-only values
+  # are never computed without the logs: `log_sampled && log_lock_try`).
+  #
+  # @param log_sampled [Boolean]
+  # @param log_lock_try [Boolean]
+  # @param lock_request [Array<String,Float>,NilClass]
+  #   The acquirer and the position of the lock request.
+  # @return [Integer,NilClass] `nil` without the try-lock logs or without the lock request.
+  #
+  # @api private
+  # @since 1.22.0
+  def logged_request_priority(log_sampled, log_lock_try, lock_request)
+    return unless log_sampled && log_lock_try && lock_request
+
+    RedisQueuedLocks::Resource.lock_request_priority(lock_request[1])
+  end
+
+  # (priorities) Drops the dead lock requests of other priority bands that block the current lock
+  # request (`:queued` access strategy: the head of the write lock queue for write lock requests,
+  # the earlier lock request of the opposite mode for both modes) and reads the actual queue heads
+  # (Step 2.2 of the attempt and of its pre-check):
+  #   - the dead lock requests of the band of the current request are dropped by the queueing
+  #     (Step 2.1, before the queue heads are read) and requests of lower priorities are never
+  #     ahead of it: only a request of a higher priority can be a dead blocking request;
+  #   - the band and the enqueue time of the blocking request are decoded from its position (see
+  #     `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`): no Redis commands to check the liveness,
+  #     any band is recognized (the priority range of the current RQL version is not used), the
+  #     time barrier is the barrier of the current request (`acquirer_dead_score`: its `queue_ttl`);
+  #   - the dead blocking requests (the head of the write lock queue and the earlier request of the
+  #     opposite mode) are dropped with all dead requests of their bands (both queues) in one round
+  #     trip with the reading of the actual queue heads; no round trips while no dead request
+  #     blocks the current one (the lock state does not matter: the attempt drops the dead blocking
+  #     requests even when the lock is obtained by another acquirer);
+  #   - up to `MAX_DEAD_REQUEST_REMOVALS` round trips (one or two bands each) per call;
+  #   - (infinite positions) RQL never writes them (manual writes of the queues, see
+  #     `RedisQueuedLocks::Resource.lock_request_priority`): a blocking request at `-inf` is always
+  #     dead (the highest band, no enqueue time) and is dropped with all requests at `-inf` of both
+  #     queues in the same round trip; a request at `+inf` is never ahead of the current request;
+  #   - the dropped blocking requests are returned, not logged: the attempt and its pre-check log
+  #     them at the same step (after the queueing log events, see `log_dropped_requests`);
+  #
+  # @param rconn [RedisClient]
+  # @param read_write_mode [Symbol]
+  # @param request_queue [String]
+  # @param opposite_request_queue [String]
+  # @param acquirer_id [String]
+  # @param acquirer_position [Numeric]
+  # @param acquirer_dead_score [Float]
+  #   Requests queued before this time are expired (the barrier of the default priority band).
+  # @param access_strategy [Symbol]
+  # @param waiting_request [Array<String,Float>,NilClass] The head of the request queue.
+  # @param opposite_waiting_request [Array<String,Float>,NilClass]
+  #   The head of the opposite request queue.
+  # @return [Array<Array<String,Float>,NilClass,Array<Array<String,Integer>>>,NilClass]
+  #   - the actual queue heads and the dropped blocking requests (the acquirer and the priority of
+  #     each one, in the order of the removal): `[waiting_request, opposite_waiting_request,
+  #     dropped_requests]` when at least one dead lock request is dropped;
+  #   - `nil` otherwise;
+  #
+  # @api private
+  # @since 1.22.0
+  # rubocop:disable Metrics/MethodLength
+  def drop_dead_requests_ahead(
+    rconn,
+    read_write_mode,
+    request_queue,
+    opposite_request_queue,
+    acquirer_id,
+    acquirer_position,
+    acquirer_dead_score,
+    access_strategy,
+    waiting_request,
+    opposite_waiting_request
+  )
+    return unless access_strategy == :queued
+
+    read_mode = (read_write_mode == :read)
+    round_trips = 0
+    # NOTE: allocated by the first removal only (no allocations while nothing dead blocks)
+    # @type var dropped_requests: Array[[String, Integer]]?
+    dropped_requests = nil
+
+    while round_trips < MAX_DEAD_REQUEST_REMOVALS
+      # NOTE: the lock requests that block the current one (the same order as in `lock_obstacle`):
+      #   the head of the write lock queue (write lock requests only) and the earlier lock request
+      #   of the opposite mode; a live head of the write lock queue stops the removal (the attempt
+      #   waits for it), the dead blocking requests are dropped in one round trip (both bands);
+      # @type var dead_head: [String, Float]?
+      dead_head = nil
+      # @type var dead_head_priority: Integer?
+      dead_head_priority = nil
+      if !read_mode && waiting_request && waiting_request[0] != acquirer_id
+        dead_head_priority = dead_request_priority(waiting_request, acquirer_dead_score)
+        break unless dead_head_priority
+
+        dead_head = waiting_request
+      end
+      # @type var dead_ahead: [String, Float]?
+      dead_ahead = nil
+      # @type var dead_ahead_priority: Integer?
+      dead_ahead_priority = nil
+      if find_opposite_request_ahead(
+        access_strategy, opposite_waiting_request, acquirer_position, acquirer_id
+      )
+        ahead_request = opposite_waiting_request #: [String, Float]
+        dead_ahead_priority = dead_request_priority(ahead_request, acquirer_dead_score)
+        dead_ahead = ahead_request if dead_ahead_priority
+      end
+      break unless dead_head_priority || dead_ahead_priority
+
+      # NOTE: (pipeline layout) ZREMRANGEBYSCORE of both queues for each dropped band (one or two
+      #   bands) and for the requests at `-inf` (a dead blocking request at `-inf` only), then [-2]
+      #   ZRANGE WITHSCORES (the head of the request queue) and [-1] ZRANGE WITHSCORES (the head of
+      #   the opposite request queue);
+      # @type var queue_state: Array[untyped]
+      queue_state = rconn.pipelined do |pipeline|
+        if dead_head_priority
+          pipeline_dead_requests_removal(
+            pipeline, request_queue, opposite_request_queue, acquirer_dead_score, dead_head_priority
+          )
+        end
+        if dead_ahead_priority && dead_ahead_priority != dead_head_priority
+          pipeline_dead_requests_removal(
+            pipeline, request_queue, opposite_request_queue, acquirer_dead_score,
+            dead_ahead_priority
+          )
+        end
+        # NOTE: (infinite positions) a dead blocking request at `-inf` (a manual write: out of all
+        #   bands, see `RedisQueuedLocks::Resource.lock_request_priority`) is not covered by
+        #   the band removal of its decoded priority (it drops the dead requests of that band
+        #   only): the requests at `-inf` are dropped from both queues by their position;
+        if (dead_head && dead_head[1] == -Float::INFINITY) ||
+           (dead_ahead && dead_ahead[1] == -Float::INFINITY)
+          pipeline.call('ZREMRANGEBYSCORE', request_queue, '-inf', '-inf')
+          pipeline.call('ZREMRANGEBYSCORE', opposite_request_queue, '-inf', '-inf')
+        end
+        pipeline.call('ZRANGE', request_queue, '0', '0', 'WITHSCORES')
+        pipeline.call('ZRANGE', opposite_request_queue, '0', '0', 'WITHSCORES')
+      end
+      # @type var removed_requests: Array[[String, Integer]]
+      removed_requests = dropped_requests || []
+      removed_requests << [dead_head[0], dead_head_priority] if dead_head && dead_head_priority
+      removed_requests << [dead_ahead[0], dead_ahead_priority] if dead_ahead && dead_ahead_priority
+      dropped_requests = removed_requests
+      waiting_request = queue_state[-2].first
+      opposite_waiting_request = queue_state[-1].first
+      round_trips += 1
+    end
+
+    [waiting_request, opposite_waiting_request, dropped_requests] if dropped_requests
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  # (priorities) Logs the dead lock requests dropped by `drop_dead_requests_ahead` (the attempt
+  # and its pre-check log them at the same step: after the queueing log events).
+  #
+  # @param logger [::Logger,#debug]
+  # @param log_sampled [Boolean]
+  # @param log_lock_try [Boolean]
+  # @param lock_key [String]
+  # @param queue_ttl [Integer]
+  # @param acquirer_id [String]
+  # @param host_id [String]
+  # @param access_strategy [Symbol]
+  # @param read_write_mode [Symbol]
+  # @param dropped_requests [Array<Array<String,Integer>>]
+  #   The acquirer and the priority of each dropped lock request.
+  # @return [void]
+  #
+  # @api private
+  # @since 1.22.0
+  def log_dropped_requests(
+    logger,
+    log_sampled,
+    log_lock_try,
+    lock_key,
+    queue_ttl,
+    acquirer_id,
+    host_id,
+    access_strategy,
+    read_write_mode,
+    dropped_requests
+  )
+    return unless log_sampled && log_lock_try
+
+    dropped_requests.each do |dead_acquirer_id, dead_priority|
+      LogVisitor.dead_request_removed(
+        logger, log_sampled, log_lock_try, lock_key, queue_ttl, acquirer_id, host_id,
+        access_strategy, read_write_mode, dead_acquirer_id, dead_priority
+      )
+    end
+  end
+
+  # (priorities) The priority band of the dead lock request (see `drop_dead_requests_ahead`): the
+  # band and the enqueue time are decoded from the position of the request (infinite positions:
+  # `-inf` is decoded to the highest band and is always dead, `+inf` to the lowest band and is never
+  # dead, see `RedisQueuedLocks::Resource.lock_request_priority`).
+  #
+  # @param lock_request [Array<String,Float>] The acquirer and the position of the lock request.
+  # @param acquirer_dead_score [Float]
+  #   Requests queued before this time are expired (the barrier of the default priority band).
+  # @return [Integer,NilClass]
+  #   The priority of the dead lock request, `nil` for a live one (its position is after the time
+  #   barrier of its band: the same barrier as the dropping of the dead requests of the band).
+  #
+  # @api private
+  # @since 1.22.0
+  def dead_request_priority(lock_request, acquirer_dead_score)
+    priority = RedisQueuedLocks::Resource.lock_request_priority(lock_request[1])
+    band_dead_score =
+      RedisQueuedLocks::Resource.lock_priority_band_dead_score(acquirer_dead_score, priority)
+    priority if lock_request[1] <= band_dead_score
+  end
+
   # Pre-check of the attempt (Step PRE): the lock state without WATCH (one round trip).
   #   - `fail_fast` attempts: the lock state only (the request is not queued: the failed "no try"
   #     attempt does not dequeue the request); fails with `:fail_fast_no_try` on the obtained lock;
   #   - retries: the lock state and the lock request queueing (the request is already queued by
   #     the previous attempts); fails with the obstacle of the classic logic (`lock_obstacle`)
-  #     and logs the same events as the failed attempt;
+  #     and logs the same events as the failed attempt in the same order;
+  #   - (priorities) retries drop the dead lock requests of other priority bands that block the
+  #     request before the decision (Step 2.2 of the attempt: one more round trip per dropped
+  #     band, see `drop_dead_requests_ahead`);
   #   - same-process conflicts (the lock is obtained by the current acquirer) and locks that can be
   #     obtained are not decided: the attempt continues with the WATCH/MULTI logic (`nil`);
   #   - the pre-check never obtains the lock (mutual exclusion relies on WATCH/MULTI only);
@@ -1159,6 +1501,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   # @param acquirer_id [String]
   # @param host_id [String]
   # @param acquirer_position [Numeric]
+  # @param priority [Integer]
   # @param acquirer_dead_score [Float]
   # @param queue_ttl [Integer]
   # @param lock_index_enabled [Boolean]
@@ -1169,6 +1512,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
   #
   # @api private
   # @since 1.20.0
+  # @version 1.22.0
   # rubocop:disable Metrics/MethodLength
   def precheck_lock(
     rconn,
@@ -1184,6 +1528,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     acquirer_id,
     host_id,
     acquirer_position,
+    priority,
     acquirer_dead_score,
     queue_ttl,
     lock_index_enabled,
@@ -1197,7 +1542,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     lock_state = rconn.pipelined do |pipeline|
       pipeline_lock_state(
         pipeline, lock_key, lock_readers_key, acquirer_id, read_mode, !fail_fast,
-        request_queue, opposite_request_queue, acquirer_position, acquirer_dead_score,
+        request_queue, opposite_request_queue, acquirer_position, priority, acquirer_dead_score,
         lock_name, queue_ttl, lock_index_enabled, lock_index_grace_period
       )
     end
@@ -1217,12 +1562,26 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
     # NOTE: the fail-fast check of the attempt (Fast-Step X0) without same-process conflicts
     return ((current_lock_obtainer || read_locked) ? :fail_fast_no_try : nil) if fail_fast
 
-    # @type var waiting_acquirer: String?
-    waiting_acquirer =
-      lock_state[LOCK_STATE_QUEUE_REPLIES_AT + QUEUE_HEAD_REPLY].first
+    # @type var waiting_request: [String, Float]?
+    waiting_request = lock_state[LOCK_STATE_QUEUE_REPLIES_AT + QUEUE_HEAD_REPLY].first
     # @type var opposite_waiting_request: [String, Float]?
     opposite_waiting_request =
       lock_state[LOCK_STATE_QUEUE_REPLIES_AT + OPPOSITE_QUEUE_HEAD_REPLY].first
+    # NOTE: (priorities) Step 2.2 of the attempt: the dead lock requests of other priority bands
+    #   that block the current one are dropped before the obstacle decision; they are logged at
+    #   the step of the attempt (after the queueing log events of the failed pre-check, they
+    #   follow the decision) or before the attempt that continues (it logs its own queueing);
+    actual_queue_heads = drop_dead_requests_ahead(
+      rconn, read_write_mode, request_queue, opposite_request_queue, acquirer_id,
+      acquirer_position, acquirer_dead_score, access_strategy, waiting_request,
+      opposite_waiting_request
+    )
+    # @type var dropped_requests: Array[[String, Integer]]?
+    dropped_requests = nil
+    if actual_queue_heads
+      waiting_request, opposite_waiting_request, dropped_requests = actual_queue_heads
+    end
+    waiting_acquirer = waiting_request ? waiting_request[0] : nil
     # @type var opposite_request_ahead: String?
     opposite_request_ahead = find_opposite_request_ahead(
       access_strategy, opposite_waiting_request, acquirer_position, acquirer_id
@@ -1231,25 +1590,44 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
       read_mode, access_strategy, acquirer_id, waiting_acquirer, opposite_request_ahead,
       current_lock_obtainer, read_locked
     )
-    return unless obstacle
+    unless obstacle
+      if dropped_requests
+        log_dropped_requests(
+          logger, log_sampled, log_lock_try, lock_key, queue_ttl, acquirer_id, host_id,
+          access_strategy, read_write_mode, dropped_requests
+        )
+      end
+      return
+    end
 
-    # NOTE: the same log events as the failed attempt (queueing steps + the exit event)
+    # NOTE: the priority of the first request is decoded for logs only
+    waiting_priority = logged_request_priority(log_sampled, log_lock_try, waiting_request)
+
+    # NOTE: the same log events as the failed attempt in the same order (queueing steps, the dropped
+    #   dead requests, the first request, the exit event)
     LogVisitor.acq_added_to_queue(
       logger, log_sampled, log_lock_try, lock_key,
-      queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
+      queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
     )
     LogVisitor.remove_expired_acqs(
       logger, log_sampled, log_lock_try, lock_key,
       queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
     )
+    if dropped_requests
+      log_dropped_requests(
+        logger, log_sampled, log_lock_try, lock_key, queue_ttl, acquirer_id, host_id,
+        access_strategy, read_write_mode, dropped_requests
+      )
+    end
     LogVisitor.get_first_from_queue(
       logger, log_sampled, log_lock_try, lock_key,
-      queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer
+      queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, waiting_acquirer,
+      waiting_priority
     )
     log_lock_obstacle(
       rconn, obstacle, logger, log_sampled, log_lock_try, lock_key, queue_ttl,
       acquirer_id, host_id, access_strategy, read_write_mode,
-      waiting_acquirer, opposite_request_ahead, current_lock_obtainer
+      waiting_acquirer, waiting_priority, opposite_waiting_request, current_lock_obtainer
     )
     obstacle
   end