redis_queued_locks 1.21.0 → 1.22.0

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.21.0
+# @version 1.22.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @return [RedisClient]
@@ -43,7 +43,7 @@ class RedisQueuedLocks::Client
   # @version 1.13.0
   def initialize(redis_client, &configuration)
     @config = RedisQueuedLocks::Config.new(&configuration)
-    @uniq_identity = config['uniq_identifier'].call #: String
+    @uniq_identity = config['uniq_identifier'].call
     @redis_client = redis_client
     @swarm = RedisQueuedLocks::Swarm.new(self)
     @swarm.swarm! if config['swarm.auto_swarm']
@@ -232,8 +232,9 @@ class RedisQueuedLocks::Client
   #   - `:queued` access strategy orders read and write lock requests in FIFO between modes
   #     (read lock request waits for earlier write lock requests, write lock request waits for
   #     earlier read and write lock requests) so writers are not starved by readers;
-  #   - `:random` access strategy ignores lock queues (a continuous flow of readers can starve
-  #     writers);
+  #   - `:random` access strategy: the lock request does not wait for earlier requests (no order
+  #     between modes: a continuous flow of readers can starve writers), but it is queued like any
+  #     lock request (`:queued` lock requests wait for it);
   #   - read lock specifics:
   #     - read lock is released (with a block of code) or expired (by `ttl`) independently
   #       of other read locks; `#unlock` releases all read locks and the write lock;
@@ -255,6 +256,24 @@ class RedisQueuedLocks::Client
   #       (but with checking the limist, retries, timeouts and so on). if lock is
   #       free to obtain - it will be obtained;
   #   - pre-configured in `config['default_access_strategy']`;
+  # @option priority [Integer,Symbol]
+  #   - The lock request priority: an Integer from `-100` (the lowest) to `100` (the highest),
+  #     `0` by default (`RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY`..`MAX_LOCK_PRIORITY`),
+  #     or a priority name of `config['lock_priorities']` (`:lowest` (-100), `:low` (-50),
+  #     `:normal` (0), `:high` (50), `:highest` (100) by default; the application can define its
+  #     own names, `merge` keeps the default ones:
+  #     `config['lock_priorities'] = config['lock_priorities'].merge(payment: 90, email: -10)`);
+  #   - `:queued` access strategy: the lock request is placed in the lock request queue after all
+  #     requests of the same or higher priority and before all requests of the lower priority
+  #     (strict priority, FIFO inside the same priority; read and write lock requests too);
+  #   - `:random` access strategy: the lock request does not wait for its turn (it ignores the order
+  #     of the lock request queues and the priorities of other requests), but it is queued at the
+  #     position of its priority like a `:queued` one: `:queued` lock requests wait for it;
+  #   - the obtained lock is never taken away: the priority orders the waiting lock requests;
+  #   - positive priorities need all processes that share the lock on RQL versions with priorities
+  #     (older versions drop such lock requests as dead ones: the order is broken, the mutual
+  #     exclusion is not affected); `0` and negative priorities work with older versions too;
+  #   - pre-configured in `config['default_lock_priority']`;
   # @option meta [NilClass,Hash<String|Symbol,Any>]
   #   - A custom metadata wich will be passed to the lock data in addition to the existing data;
   #   - Metadata can not contain reserved lock data keys;
@@ -291,8 +310,8 @@ class RedisQueuedLocks::Client
   #   - Custom instrumenter that will be invoked via #notify method with `event` and `payload` data;
   #   - See RedisQueuedLocks::Instrument::ActiveSupport for examples and implementation details;
   #   - See [Instrumentation](#instrumentation) section of docs;
-  #   - pre-configured in `config['isntrumenter']` with void notifier
-  #     (`RedisQueuedLocks::Instrumenter::VoidNotifier`);
+  #   - pre-configured in `config['instrumenter']` with void notifier
+  #     (`RedisQueuedLocks::Instrument::VoidNotifier`);
   # @option instrument [NilClass,Any]
   #   - Custom instrumentation data wich will be passed to the instrumenter's payload
   #     with :instrument key;
