redis_queued_locks 1.20.0 → 1.22.0

data/lib/redis_queued_locks/acquirer/lock_series_poc.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
 # NOTE: Lock Series PoC
-# rubocop:disable all
+# rubocop:disable Metrics/ModuleLength, Metrics/ClassLength, Metrics/MethodLength
 # @api private
 # @since 1.16.0
+# @version 1.22.0
 module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
   require_relative 'lock_series_poc/log_visitor'
   require_relative 'lock_series_poc/instr_visitor'
 
-  # @sine 1.16.0
+  # @since 1.16.0
   extend RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
 
   class << self
     # @api private
     # @since 1.16.0
-    # @version 1.20.0
+    # @version 1.22.0
     def lock_series_poc( # steep:ignore
       redis,
       lock_names,
@@ -44,6 +45,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
+      lock_priorities:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
@@ -56,6 +59,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     )
       # NOTE: (RW) the lock mode is the same for all locks of the series
       #   (see RedisQueuedLocks::Acquirer::AcquireLock for read_write_mode validations);
+      # NOTE: the lock request priority is the same for all locks of the series too (validated
+      #   below: the series logs and instrumentation report it);
 
       case meta
       when Hash, NilClass then nil
@@ -66,19 +71,22 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         )
       end
 
+      # NOTE: Symbol keys are written to the lock data as Strings (the same check as in
+      #   RedisQueuedLocks::Acquirer::AcquireLock);
       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,
@@ -88,6 +96,51 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         )
       end
 
+      # NOTE: the series ttl is validated before the lock ttl calculation: each lock ttl of
+      #   the series includes the retry delay and jitter (a non-positive series ttl can produce
+      #   a positive lock ttl), the series ttl limits the `timed` block (the same check as in
+      #   RedisQueuedLocks::Acquirer::AcquireLock);
+      if !ttl.is_a?(::Integer) || ttl <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:ttl` argument should be a positive Integer, got #{ttl.inspect}."
+        )
+      end
+
+      # NOTE: the retry delay and jitter are parts of the lock ttls of the series (validated before
+      #   the lock ttl calculation; other options are validated by
+      #   RedisQueuedLocks::Acquirer::AcquireLock on the first lock of the series, before any lock
+      #   is obtained);
+      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
+
+      # NOTE: the priority of the series is validated before the series logs and instrumentation:
+      #   a priority name is resolved to its Integer priority (the series events report the Integer
+      #   priority; the same check as in RedisQueuedLocks::Acquirer::AcquireLock);
+      priority = lock_priorities.fetch(priority, priority) if priority.is_a?(::Symbol)
+      if !priority.is_a?(::Integer) ||
+         priority < RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY ||
+         priority > RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:priority` argument should be an Integer from " \
+          "#{RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY} to " \
+          "#{RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY} or a priority name of " \
+          "`config['lock_priorities']` (#{lock_priorities.keys.map(&:inspect).join(', ')}), " \
+          "got #{priority.inspect}."
+        )
+      end
+
       locks_count = lock_names.size
 
       lock_acquirement_operations = lock_names.each_with_index.map do |lock_name, position|
@@ -132,10 +185,10 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         identity
       )
 
