redis_queued_locks 1.19.0 → 1.21.0

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.21.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @return [RedisClient]
@@ -79,6 +79,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.9.0
+  # @version 1.21.0
   def swarm_info(zombie_ttl: config['swarm.flush_zombies.zombie_ttl'])
     swarm.swarm_info(zombie_ttl:)
   end
@@ -107,6 +108,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.9.0
+  # @version 1.21.0
   def flush_zombies(
     zombie_ttl: config['swarm.flush_zombies.zombie_ttl'],
     lock_scan_size: config['swarm.flush_zombies.zombie_lock_scan_size'],
@@ -121,6 +123,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.9.0
+  # @version 1.21.0
   def zombie_locks(
     zombie_ttl: config['swarm.flush_zombies.zombie_ttl'],
     lock_scan_size: config['swarm.flush_zombies.zombie_lock_scan_size']
@@ -132,8 +135,9 @@ class RedisQueuedLocks::Client
   # @option lock_scan_size [Integer]
   # @return [Set<String>]
   #
-  # @api ppublic
+  # @api public
   # @since 1.9.0
+  # @version 1.21.0
   def zombie_acquirers(
     zombie_ttl: config['swarm.flush_zombies.zombie_ttl'],
     lock_scan_size: config['swarm.flush_zombies.zombie_lock_scan_size']
@@ -146,6 +150,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.9.0
+  # @version 1.21.0
   def zombie_hosts(zombie_ttl: config['swarm.flush_zombies.zombie_ttl'])
     swarm.zombie_hosts(zombie_ttl:)
   end
@@ -159,7 +164,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.9.0
-  # @version 1.17.0
+  # @version 1.21.0
   def zombies_info(
     zombie_ttl: config['swarm.flush_zombies.zombie_ttl'],
     lock_scan_size: config['swarm.flush_zombies.zombie_lock_scan_size']
@@ -171,11 +176,22 @@ class RedisQueuedLocks::Client
   # @param lock_name [String]
   #   Lock name to be obtained.
   # @option ttl [Integer]
-  #   Lock's time to live (in milliseconds).
+  #   - Lock's time to live (in milliseconds);
+  #   - a positive Integer;
+  #   - pre-configured in `config['default_lock_ttl']`;
   # @option queue_ttl [Integer]
   #   Lifetime of the acuier's lock request. In seconds.
+  # @option lock_index_grace_period [Integer]
+  #   - The lock index score margin over the lock key lifetime (in milliseconds): the lock name
+  #     stays in the lock index (`rql:index:locks`) for this period after the expiration of
+  #     the lock keys;
+  #   - should be greater than the client clock skew between your hosts plus the network latency;
+  #   - used only with the enabled lock index (`config['lock_index_enabled']`, the client-wide
+  #     mode: the lock index is maintained by all lock acquirements of the client);
+  #   - pre-configured in `config['lock_index_grace_period']`;
   # @option timeout [Integer,NilClass]
-  #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout".
+  #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout"
+  #   (`0` is the same as `nil`).
   # @option timed [Boolean]
   #   Limit the invocation time period of the passed block of code by the lock's TTL.
   # @option retry_count [Integer,NilClass]
@@ -286,7 +302,7 @@ class RedisQueuedLocks::Client
   #   - works in tandem with <config['log_sampling_percent'] and <config['log_sampler']>;
   # @option log_sampling_percent [Integer]
   #   - the percent of cases that should be logged;
-  #   - take an effect when <config['log_sampling_enalbed']> is true;
+  #   - take an effect when <config['log_sampling_enabled']> is true;
   #   - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
   # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
   #   - percent-based log sampler that decides should be RQL case logged or not;
@@ -307,7 +323,7 @@ class RedisQueuedLocks::Client
   #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
   # @option instr_sampling_percent [Integer]
   #   - the percent of cases that should be instrumented;
-  #   - take an effect when <config['instr_sampling_enalbed']> is true;
+  #   - take an effect when <config['instr_sampling_enabled']> is true;
   #   - works in tandem with <config['instr_sampling_enabled']>
   #     and <config['instr_sampler']> configs;
   # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
@@ -331,12 +347,13 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.21.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -373,6 +390,8 @@ class RedisQueuedLocks::Client
       ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
       ttl:,
       queue_ttl:,
+      lock_index_enabled: config['lock_index_enabled'],
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -407,11 +426,13 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
+  # @version 1.21.0
   def lock_series( # steep:ignore
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -449,6 +470,8 @@ class RedisQueuedLocks::Client
       ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
       ttl:,
       queue_ttl:,
+      lock_index_enabled: config['lock_index_enabled'],
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -483,11 +506,13 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
+  # @version 1.21.0
   def lock_series!( # steep:ignore
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -519,6 +544,7 @@ class RedisQueuedLocks::Client
       detailed_result:,
       ttl:,
       queue_ttl:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -552,11 +578,12 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.21.0
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -587,6 +614,7 @@ class RedisQueuedLocks::Client
       lock_name,
       ttl:,
       queue_ttl:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -645,7 +673,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.21.0
   def unlock(
     lock_name,
     logger: config['logger'],
@@ -663,8 +691,10 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseLock.release_lock(
       redis_client,
       lock_name,
-      instrumenter,
+      config['lock_index_enabled'],
       logger,
+      instrumenter,
+      instrument,
       log_sampling_enabled,
       log_sampling_percent,
       log_sampler,
@@ -721,7 +751,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.18.0
-  # @version 1.19.0
+  # @version 1.21.0
   def unlock_read(
     lock_name,
     acquirer_id: nil,
@@ -742,8 +772,8 @@ class RedisQueuedLocks::Client
       redis_client,
       lock_name,
       acquirer_id || current_acquirer_id(identity:),
-      instrumenter,
       logger,
+      instrumenter,
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
@@ -881,19 +911,14 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Resource.possible_host_identifiers(identity)
   end
 
-  # This method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension.
-  # So the methid is spliited into the two commands:
-  #   (1) read current pttl
-  #   (2) set new ttl that is calculated as "current pttl + additional milliseconds"
-  # What can happen during these steps
-  # - lock is expired between commands or before the first command;
-  # - lock is expired before the second command;
-  # - lock is expired AND newly acquired by another process (so you will extend the
-  #   totally new lock with fresh PTTL);
+  # The write lock TTL is extended atomically by one Lua script (`PTTL` + `PEXPIRE` with
+  # "current pttl + additional milliseconds") without the lock owner check: when your lock is
+  # expired and newly obtained by another acquirer, the lock of that acquirer is extended.
   # Use it at your own risk and consider async nature when calling this method.
   #
   # @param lock_name [String]
-  # @param milliseconds [Integer] How many milliseconds should be added.
+  # @param milliseconds [Integer]
+  #   How many milliseconds should be added: a positive Integer.
   # @option read_write_mode [Symbol]
   #   - `:write` (default) - extends the write lock (the method description above);
   #   - `:read` - extends the read lock of the current acquirer only (an expired read lock or
@@ -923,7 +948,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.21.0
   def extend_lock_ttl(
     lock_name,
     milliseconds,
@@ -949,6 +974,7 @@ class RedisQueuedLocks::Client
       read_write_mode,
       all_read_locks,
       current_acquirer_id(identity:),
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -967,6 +993,7 @@ class RedisQueuedLocks::Client
   # Returns:
   #   - :rel_time - (milliseconds) - time spent to release all locks and queues;
   #   - :rel_key_cnt - (integer) - the number of released redis keys (queus+locks);
+  # Locks are found via the keyspace SCAN or via the lock index (`config['lock_index_enabled']`).
   #
   # @option batch_size [Integer]
   # @option logger [::Logger,#debug]
@@ -985,7 +1012,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.21.0
   def clear_locks(
     batch_size: config['lock_release_batch_size'],
     logger: config['logger'],
@@ -1003,6 +1030,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -1024,6 +1052,8 @@ class RedisQueuedLocks::Client
   # current puma request thread is killed by Rack::Timeout and you need to cleanup all zombie RQL
   # locks and lock reuqests obtained during the request processing).
   #
+  # Locks are found via the keyspace SCAN or via the lock index (`config['lock_index_enabled']`).
+  #
   # Identifiers can be extracted via:
   #   - `#current_host_id`
   #   - `#current_acquirer_id`
@@ -1071,11 +1101,12 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.14.0
+  # @version 1.21.0
   def clear_locks_of(
     host_id:,
     acquirer_id:,
     lock_scan_size: config['clear_locks_of__lock_scan_size'],
-    queue_scan_size: config['clear_locks_of__queue_scan_size'], # steep:ingore
+    queue_scan_size: config['clear_locks_of__queue_scan_size'],
     logger: config['logger'],
     instrumenter: config['instrumenter'],
     instrument: nil,
@@ -1094,6 +1125,7 @@ class RedisQueuedLocks::Client
       redis_client,
       lock_scan_size,
       queue_scan_size,
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -1112,7 +1144,8 @@ class RedisQueuedLocks::Client
   # Release all locks of the current acquirer/host and
   # remove the current acquirer/host from all queues;
   #
-  # @option batch_size [Integer]
+  # @option lock_scan_size [Integer]
+  # @option queue_scan_size [Integer]
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify] See `config['instrumenter']` docs for details.
   # @option instrument [NilClass,Any]
@@ -1131,9 +1164,10 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.14.0
+  # @version 1.21.0
   def clear_current_locks(
     lock_scan_size: config['clear_locks_of__lock_scan_size'],
-    queue_scan_size: config['clear_locks_of__queue_scan_size'], # steep:ingore
+    queue_scan_size: config['clear_locks_of__queue_scan_size'],
     logger: config['logger'],
     instrumenter: config['instrumenter'],
     instrument: nil,
@@ -1183,10 +1217,16 @@ class RedisQueuedLocks::Client
   #     at the moment of Redis'es SCAN;
   # @return [Set<String>,Set<Hash<Symbol,Any>>]
   #
+  # NOTE: locks are found via the keyspace SCAN or via the lock index (ZSCAN, the enabled
+  #   `config['lock_index_enabled']`: `scan_size` is the number of locks in one batch);
+  #
   # @api public
   # @since 1.0.0
+  # @version 1.21.0
   def locks(scan_size: config['key_extraction_batch_size'], with_info: false)
-    RedisQueuedLocks::Acquirer::Locks.locks(redis_client, scan_size:, with_info:)
+    RedisQueuedLocks::Acquirer::Locks.locks(
+      redis_client, scan_size:, with_info:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # Extracts lock keys with their info. See #locks(with_info: true) for details.
@@ -1196,8 +1236,9 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  def locks_info(scan_size: config['key_extraction_batch_size']) # steep:ignore
-    locks(scan_size:, with_info: true)
+  # @version 1.21.0
+  def locks_info(scan_size: config['key_extraction_batch_size'])
+    locks(scan_size:, with_info: true) #: RedisQueuedLocks::Acquirer::Locks::locksInfo
   end
 
   # @option scan_size [Integer]
@@ -1214,10 +1255,16 @@ class RedisQueuedLocks::Client
   #     at the moment of Redis'es SCAN;
   # @return [Set<String>,String<Hash<Symbol,Any>>]
   #
+  # NOTE: lock queues are found via the keyspace SCAN or via the lock index (ZSCAN, the enabled
+  #   `config['lock_index_enabled']`: `scan_size` is the number of locks in one batch);
+  #
   # @api public
   # @since 1.0.0
+  # @version 1.21.0
   def queues(scan_size: config['key_extraction_batch_size'], with_info: false)
-    RedisQueuedLocks::Acquirer::Queues.queues(redis_client, scan_size:, with_info:)
+    RedisQueuedLocks::Acquirer::Queues.queues(
+      redis_client, scan_size:, with_info:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # Extracts lock queues with their info. See #queues(with_info: true) for details.
@@ -1227,17 +1274,24 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
+  # @version 1.21.0
   def queues_info(scan_size: config['key_extraction_batch_size'])
-    queues(scan_size:, with_info: true)
+    queues(scan_size:, with_info: true) #: RedisQueuedLocks::Acquirer::Queues::queuesInfo
   end
 
   # @option scan_size [Integer]
   # @return [Set<String>]
+  #   - the disabled lock index: all the RQL keys (`rql:lock*`) found via the keyspace SCAN;
+  #   - the enabled lock index (`config['lock_index_enabled']`): the existing keys of the locks of
+  #     the lock index (ZSCAN, `scan_size` is the number of locks in one batch);
   #
   # @api public
   # @since 1.0.0
+  # @version 1.21.0
   def keys(scan_size: config['key_extraction_batch_size'])
-    RedisQueuedLocks::Acquirer::Keys.keys(redis_client, scan_size:)
+    RedisQueuedLocks::Acquirer::Keys.keys(
+      redis_client, scan_size:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # @option dead_ttl [Integer]
@@ -1245,7 +1299,8 @@ class RedisQueuedLocks::Client
   #     considered as dead;
   #   - `config['dead_request_ttl']` is used by default;
   # @option scan_size [Integer]
-  #   - the batch of scanned keys for Redis'es SCAN command;
+  #   - 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 logger [::Logger,#debug]
   # @option instrumenter [#notify]
@@ -1263,7 +1318,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.21.0
   def clear_dead_requests(
     dead_ttl: config['dead_request_ttl'],
     scan_size: config['lock_release_batch_size'],
@@ -1283,6 +1338,79 @@ class RedisQueuedLocks::Client
       redis_client,
       scan_size,
       dead_ttl,
+      config['lock_index_enabled'],
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      log_sample_this,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler,
+      instr_sample_this
+    )
+  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
+  # 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
+  #     maintained while it is disabled);
+  #   - one SCAN pass over the RQL keys;
+  #   - lock queues without TTL (older RQL versions) get `queue_ttl` as their TTL;
+  #   - idempotent: the lock index scores are never decreased, already indexed keys stay as is;
+  #
+  # @option scan_size [Integer]
+  #   - the batch of scanned keys for Redis'es SCAN command;
+  #   - `config['lock_release_batch_size']` is used by default;
+  # @option queue_ttl [Integer]
+  #   - TTL of the lock queues without TTL (in seconds);
+  #   - `config['default_queue_ttl']` is used by default;
+  # @option lock_index_grace_period [Integer]
+  #   - the lock index score margin over the key lifetime (in milliseconds);
+  #   - `config['lock_index_grace_period']` is used by default;
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
+  # @option log_sampling_enabled [Boolean]
+  # @option log_sampling_percent [Integer]
+  # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+  # @option log_sample_this [Boolean]
+  # @option instr_sampling_enabled [Boolean]
+  # @option instr_sampling_percent [Integer]
+  # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+  # @option instr_sample_this [Boolean]
+  # @return [Hash<Symbol,Boolean|Hash<Symbol,Integer>>]
+  #   Format: { ok: true, result: { idx_key_cnt: Integer } } (the number of indexed keys)
+  #
+  # @api public
+  # @since 1.20.0
+  # @version 1.21.0
+  def reindex_locks(
+    scan_size: config['lock_release_batch_size'],
+    queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
+    logger: config['logger'],
+    instrumenter: config['instrumenter'],
+    instrument: nil,
+    log_sampling_enabled: config['log_sampling_enabled'],
+    log_sampling_percent: config['log_sampling_percent'],
+    log_sampler: config['log_sampler'],
+    log_sample_this: false,
+    instr_sampling_enabled: config['instr_sampling_enabled'],
+    instr_sampling_percent: config['instr_sampling_percent'],
+    instr_sampler: config['instr_sampler'],
+    instr_sample_this: false
+  )
+    RedisQueuedLocks::Acquirer::ReindexLocks.reindex_locks(
+      redis_client,
+      scan_size,
+      queue_ttl,
+      lock_index_grace_period,
       logger,
       instrumenter,
       instrument,

data/lib/redis_queued_locks/config.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.13.0
-# @version 1.15.1
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Config
   require_relative 'config/dsl'
@@ -27,6 +26,8 @@ class RedisQueuedLocks::Config
   setting('logger', RedisQueuedLocks::Logging::VoidLogger)
   setting('log_lock_try', false)
   setting('dead_request_ttl', 1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds)
+  setting('lock_index_enabled', false)
+  setting('lock_index_grace_period', 60_000) # NOTE: in milliseconds)
   setting('is_timed_by_default', false)
   setting('default_conflict_strategy', :wait_for_lock)
   setting('default_access_strategy', :queued)
@@ -55,41 +56,43 @@ class RedisQueuedLocks::Config
   setting('swarm.flush_zombies.redis_config.pool_config', {})
 
   validate('swarm.auto_swarm') { |val| val == true || val == false }
-  validate('swarm.supervisor.liveness_probing_period') { |val| val.is_a?(Integer) }
+  validate('swarm.supervisor.liveness_probing_period') { |val| val.is_a?(Integer) && val > 0 }
 
   validate('swarm.probe_hosts.enabled_for_swarm') { |val| val == true || val == false }
   validate('swarm.probe_hosts.redis_config.sentinel') { |val| val == true || val == false }
   validate('swarm.probe_hosts.redis_config.pooled') { |val| val == true || val == false }
   validate('swarm.probe_hosts.redis_config.config') { |val| val.is_a?(Hash) }
   validate('swarm.probe_hosts.redis_config.pool_config') { |val| val.is_a?(Hash) }
-  validate('swarm.probe_hosts.probe_period') { |val| val.is_a?(Integer) }
+  validate('swarm.probe_hosts.probe_period') { |val| val.is_a?(Integer) && val > 0 }
 
   validate('swarm.flush_zombies.enabled_for_swarm') { |val| val == true || val == false }
   validate('swarm.flush_zombies.redis_config.sentinel') { |val| val == true || val == false }
   validate('swarm.flush_zombies.redis_config.pooled') { |val| val == true || val == false }
   validate('swarm.flush_zombies.redis_config.config') { |val| val.is_a?(Hash) }
   validate('swarm.flush_zombies.redis_config.pool_config') { |val| val.is_a?(Hash) }
-  validate('swarm.flush_zombies.zombie_ttl') { |val| val.is_a?(Integer) }
-  validate('swarm.flush_zombies.zombie_lock_scan_size') { |val| val.is_a?(Integer) }
-  validate('swarm.flush_zombies.zombie_queue_scan_size') { |val| val.is_a?(Integer) }
-  validate('swarm.flush_zombies.zombie_flush_period') { |val| val.is_a?(Integer) }
+  validate('swarm.flush_zombies.zombie_ttl') { |val| val.is_a?(Integer) && val > 0 }
+  validate('swarm.flush_zombies.zombie_lock_scan_size') { |val| val.is_a?(Integer) && val > 0 }
+  validate('swarm.flush_zombies.zombie_queue_scan_size') { |val| val.is_a?(Integer) && val > 0 }
+  validate('swarm.flush_zombies.zombie_flush_period') { |val| val.is_a?(Integer) && val > 0 }
 
   validate('retry_count') { |val| val == nil || (val.is_a?(Integer) && val >= 0) }
   validate('retry_delay') { |val| val.is_a?(Integer) && val >= 0 }
   validate('retry_jitter') { |val| val.is_a?(Integer) && val >= 0 }
   validate('try_to_lock_timeout') { |val| val == nil || (val.is_a?(Integer) && val >= 0) }
-  validate('default_lock_ttl') { |val| val.is_a?(Integer) }
-  validate('default_queue_ttl') { |val| val.is_a?(Integer) }
+  validate('default_lock_ttl') { |val| val.is_a?(Integer) && val > 0 }
+  validate('default_queue_ttl') { |val| val.is_a?(Integer) && val > 0 }
   validate('detailed_acq_timeout_error') { |val| val == true || val == false }
-  validate('lock_release_batch_size') { |val| val.is_a?(Integer) }
-  validate('clear_locks_of__lock_scan_size') { |val| val.is_a?(Integer) }
-  validate('clear_locks_of__queue_scan_size') { |val| val.is_a?(Integer) }
-  validate('key_extraction_batch_size') { |val| val.is_a?(Integer) }
+  validate('lock_release_batch_size') { |val| val.is_a?(Integer) && val > 0 }
+  validate('clear_locks_of__lock_scan_size') { |val| val.is_a?(Integer) && val > 0 }
+  validate('clear_locks_of__queue_scan_size') { |val| val.is_a?(Integer) && val > 0 }
+  validate('key_extraction_batch_size') { |val| val.is_a?(Integer) && val > 0 }
   validate('instrumenter') { |val| RedisQueuedLocks::Instrument.valid_interface?(val) }
   validate('uniq_identifier') { |val| val.is_a?(Proc) }
   validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
   validate('log_lock_try') { |val| val == true || val == false }
   validate('dead_request_ttl') { |val| val.is_a?(Integer) && val > 0 }
+  validate('lock_index_enabled') { |val| val == true || val == false }
+  validate('lock_index_grace_period') { |val| val.is_a?(Integer) && val >= 0 }
   validate('is_timed_by_default') { |val| val == true || val == false }
   validate('log_sampler') { |val| RedisQueuedLocks::Logging.valid_sampler?(val) }
   validate('log_sampling_enabled') { |val| val == true || val == false }

data/lib/redis_queued_locks/errors.rb

@@ -4,6 +4,12 @@
 #   the one-line definition style (like "Error = Class.new(::StandardError)")
 #   is not used cuz that style can not be correctly defined via RBS types: we can not
 #   identify the superclass of our class for a constant;
+# NOTE: (error hierarchy) each error inherits from the global base error of its branch:
+#   - `Error` (`::StandardError`) - the main hierarchy;
+#   - `ArgumentError` (`::ArgumentError`) - invalid arguments (the Ruby core branch that can not be
+#     a part of the main hierarchy);
+#   - `Exception` (`::Exception`) - super exceptional cases only: each error of this branch
+#     describes why it is not a `StandardError`;
 module RedisQueuedLocks
   # @api public
   # @since 1.0.0
@@ -13,13 +19,29 @@ module RedisQueuedLocks
   # @since 1.0.0
   class ArgumentError < ::ArgumentError; end
 
+  # The base of the errors that should not be rescued by the code they interrupt
+  # (`rescue => e`, `rescue StandardError`, `rescue nil`): like `Timeout::ExitException`,
+  # they are rescued only by `rescue Exception` (and by the library itself).
+  # NOTE: inside `module RedisQueuedLocks` a bare `Exception` refers to this class;
+  #
+  # @api private
+  # @since 1.21.0
+  class Exception < ::Exception; end # rubocop:disable Lint/InheritException
+
   # @api public
   # @since 1.0.0
   class LockAlreadyObtainedError < Error; end
 
+  # Interrupts the lock acquirement after the `timeout` (`Timeout.timeout`); rescued by
+  # `WithAcqTimeout` (=> `LockAcquirementTimeoutError` / `:timeout_reached`).
+  # NOTE: (why `Exception`) the acquirement calls the logger and the instrumenter: a `StandardError`
+  #   that interrupts them is swallowed by `rescue nil` of the log/instrumentation events, and the
+  #   acquirement continues without the timeout (with `retry_count: nil` - without any limit);
+  #
   # @api private
   # @since 1.11.0
-  class LockAcquirementIntermediateTimeoutError < ::Timeout::Error; end
+  # @version 1.21.0
+  class LockAcquirementIntermediateTimeoutError < Exception; end
 
   # @api public
   # @since 1.0.0
@@ -29,11 +51,19 @@ module RedisQueuedLocks
   # @since 1.0.0
   class LockAcquirementRetryLimitError < Error; end
 
+  # Interrupts the `timed: true` block after the lock ttl (`Timeout.timeout`); rescued by
+  # `YieldExpire` (=> `TimedLockTimeoutError`).
+  # NOTE: (why `Exception`) a `StandardError` is swallowed by `rescue => e` / `rescue nil` of
+  #   the user block: the block continues after the lock ttl (without the mutual exclusion:
+  #   another acquirer can obtain the expired lock, and the write lock release after the block
+  #   deletes its lock);
+  #
   # @api private
   # @since 1.12.0
-  class TimedLockIntermediateTimeoutError < ::Timeout::Error; end
+  # @version 1.21.0
+  class TimedLockIntermediateTimeoutError < Exception; end
 
-  # @api pulic
+  # @api public
   # @since 1.0.0
   class TimedLockTimeoutError < Error; end
 
@@ -57,7 +87,7 @@ module RedisQueuedLocks
   # @since 1.13.0
   class ConfigNotFoundError < ConfigError; end
 
-  # @api pub;ic
+  # @api public
   # @since 1.13.0
   class ConfigValidationError < ConfigError; end
 end