@@ -347,7 +366,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.22.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
@@ -364,6 +383,7 @@ class RedisQueuedLocks::Client
     conflict_strategy: config['default_conflict_strategy'],
     read_write_mode: :write,
     access_strategy: config['default_access_strategy'],
+    priority: config['default_lock_priority'],
     identity: uniq_identity,
     meta: nil,
     detailed_acq_timeout_error: config['detailed_acq_timeout_error'],
@@ -404,6 +424,8 @@ class RedisQueuedLocks::Client
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
+      lock_priorities: config['lock_priorities'],
       meta:,
       detailed_acq_timeout_error:,
       logger:,
@@ -423,10 +445,10 @@ class RedisQueuedLocks::Client
   # rubocop:enable Metrics/MethodLength
 
   # NOTE: Lock Series PoC
-  # rubocop:disable all
+  # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.16.0
-  # @version 1.21.0
+  # @version 1.22.0
   def lock_series( # steep:ignore
     *lock_names,
     detailed_result: false,
@@ -443,6 +465,7 @@ class RedisQueuedLocks::Client
     conflict_strategy: config['default_conflict_strategy'],
     read_write_mode: :write,
     access_strategy: config['default_access_strategy'],
+    priority: config['default_lock_priority'],
     identity: uniq_identity,
     meta: nil,
     detailed_acq_timeout_error: config['detailed_acq_timeout_error'],
@@ -484,6 +507,8 @@ class RedisQueuedLocks::Client
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
+      lock_priorities: config['lock_priorities'],
       meta:,
       detailed_acq_timeout_error:,
       logger:,
@@ -500,13 +525,13 @@ class RedisQueuedLocks::Client
       &block
     )
   end
-  # rubocop:enable all
+  # rubocop:enable Metrics/MethodLength
 
   # NOTE: Lock Series PoC
-  # rubocop:disable all
+  # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.16.0
-  # @version 1.21.0
+  # @version 1.22.0
   def lock_series!( # steep:ignore
     *lock_names,
     detailed_result: false,
@@ -522,6 +547,7 @@ class RedisQueuedLocks::Client
     conflict_strategy: config['default_conflict_strategy'],
     read_write_mode: :write,
     access_strategy: config['default_access_strategy'],
+    priority: config['default_lock_priority'],
     identity: uniq_identity,
     meta: nil,
     detailed_acq_timeout_error: config['detailed_acq_timeout_error'],
@@ -555,6 +581,7 @@ class RedisQueuedLocks::Client
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
       identity:,
       meta:,
       detailed_acq_timeout_error:,
@@ -573,12 +600,14 @@ class RedisQueuedLocks::Client
       &block
     )
   end
+  # rubocop:enable Metrics/MethodLength
 
   # @note See #lock method signature.
   #
+  # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.22.0
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'],
@@ -593,6 +622,7 @@ class RedisQueuedLocks::Client
     conflict_strategy: config['default_conflict_strategy'],
     read_write_mode: :write,
     access_strategy: config['default_access_strategy'],
+    priority: config['default_lock_priority'],
     identity: uniq_identity,
     instrumenter: config['instrumenter'],
     meta: nil,
@@ -632,6 +662,7 @@ class RedisQueuedLocks::Client
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
@@ -714,13 +745,15 @@ class RedisQueuedLocks::Client
   #
   # @param lock_name [String] The lock name whose read lock should be released.
   # @option acquirer_id [String,NilClass]
-  #   - The acquirer whose read lock should be released (`nil` by default);
-  #   - `nil` => the current acquirer is used (calculated from `identity:`, see `#current_acquirer_id`);
-  #   - can be extracted from the lock data (`#lock_info`, `#locks_info`, `#queue_info`, `#queues_info`);
+  #   - the acquirer whose read lock should be released (`nil` by default);
+  #   - `nil` => the current acquirer is used (calculated from `identity:`,
+  #     see `#current_acquirer_id`);
+  #   - can be extracted from the lock data (`#lock_info`, `#locks_info`, `#queue_info`,
+  #     `#queues_info`);
   # @option identity [String]
   #   Unique acquirer identity (the same as for `#lock`) that is used to calculate the current