-      RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.start_lock_series_obtaining( # steep:ignore
+      LogVisitor.start_lock_series_obtaining( # steep:ignore
         logger, log_sampled, lock_keys_for_instrumentation,
-        queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, access_strategy,
-        read_write_mode
+        queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation,
+        access_strategy, read_write_mode, priority
       )
 
       acq_start_time = RedisQueuedLocks::Utilities.clock_gettime
@@ -176,6 +229,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
               conflict_strategy:,
               read_write_mode:,
               access_strategy:,
+              priority:,
+              lock_priorities:,
               log_sampling_enabled:,
               log_sampling_percent:,
               log_sampler:,
@@ -208,7 +263,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         else
           failed_on_lock = lock_operation_options[:lock_name]
           failed_locks_and_errors[lock_operation_options[:lock_name]] = result
-          # NOTE: release all previously acquired locks (non-exceptional failure: raise_errors: false)
+          # NOTE: release all previously acquired locks
+          #   (non-exceptional failure: raise_errors: false)
           unless is_failed_series_released
             release_lock_series( # steep:ignore
               redis, read_write_mode, successfully_acquired_locks, acquirer_id_for_instrumentation
@@ -219,20 +275,22 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         end
       end
 
-      if (successfully_acquired_locks.size == lock_names.size && (successfully_acquired_locks.all? { |res| res[:ok] }))
+      if successfully_acquired_locks.size == lock_names.size &&
+         successfully_acquired_locks.all? { |res| res[:ok] }
         acq_end_time = RedisQueuedLocks::Utilities.clock_gettime
         acq_time = ((acq_end_time - acq_start_time) / 1_000.0).ceil(2)
         ts = Time.now.to_f
 
-        RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.lock_series_obtained( # steep:ignore
+        LogVisitor.lock_series_obtained( # steep:ignore
           logger, log_sampled, lock_keys_for_instrumentation,
           queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation,
-          acq_time, access_strategy, read_write_mode
+          acq_time, access_strategy, read_write_mode, priority
         )
 
-        RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor.lock_series_obtained( # steep:ignore
-          instrumenter, instr_sampled, lock_keys_for_instrumentation, read_write_mode,
-          ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, ts, acq_time, instrument
+        InstrVisitor.lock_series_obtained( # steep:ignore
+          instrumenter, instr_sampled, lock_keys_for_instrumentation, read_write_mode, priority,
+          ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, ts, acq_time,
+          instrument
         )
 
         yield_time = RedisQueuedLocks::Utilities.clock_gettime
@@ -242,8 +300,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
         ).ceil(2)
 
         yield_result = nil
-        is_lock_manually_released = nil
-        hold_time = nil
+        # @type var is_lock_manually_released: bool
+        # @type var hold_time: Float | Integer
 
         begin
           yield_result = yield_expire( # steep:ignore
@@ -284,17 +342,18 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
           hold_time = ((rel_time - acq_end_time) / 1_000.0).ceil(2)
           ts = Time.now.to_f
 
-          RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor.expire_lock_series( # steep:ignore
+          LogVisitor.expire_lock_series( # steep:ignore
             logger, log_sampled, lock_keys_for_instrumentation,
-            queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation, access_strategy,
-            read_write_mode
+            queue_ttl, acquirer_id_for_instrumentation, host_id_for_instrumentation,
+            access_strategy, read_write_mode, priority
           ) if is_lock_manually_released
 
-          RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor.lock_series_hold_and_release( # steep:ignore
+          InstrVisitor.lock_series_hold_and_release( # steep:ignore
             instrumenter,
             instr_sampled,
             lock_keys_for_instrumentation,
             read_write_mode,
+            priority,
             ttl,
             acquirer_id_for_instrumentation,
             host_id_for_instrumentation,
@@ -330,7 +389,7 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
             lock_series: lock_names,
             acquired_locks:,
             missing_locks:,
-            failed_on_lock:,
+            failed_on_lock:
           }
         }
       end
@@ -350,7 +409,9 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     #
     # @api private
     # @since 1.18.0
-    def release_lock_series(redis, read_write_mode, successfully_acquired_locks, acquirer_id) # steep:ignore
+    def release_lock_series( # steep:ignore
+      redis, read_write_mode, successfully_acquired_locks, acquirer_id
+    )
       lock_names = obtained_lock_names(successfully_acquired_locks) # steep:ignore
 
       if read_write_mode == :read
@@ -374,7 +435,7 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     #
     # @api private
     # @since 1.18.0
-    # @version 1.20.0
+    # @version 1.21.0
     def release_write_lock_series(redis, lock_names, acquirer_id) # steep:ignore
       return if lock_names.empty?
 
@@ -395,8 +456,16 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
             own_lock_keys.each { |lock_key| transaction.call('DEL', lock_key) }
           end
           # NOTE: `nil` => the transaction is aborted (a watched lock is changed) => retry
-          break unless released.nil?
+          break unless released == nil
         end
+      rescue RedisQueuedLocks::LockAcquirementIntermediateTimeoutError,
+             RedisQueuedLocks::TimedLockIntermediateTimeoutError,
+             ::Timeout::ExitException
+        # NOTE: (timeouts) an interrupted WATCH block (the internal timeouts and the user's
+        #   `Timeout.timeout` without an exception class): the closed connection drops the WATCH
+        #   state (redis-client sends `UNWATCH` only on `StandardError`);
+        conn.close
+        raise
       end
     end
 
@@ -441,4 +510,4 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     end
   end
 end
-# rubocop:enable all
+# rubocop:enable Metrics/ModuleLength, Metrics/ClassLength, Metrics/MethodLength

data/lib/redis_queued_locks/acquirer/locks.rb

@@ -25,8 +25,17 @@ module RedisQueuedLocks::Acquirer::Locks
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
     def locks(redis_client, scan_size:, with_info:, lock_index_enabled:)
+      # NOTE: (arguments) the same range as the config key: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      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
+
       redis_client.with do |rconn|
         lock_keys =
           lock_index_enabled ? index_locks(rconn, scan_size) : scan_locks(rconn, scan_size)
@@ -106,7 +115,8 @@ module RedisQueuedLocks::Acquirer::Locks
 
     # 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.
+    # the index yet) are skipped: all their keys are expired (`+inf` names, keys without TTL, never
+    # expire: see `RedisQueuedLocks::Resource.lock_index_score_expired?`).
     #
     # NOTE: each operation module iterates over the lock index by itself (duplicated on purpose:
     #   operation modules are independent of each other, see `extract_locks_info`);
@@ -119,6 +129,7 @@ module RedisQueuedLocks::Acquirer::Locks
     #
     # @api private
     # @since 1.20.0
+    # @version 1.22.0
     def each_lock_name_batch(redis_client, scan_size)
       lock_index_time = RedisQueuedLocks::Resource.lock_index_time
       # @type var lock_names: Array[String]
@@ -127,7 +138,9 @@ module RedisQueuedLocks::Acquirer::Locks
       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
+        next if RedisQueuedLocks::Resource.lock_index_score_expired?(
+          lock_index_score, lock_index_time
+        )
 
         lock_names << lock_name
         next if lock_names.size < scan_size
@@ -153,7 +166,7 @@ module RedisQueuedLocks::Acquirer::Locks
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def extract_locks_info(redis_client, lock_keys, scan_size)
       Set.new.tap do |seeded_locks|
@@ -162,6 +175,13 @@ module RedisQueuedLocks::Acquirer::Locks
         # rubocop:enable Layout/LineLength
 
         lock_keys.each_slice(scan_size) do |lock_keys_batch|
+          # Step 0: lock names of the batch (once per lock: the readers registry keys and the read
+          #   lock data keys are built from them)
+          # @type var lock_names_batch: Array[String]
+          lock_names_batch = lock_keys_batch.map do |lock_key|
+            RedisQueuedLocks::Resource.lock_name_from_key(lock_key, :lock) #: String
+          end
+
           # Step 1: extract the state of the batch of locks in one round trip
           # NOTE: (pipeline layout) [0] TIME (read locks are checked in redis time), then
           #   `LOCK_STATE_REPLIES` replies per lock in the batch order (the replies of the lock
@@ -170,10 +190,9 @@ module RedisQueuedLocks::Acquirer::Locks
           # @type var batch_state: Array[untyped]
           batch_state = redis_client.pipelined do |pipeline|
             pipeline.call('TIME')
-            lock_keys_batch.each do |lock_key|
-              lock_readers_key = RedisQueuedLocks::Resource.prepare_lock_readers(
-                lock_key.delete_prefix('rql:lock:')
-              )
+            lock_keys_batch.each_with_index do |lock_key, index|
+              lock_readers_key =
+                RedisQueuedLocks::Resource.prepare_lock_readers(lock_names_batch[index])
               pipeline.call('HGETALL', lock_key)
               pipeline.call('PTTL', lock_key)
               pipeline.call('ZRANGE', lock_readers_key, '0', '-1', 'WITHSCORES')
@@ -199,12 +218,13 @@ module RedisQueuedLocks::Acquirer::Locks
           #   read lock data can be absent if it is dropped during the read lock life;
           # @type var read_locks_data: Array[Hash[String,String]]
           read_locks_data = redis_client.pipelined do |pipeline|
-            lock_keys_batch.each_with_index do |lock_key, index|
-              lock_name = lock_key.delete_prefix('rql:lock:')
+            lock_keys_batch.each_index do |index|
               live_read_locks[index]&.each do |(acquirer_id, _expiration)|
                 pipeline.call(
                   'HGETALL',
-                  RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+                  RedisQueuedLocks::Resource.prepare_read_lock_key(
+                    lock_names_batch[index], acquirer_id
+                  )
                 )
               end
             end
@@ -232,6 +252,7 @@ module RedisQueuedLocks::Acquirer::Locks
                 pttl_cmd_res = batch_state[replies_at + 1] # NOTE: PTTL result (integer)
 
                 hget_cmd_res.tap do |lock_data|
+                  lock_data['lock_key'] = lock_key
                   lock_data['rw_mode'] = 'write'
                   lock_data['ts'] = Float(lock_data['ts'])
                   lock_data['ini_ttl'] = Integer(lock_data['ini_ttl'])

data/lib/redis_queued_locks/acquirer/queue_info.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.20.0
 module RedisQueuedLocks::Acquirer::QueueInfo
   class << self
     # Returns an information about the required lock queue by the lock name. The result
@@ -17,22 +16,34 @@ module RedisQueuedLocks::Acquirer::QueueInfo
     #   - result format: {
     #     "lock_queue" => "rql:lock_queue:your_lock_name", # lock queue key in redis,
     #     "queue" => [
-    #       { "acq_id" => "rql:acq:123/456/789/987/id", "score" => 123.456, "rw_mode" => "write" },
-    #       { "acq_id" => "rql:acq:123/686/789/987/id", "score" => 456.789, "rw_mode" => "write" },
+    #       {
+    #         "acq_id" => "rql:acq:123/456/789/987/id",
+    #         "score" => 123.456,
+    #         "rw_mode" => "write",
+    #         "priority" => 0
+    #       },
     #       ...
     #     ] # ordered set (by score) with information about an acquirer, their position in queue
-    #       # and the requested lock mode
+    #       # (the enqueue time shifted by the priority band: see
+    #       # `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`), the requested lock mode and
+    #       # the lock request priority (decoded from the position)
     #     <additional keys when the queue of read lock requests exists>:
     #     "read_lock_queue" => "rql:lock_read_queue:your_lock_name", # read lock queue key in redis
     #     "read_queue" => [
-    #       { "acq_id" => "rql:acq:123/456/789/987/id", "score" => 123.456, "rw_mode" => "read" },
+    #       {
+    #         "acq_id" => "rql:acq:123/456/789/987/id",
+    #         "score" => 123.456,
+    #         "rw_mode" => "read",
+    #         "priority" => 0
+    #       },
     #       ...
     #     ] # read lock requests (positions are comparable with the write lock request positions)
     #   }
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.22.0
+    # rubocop:disable Metrics/MethodLength
     def queue_info(redis_client, lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
       read_lock_key_queue = RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
@@ -55,14 +66,24 @@ module RedisQueuedLocks::Acquirer::QueueInfo
         queue_info = {
           'lock_queue' => lock_key_queue,
           'queue' => zrange_cmd_res.map do |val|
-            { 'acq_id' => val[0], 'score' => val[1], 'rw_mode' => 'write' }
+            {
+              'acq_id' => val[0],
+              'score' => val[1],
+              'rw_mode' => 'write',
+              'priority' => RedisQueuedLocks::Resource.lock_request_priority(val[1])
+            }
           end
         }
         # NOTE: (RW) the queue of read lock requests
         unless read_zrange_cmd_res.empty?
           queue_info['read_lock_queue'] = read_lock_key_queue
           queue_info['read_queue'] = read_zrange_cmd_res.map do |val|
-            { 'acq_id' => val[0], 'score' => val[1], 'rw_mode' => 'read' }
+            {
+              'acq_id' => val[0],
+              'score' => val[1],
+              'rw_mode' => 'read',
+              'priority' => RedisQueuedLocks::Resource.lock_request_priority(val[1])
+            }
           end
         end
         queue_info
@@ -71,5 +92,6 @@ module RedisQueuedLocks::Acquirer::QueueInfo
         nil
       end
     end
+    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/redis_queued_locks/acquirer/queues.rb

@@ -15,8 +15,17 @@ module RedisQueuedLocks::Acquirer::Queues
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.22.0
     def queues(redis_client, scan_size:, with_info:, lock_index_enabled:)
+      # NOTE: (arguments) the same range as the config key: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      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
+
       redis_client.with do |rconn|
         lock_queues =
           lock_index_enabled ? index_queues(rconn, scan_size) : scan_queues(rconn, scan_size)
@@ -93,7 +102,8 @@ module RedisQueuedLocks::Acquirer::Queues
 
     # 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.
+    # the index yet) are skipped: all their keys are expired (`+inf` names, keys without TTL, never
+    # expire: see `RedisQueuedLocks::Resource.lock_index_score_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`);
@@ -106,6 +116,7 @@ module RedisQueuedLocks::Acquirer::Queues
     #
     # @api private
     # @since 1.20.0
+    # @version 1.22.0
     def each_lock_name_batch(redis_client, scan_size)
       lock_index_time = RedisQueuedLocks::Resource.lock_index_time
       # @type var lock_names: Array[String]
@@ -114,7 +125,9 @@ module RedisQueuedLocks::Acquirer::Queues
       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
+        next if RedisQueuedLocks::Resource.lock_index_score_expired?(
+          lock_index_score, lock_index_time
+        )
 
         lock_names << lock_name
         next if lock_names.size < scan_size
@@ -130,11 +143,13 @@ module RedisQueuedLocks::Acquirer::Queues
     # @param lock_queues [Set<String>]
     # @param scan_size [Integer] The number of queues whose requests are read in one round trip.
     # @return [Set<Hash<Symbol,Any>>]
-    #   - each request: `{ 'acq_id' => String, 'score' => Float, 'rw_mode' => 'read'/'write' }`;
+    #   - each request: `{ 'acq_id' => String, 'score' => Float, 'rw_mode' => 'read'/'write',
+    #     'priority' => Integer }` (the priority is decoded from the position: see
+    #     `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`);
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.22.0
     def extract_queues_info(redis_client, lock_queues, scan_size)
       # NOTE: the same approach as in `QueueInfo` (duplicated on purpose: public operation modules
       #   do not reuse each other, they share logic via `Resource`, `Utilities`);
@@ -162,7 +177,12 @@ module RedisQueuedLocks::Acquirer::Queues
             seeded_queues << {
               queue: lock_queue,
               requests: queues_requests[index].map do |val|
-                { 'acq_id' => val[0], 'score' => val[1], 'rw_mode' => rw_mode }
+                {
+                  'acq_id' => val[0],
+                  'score' => val[1],
+                  'rw_mode' => rw_mode,
+                  'priority' => RedisQueuedLocks::Resource.lock_request_priority(val[1])
+                }
               end
             }
           end