redis_queued_locks 1.20.0 → 1.21.0

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.20.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,7 +176,9 @@ 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]
@@ -183,7 +190,8 @@ class RedisQueuedLocks::Client
   #     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]
@@ -294,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;
@@ -315,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>]
@@ -339,7 +347,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
@@ -418,7 +426,7 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
-  # @version 1.20.0
+  # @version 1.21.0
   def lock_series( # steep:ignore
     *lock_names,
     detailed_result: false,
@@ -498,7 +506,7 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
-  # @version 1.20.0
+  # @version 1.21.0
   def lock_series!( # steep:ignore
     *lock_names,
     detailed_result: false,
@@ -570,7 +578,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'],
@@ -665,7 +673,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def unlock(
     lock_name,
     logger: config['logger'],
@@ -684,8 +692,9 @@ class RedisQueuedLocks::Client
       redis_client,
       lock_name,
       config['lock_index_enabled'],
-      instrumenter,
       logger,
+      instrumenter,
+      instrument,
       log_sampling_enabled,
       log_sampling_percent,
       log_sampler,
@@ -742,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,
@@ -763,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,
@@ -902,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
@@ -944,7 +948,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def extend_lock_ttl(
     lock_name,
     milliseconds,
@@ -1008,7 +1012,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def clear_locks(
     batch_size: config['lock_release_batch_size'],
     logger: config['logger'],
@@ -1097,12 +1101,12 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.14.0
-  # @version 1.20.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,
@@ -1140,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]
@@ -1159,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,
@@ -1216,7 +1222,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.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:, lock_index_enabled: config['lock_index_enabled']
@@ -1230,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]
@@ -1253,7 +1260,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.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:, lock_index_enabled: config['lock_index_enabled']
@@ -1267,8 +1274,9 @@ 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]
@@ -1279,7 +1287,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def keys(scan_size: config['key_extraction_batch_size'])
     RedisQueuedLocks::Acquirer::Keys.keys(
       redis_client, scan_size:, lock_index_enabled: config['lock_index_enabled']
@@ -1310,7 +1318,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.20.0
+  # @version 1.21.0
   def clear_dead_requests(
     dead_ttl: config['dead_request_ttl'],
     scan_size: config['lock_release_batch_size'],
@@ -1365,21 +1373,55 @@ class RedisQueuedLocks::Client
   # @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']
+    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
+      lock_index_grace_period,
+      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
 end

data/lib/redis_queued_locks/config.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.13.0
-# @version 1.20.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Config
   require_relative 'config/dsl'
@@ -57,36 +56,36 @@ 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) }

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

data/lib/redis_queued_locks/instrument/sampler.rb

@@ -3,12 +3,6 @@
 # @api public
 # @since 1.6.0
 module RedisQueuedLocks::Instrument::Sampler
-  # @return [Range]
-  #
-  # @api private
-  # @since 1.6.0
-  SAMPLING_PERCENT_RANGE = (0..100)
-
   class << self
     # Super simple probalistic function based on the `weight` of <true>/<false> values.
     # Requires the <percent> parameter as the required percent of <true> values sampled.
@@ -20,8 +14,11 @@ module RedisQueuedLocks::Instrument::Sampler
     #
     # @api public
     # @since 1.6.0
+    # @version 1.21.0
     def sampling_happened?(sampling_percent)
-      sampling_percent >= SecureRandom.rand(SAMPLING_PERCENT_RANGE)
+      # NOTE: one of 100 equally probable values (0..99): `sampling_percent` of them are lower
+      #   (0% => never, 100% => always);
+      SecureRandom.rand(100) < sampling_percent
     end
   end
 end

data/lib/redis_queued_locks/logging/sampler.rb

@@ -3,12 +3,6 @@
 # @api public
 # @since 1.5.0
 module RedisQueuedLocks::Logging::Sampler
-  # @return [Range]
-  #
-  # @api private
-  # @since 1.6.0
-  SAMPLING_PERCENT_RANGE = (0..100)
-
   class << self
     # Super simple probalistic function based on the `weight` of <true>/<false> values.
     # Requires the <percent> parameter as the required percent of <true> values sampled.
@@ -20,9 +14,11 @@ module RedisQueuedLocks::Logging::Sampler
     #
     # @api public
     # @since 1.5.0
-    # @version 1.6.0
+    # @version 1.21.0
     def sampling_happened?(sampling_percent)
-      sampling_percent >= SecureRandom.rand(SAMPLING_PERCENT_RANGE)
+      # NOTE: one of 100 equally probable values (0..99): `sampling_percent` of them are lower
+      #   (0% => never, 100% => always);
+      SecureRandom.rand(100) < sampling_percent
     end
   end
 end

data/lib/redis_queued_locks/resource.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.20.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Resource
   # @return [String]
@@ -366,14 +367,23 @@ module RedisQueuedLocks::Resource
       (acquirer_position + queue_ttl) < Time.now.to_f
     end
 
-    # @param lock_queue [String]
-    # @return [String]
+    # NOTE: (debug) not used by the library: a manual runtime check (in a console) of the lock that
+    #   a queue belongs to (e.g. `Resource.lock_key_from_queue(client.queues.first)`);
+    #
+    # @param lock_queue [String] `rql:lock_queue:<name>` or `rql:lock_read_queue:<name>`.
+    # @return [String,NilClass]
+    #   - `rql:lock:<name>` for the write lock request queue and for the read lock request queue;
+    #   - `nil` for any other key;
     #
     # @api private
     # @since 1.0.0
+    # @version 1.21.0
     def lock_key_from_queue(lock_queue)
-      # NOTE: 15 is a start position of the lock name
-      "rql:lock:#{lock_queue[15..]}"
+      key_family = lock_key_family(lock_queue)
+      return unless key_family == :lock_queue || key_family == :read_lock_queue
+
+      lock_name = lock_name_from_key(lock_queue, key_family) #: String
+      prepare_lock_key(lock_name)
     end
 
     # @return [Integer]

data/lib/redis_queued_locks/swarm/flush_zombies.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.9.0
+# @version 1.20.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElement::Isolated
   class << self

data/lib/redis_queued_locks/swarm/redis_client_builder.rb

@@ -7,19 +7,23 @@ module RedisQueuedLocks::Swarm::RedisClientBuilder
     # @option pooled [Boolean]
     # @option sentinel [Boolean]
     # @option config [Hash]
+    # @option pool_config [Hash]
     # @return [RedisClient|RedisClient::Pooled]
     #
     # @api private
     # @since 1.9.0
+    # @version 1.21.0
     # rubocop:disable Style/RedundantAssignment
     def build(pooled: false, sentinel: false, config: {}, pool_config: {})
-      config.transform_keys!(&:to_sym)
-      pool_config.transform_keys!(&:to_sym)
+      # NOTE: the passed hashes are not mutated: they are the values of the client config (they
+      #   can be frozen and are shared with the zombie flusher Ractor when they are shareable);
+      redis_options = config.transform_keys(&:to_sym)
+      pool_options = pool_config.transform_keys(&:to_sym)
 
       redis_config =
-        sentinel ? sentinel_config(config) : non_sentinel_config(config)
+        sentinel ? sentinel_config(redis_options) : non_sentinel_config(redis_options)
       redis_client =
-        pooled ? pooled_client(redis_config, pool_config) : non_pooled_client(redis_config)
+        pooled ? pooled_client(redis_config, pool_options) : non_pooled_client(redis_config)
 
       redis_client
     end

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

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.9.0
+# @version 1.17.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   # @since 1.9.0
@@ -78,7 +79,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   # @return [void]
   #
   # @api private
-  # @since 19.0.0
+  # @since 1.9.0
   def reswarm_if_dead!
     return unless enabled?
 
@@ -154,7 +155,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
 
   # Swarm element lifecycle have the following flow:
   # => 1) init (swarm!): create a thread, main loop is not started;
-  # => 2) start (swarm_loop__start): run the main lopp inside the created thread;
+  # => 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;
   # In addition you should implement `#spawn_main_loop!` method that will be the main logic