-  #   acquirer id (see `#current_acquirer_id`). Ignored when `acquirer_id:` is passed: the acquirer id
-  #   already contains its own identity.
+  #   acquirer id (see `#current_acquirer_id`). Ignored when `acquirer_id:` is passed: the
+  #   acquirer id already contains its own identity.
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
@@ -826,7 +859,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.22.0
   def queue_info(lock_name)
     RedisQueuedLocks::Acquirer::QueueInfo.queue_info(redis_client, lock_name)
   end
@@ -1260,7 +1293,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.22.0
   def queues(scan_size: config['key_extraction_batch_size'], with_info: false)
     RedisQueuedLocks::Acquirer::Queues.queues(
       redis_client, scan_size:, with_info:, lock_index_enabled: config['lock_index_enabled']
@@ -1274,7 +1307,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.22.0
   def queues_info(scan_size: config['key_extraction_batch_size'])
     queues(scan_size:, with_info: true) #: RedisQueuedLocks::Acquirer::Queues::queuesInfo
   end
@@ -1302,6 +1335,13 @@ class RedisQueuedLocks::Client
   #   - the batch of scanned keys for Redis'es SCAN command (or the number of locks in one batch of
   #     the lock index ZSCAN pass: the enabled `config['lock_index_enabled']`);
   #   - `config['lock_release_batch_size']` is used by default;
+  # @option by_priority [Boolean]
+  #   - read only the first lock request of each priority in the lock queues instead of all lock
+  #     requests (the dead requests of a priority are found by its first lock request): the
+  #     transfer does not depend on the length of the lock queues, a batch of lock queues takes
+  #     one round trip per priority of its lock queue with the most priorities + 1 (instead of two
+  #     round trips): for long lock queues with few priorities;
+  #   - `false` by default (all lock requests are read);
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
@@ -1318,10 +1358,11 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.22.0
   def clear_dead_requests(
     dead_ttl: config['dead_request_ttl'],
     scan_size: config['lock_release_batch_size'],
+    by_priority: false,
     logger: config['logger'],
     instrumenter: config['instrumenter'],
     instrument: nil,
@@ -1338,6 +1379,7 @@ class RedisQueuedLocks::Client
       redis_client,
       scan_size,
       dead_ttl,
+      by_priority,
       config['lock_index_enabled'],
       logger,
       instrumenter,
@@ -1354,8 +1396,8 @@ class RedisQueuedLocks::Client
   end
 
   # Adds the lock keys without the lock index entry (keys of older RQL versions, keys created while
-  # the lock index was disabled) to the lock index (`rql:index:locks`). Invoke it once after the lock
-  # index is enabled (`config['lock_index_enabled']`) on all your processes: lock-iterating
+  # the lock index was disabled) to the lock index (`rql:index:locks`). Invoke it once after the
+  # lock index is enabled (`config['lock_index_enabled']`) on all your processes: lock-iterating
   # operations (the swarm, `#locks`, `#queues`, `#keys`, `#clear_locks`, ...) find locks via
   # the lock index only.
   #   - works regardless of `config['lock_index_enabled']` (the lock index is not used and not

data/lib/redis_queued_locks/config.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.13.0
+# @version 1.22.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Config
   require_relative 'config/dsl'
@@ -31,6 +32,8 @@ class RedisQueuedLocks::Config
   setting('is_timed_by_default', false)
   setting('default_conflict_strategy', :wait_for_lock)
   setting('default_access_strategy', :queued)
+  setting('lock_priorities', { lowest: -100, low: -50, normal: 0, high: 50, highest: 100 }.freeze)
+  setting('default_lock_priority', 0)
   setting('log_sampling_enabled', false)
   setting('log_sampling_percent', 15)
   setting('log_sampler', RedisQueuedLocks::Logging::Sampler)
@@ -114,6 +117,27 @@ class RedisQueuedLocks::Config
     val == :random
     # rubocop:enable Layout/MultilineOperationIndentation
   end
+  validate('lock_priorities') do |val|
+    val.is_a?(Hash) && val.all? do |name, priority|
+      # rubocop:disable Layout/MultilineOperationIndentation
+      name.is_a?(Symbol) &&
+      priority.is_a?(Integer) &&
+      priority >= RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY &&
+      priority <= RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY
+      # rubocop:enable Layout/MultilineOperationIndentation
+    end
+  end
+  # NOTE: a Symbol is a priority name of `config['lock_priorities']`: a validator gets one value,
+  #   so the name is checked by the configuration itself (`prevent_default_priority__unknown_name`:
+  #   once after a configuration block, the keys can be assigned in any order; before a direct
+  #   assignment is applied);
+  validate('default_lock_priority') do |val|
+    val.is_a?(Symbol) || (
+      val.is_a?(Integer) &&
+      val >= RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY &&
+      val <= RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY
+    )
+  end
 
   # @return [Hash<Symbol,Any>]
   #
@@ -123,10 +147,14 @@ class RedisQueuedLocks::Config
 
   # @return [void]
   #
+  # @raise [RedisQueuedLocks::ConfigValidationError]
+  #
   # @api private
   # @since 1.13.0
+  # @version 1.22.0
   def initialize(&configuration)
     @config_state = {}
+    @configuring = false
     config_setters.each_value { |setter| setter.call(@config_state) }
     configure(&configuration)
   end
@@ -136,10 +164,40 @@ class RedisQueuedLocks::Config
   # @yieldparam [?]
   # @return [void]
   #
+  # @raise [RedisQueuedLocks::ConfigValidationError]
+  #
   # @api private
   # @since 1.13.0
+  # @version 1.22.0
   def configure(&configuration)
-    yield(self) if block_given?
+    return unless block_given?
+
+    # NOTE: (priorities) the keys of the block can be assigned in any order: the priority name of
+    #   `default_lock_priority` is checked against `lock_priorities` once, after the block (after
+    #   the outer block for nested blocks); an inconsistent pair is never applied: both keys keep
+    #   their values from before the block (also when the block fails: its error is raised);
+    lock_priorities = config_state['lock_priorities']
+    default_lock_priority = config_state['default_lock_priority']
+    nested = @configuring
+    completed = false
+    @configuring = true
+    begin
+      yield(self)
+      completed = true
+    ensure
+      @configuring = nested
+      unless nested
+        begin
+          prevent_default_priority__unknown_name(
+            config_state['lock_priorities'], config_state['default_lock_priority']
+          )
+        rescue RedisQueuedLocks::ConfigValidationError
+          config_state['lock_priorities'] = lock_priorities
+          config_state['default_lock_priority'] = default_lock_priority
+          raise if completed
+        end
+      end
+    end
   end
 
   # @param config_key [String]
@@ -163,9 +221,21 @@ class RedisQueuedLocks::Config
   #
   # @api public
   # @since 1.13.0
+  # @version 1.22.0
   def []=(config_key, config_value)
     prevent_key__non_existent(config_key)
     prevent_key__invalid_type(config_key, config_value)
+    # NOTE: (priorities) a direct assignment (out of a configuration block) keeps the priority name
+    #   of `default_lock_priority` a key of `lock_priorities` (a configuration block checks it once
+    #   after the block, see `configure`);
+    unless @configuring
+      case config_key
+      when 'lock_priorities'
+        prevent_default_priority__unknown_name(config_value, config_state['default_lock_priority'])
+      when 'default_lock_priority'
+        prevent_default_priority__unknown_name(config_state['lock_priorities'], config_value)
+      end
+    end
     config_state[config_key] = config_value
   end
 
@@ -236,5 +306,27 @@ class RedisQueuedLocks::Config
       )
     end
   end
+
+  # A priority name of the default lock request priority should be a priority name of
+  # `lock_priorities` (an unknown name would fail each lock acquirement with the default priority).
+  #
+  # @param lock_priorities [Hash<Symbol,Integer>] The priority names.
+  # @param default_lock_priority [Integer,Symbol] The default lock request priority.
+  # @return [void]
+  #
+  # @raise [RedisQueuedLocks::ConfigValidationError]
+  #
+  # @api private
+  # @since 1.22.0
+  def prevent_default_priority__unknown_name(lock_priorities, default_lock_priority)
+    if default_lock_priority.is_a?(Symbol) && !lock_priorities.key?(default_lock_priority)
+      raise(
+        RedisQueuedLocks::ConfigValidationError,
+        "The priority name #{default_lock_priority.inspect} of the 'default_lock_priority' " \
+        "config key is not a key of the 'lock_priorities' config key " \
+        "(#{lock_priorities.keys.map(&:inspect).join(', ')})."
+      )
+    end
+  end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/resource.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.20.0
+# @version 1.22.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Resource
   # @return [String]
@@ -90,6 +90,44 @@ module RedisQueuedLocks::Resource
   # @since 1.3.0
   REDIS_TIMESHIFT_ERROR = 2
 
+  # The lowest lock request priority (the `priority` option of `#lock`).
+  #
+  # @return [Integer]
+  #
+  # @api private
+  # @since 1.22.0
+  MIN_LOCK_PRIORITY = -100
+
+  # The highest lock request priority (the `priority` option of `#lock`).
+  #
+  # @return [Integer]
+  #
+  # @api private
+  # @since 1.22.0
+  MAX_LOCK_PRIORITY = 100
+
+  # Lock request priority band: the position of the lock request in the lock request queue (the
+  # score) is the enqueue time (epoch, seconds) shifted by `priority * LOCK_PRIORITY_BAND` down:
+  #   - each priority gets its own range of positions (the band): requests of the higher priority
+  #     are always ahead of the requests of the lower priority, requests of the same priority are
+  #     ordered by the enqueue time (FIFO);
+  #   - 2**32 seconds (~136 years) is greater than any enqueue time (epoch) up to the year 2106,
+  #     so the bands never overlap and the priority is decoded from the position unambiguously;
+  #   - the default priority (`0`) keeps the position equal to the enqueue time (the positions of
+  #     the RQL versions without priorities);
+  #   - the band of the priority `p` is `(-p * LOCK_PRIORITY_BAND, (1 - p) * LOCK_PRIORITY_BAND)`;
+  #   - the enqueue time is decoded from the position of any priority, so dead lock requests of any
+  #     band are recognized by the position (the time barrier of the band, see
+  #     `lock_priority_band_dead_score`) without the knowledge of the priority range;
+  #   - the precision of the positions (the FIFO precision inside a priority) depends on the
+  #     shift: ~1 µs for -1..1, ~61 µs for -100..100 (`MIN_LOCK_PRIORITY`..`MAX_LOCK_PRIORITY`):
+  #     requests of the same priority made within this interval are ordered by acquirer ids;
+  # @return [Integer] In seconds.
+  #
+  # @api private
+  # @since 1.22.0
+  LOCK_PRIORITY_BAND = 4_294_967_296
+
   # rubocop:disable Metrics/ClassLength
   class << self
     # Returns 16-byte unique identifier. It is used for uniquely
@@ -276,6 +314,22 @@ module RedisQueuedLocks::Resource
       ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
     end
 
+    # Is the lock name of the lock index expired (all the keys of the lock are expired)?
+    #
+    # NOTE: the lock index replies of ZSCAN have String scores: `+inf` (a key without TTL indexed
+    #   by `ReindexLocks`) is `"inf"`, and `String#to_f` turns it into `0.0` (the name would be
+    #   skipped as an expired one by every lock index lookup): it never expires;
+    #
+    # @param lock_index_score [String] The score of the lock name (a ZSCAN reply).
+    # @param lock_index_time [Integer] The current client time (see `lock_index_time`).
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 1.22.0
+    def lock_index_score_expired?(lock_index_score, lock_index_time)
+      lock_index_score != 'inf' && lock_index_score.to_f < lock_index_time
+    end
+
     # @param lock_readers_key [String]
     # @return [String]
     #
@@ -327,16 +381,23 @@ module RedisQueuedLocks::Resource
       (Integer(redis_time[0]) * 1_000) + (Integer(redis_time[1]) / 1_000)
     end
 
-    # @return [Float] Redis's <Set> score that is calculated from the time (epoch) as a float.
+    # @param priority [Integer]
+    #   The lock request priority (from `MIN_LOCK_PRIORITY` to `MAX_LOCK_PRIORITY`).
+    # @return [Float]
+    #   Redis's <Set> score: the time (epoch, as a float) shifted by the priority band (see
+    #   `LOCK_PRIORITY_BAND`; the default priority `0` keeps the time).
     #
     # @api private
     # @since 1.0.0
-    def calc_initial_acquirer_position
-      Time.now.to_f
+    # @version 1.22.0
+    def calc_initial_acquirer_position(priority)
+      Time.now.to_f - (priority * LOCK_PRIORITY_BAND)
     end
 
     # @param queue_ttl [Numeric] In seconds
-    # @return [Float] Redis's <Set> score barrier for acquirers that should be removed from queue.
+    # @return [Float]
+    #   Redis's <Set> score barrier for acquirers that should be removed from queue (the time
+    #   barrier: the barrier of the default priority band, see `lock_priority_band_dead_score`).
     #
     # @api private
     # @since 1.0.0
@@ -344,6 +405,57 @@ module RedisQueuedLocks::Resource
       Time.now.to_f - queue_ttl
     end
 
+    # The lowest position (score) of the lock requests of the given priority band (see
+    # `LOCK_PRIORITY_BAND`): the lower bound of the dead lock request removal (`ZREMRANGEBYSCORE`).
+    #
+    # @param priority [Integer] Any priority (the bands of all priorities have the same layout).
+    # @return [Integer]
+    #   The lower edge of the band (the positions of the band never reach its edges: an enqueue
+    #   time is always greater than 0 and less than `LOCK_PRIORITY_BAND`).
+    #
+    # @api private
+    # @since 1.22.0
+    def lock_priority_band_floor(priority)
+      -priority * LOCK_PRIORITY_BAND
+    end
+
+    # Requests of the given priority band queued at this position or earlier are dead (the upper
+    # bound of the dead lock request removal, see `LOCK_PRIORITY_BAND`).
+    #
+    # @param dead_score [Float] The time barrier (see `acquirer_dead_score`).
+    # @param priority [Integer]
+    # @return [Float]
+    #
+    # @api private
+    # @since 1.22.0
+    def lock_priority_band_dead_score(dead_score, priority)
+      dead_score - (priority * LOCK_PRIORITY_BAND)
+    end
+
+    # Priority of the lock request by its position in the lock request queue (the score).
+    #
+    # NOTE: (infinite positions) RQL never writes infinite positions (manual writes of the lock
+    #   request queues): they are out of all bands and are decoded to the bounds of the priority
+    #   range (the floor of an infinite Float raises `FloatDomainError`):
+    #   - `-inf`: `MAX_LOCK_PRIORITY` (ahead of all lock requests; such a request is dead: its
+    #     enqueue time is unknown, it is dropped like before priorities);
+    #   - `+inf`: `MIN_LOCK_PRIORITY` (behind all lock requests; never dead);
+    #
+    # @param acquirer_position [Numeric] The position (the score) of the lock request.
+    # @return [Integer] See `LOCK_PRIORITY_BAND`.
+    #
+    # @api private
+    # @since 1.22.0
+    def lock_request_priority(acquirer_position)
+      if acquirer_position == -Float::INFINITY
+        MAX_LOCK_PRIORITY
+      elsif acquirer_position == Float::INFINITY
+        MIN_LOCK_PRIORITY
+      else
+        -(acquirer_position / LOCK_PRIORITY_BAND).floor
+      end
+    end
+
     # @param zombie_ttl [Float] In seconds with milliseconds.
     # @return [Float]
     #
@@ -354,8 +466,10 @@ module RedisQueuedLocks::Resource
     end
 
     # @param acquirer_position [Float]
-    #   A time (epoch, seconds.milliseconds) that represents
-    #   the acquirer position in lock request queue.
+    #   A time (epoch, seconds.milliseconds) shifted by the priority band that represents
+    #   the acquirer position in lock request queue (see `calc_initial_acquirer_position`).
+    # @param priority [Integer]
+    #   The lock request priority (the band of the position).
     # @param queue_ttl [Integer]
     #   In second.
     # @return [Boolean]
@@ -363,8 +477,9 @@ module RedisQueuedLocks::Resource
     #
     # @api private
     # @since 1.0.0
-    def dead_score_reached?(acquirer_position, queue_ttl)
-      (acquirer_position + queue_ttl) < Time.now.to_f
+    # @version 1.22.0
+    def dead_score_reached?(acquirer_position, priority, queue_ttl)
+      (acquirer_position + (priority * LOCK_PRIORITY_BAND) + queue_ttl) < Time.now.to_f
     end
 
     # NOTE: (debug) not used by the library: a manual runtime check (in a console) of the lock that

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

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.9.0
-# @version 1.17.0
+# @version 1.21.1
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   # @since 1.9.0
@@ -70,7 +70,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
     return unless enabled?
 
     sync.synchronize do
-      swarm_element__termiante
+      swarm_element__terminate
       swarm!
       swarm_loop__start
     end
@@ -99,7 +99,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   # @since 1.9.0
   def try_kill!
     sync.synchronize do
-      swarm_element__termiante
+      swarm_element__terminate
     end
   end
 
@@ -157,7 +157,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   # => 1) init (swarm!): create a thread, main loop is not started;
   # => 2) start (swarm_loop__start): run the main loop inside the created thread;
   # => 3) stop (swarm_loop__stop): stop the main loop inside the created thread;
-  # => 4) terminate (swarm_element__termiante): kill the created thread;
+  # => 4) terminate (swarm_element__terminate): kill the created thread;
   # In addition you should implement `#spawn_main_loop!` method that will be the main logic
   # of the your swarm element.
   #
@@ -341,7 +341,8 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   #
   # @api private
   # @since 1.9.0
-  def swarm_element__termiante
+  # @version 1.21.1
+  def swarm_element__terminate
     return if idle? || swarmed__dead?
     sync.synchronize do
       main_loop&.kill

data/lib/redis_queued_locks/swarm/zombie_info.rb

@@ -232,7 +232,8 @@ module RedisQueuedLocks::Swarm::ZombieInfo
     # names, the full keyspace is never scanned): write locks and readers registries are processed
     # in batches of `lock_scan_size` locks with one round trip per batch and per key family
     # (batches are collected across ZSCAN pages). Expired lock names of the index are skipped
-    # (all their keys are expired).
+    # (all their keys are expired; `+inf` names, keys without TTL, never expire: see
+    # `RedisQueuedLocks::Resource.lock_index_score_expired?`).
     #
     # @param rconn [RedisClient] redis connection obtained via `#with` from RedisClient instance;
     # @param zombie_hosts [Set<String>]
@@ -244,6 +245,7 @@ module RedisQueuedLocks::Swarm::ZombieInfo
     #
     # @api private
     # @since 1.20.0
+    # @version 1.22.0
     def each_lock_index_zombie_lock(rconn, zombie_hosts, lock_scan_size, &block)
       # @type var lock_keys: Array[String]
       lock_keys = []
@@ -255,7 +257,9 @@ module RedisQueuedLocks::Swarm::ZombieInfo
         RedisQueuedLocks::Resource::LOCK_INDEX_KEY, count: lock_scan_size
       ) do |lock_name, lock_index_score|
         # NOTE: the expired lock name (not dropped from the index yet): its keys are expired
-        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_keys << RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
         lock_readers_keys << RedisQueuedLocks::Resource.prepare_lock_readers(lock_name)