redis_queued_locks 1.20.0 → 1.21.0

data/lib/redis_queued_locks/acquirer/reindex_locks.rb

@@ -2,7 +2,13 @@
 
 # @api private
 # @since 1.20.0
+# @version 1.21.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::ReindexLocks
+  # @since 1.21.0
+  extend RedisQueuedLocks::Utilities
+
+  # rubocop:disable Metrics/ClassLength
   class << self
     # Adds the lock keys without the lock index entry (keys of older RQL versions created before
     # the lock index) to the lock index (`RedisQueuedLocks::Resource::LOCK_INDEX_KEY`):
@@ -16,18 +22,125 @@ module RedisQueuedLocks::Acquirer::ReindexLocks
     #   - keys without TTL (unreachable for RQL keys) are indexed forever (`+inf` score);
     #   - the index score is never decreased (`ZADD GT`): the operation is idempotent and can be
     #     invoked at any time (keys of the current RQL version are indexed already);
+    #   - the operation is reported with one log and one instrumentation event
+    #     (`redis_queued_locks.reindex_locks`) with the time of the whole operation;
     #
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
     # @param queue_ttl [Integer] TTL of the lock queues without TTL (in seconds).
     # @param lock_index_grace_period [Integer]
     #   The lock index score margin over the key lifetime (in milliseconds).
+    # @param logger [::Logger,#debug]
+    # @param instrumenter [#notify]
+    # @param instrument [NilClass,Any]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @param log_sample_this [Boolean]
+    # @param instr_sampling_enabled [Boolean]
+    # @param instr_sampling_percent [Integer]
+    # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+    # @param 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 private
     # @since 1.20.0
-    def reindex_locks(redis_client, scan_size, queue_ttl, lock_index_grace_period)
+    # @version 1.21.0
+    # rubocop:disable Metrics/MethodLength
+    def reindex_locks(
+      redis_client,
+      scan_size,
+      queue_ttl,
+      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
+    )
+      # NOTE: (arguments) the same ranges as the config keys: zero/negative sizes fail SCAN
+      #   (`COUNT 0`), a non-positive queue ttl expires the lock queues without TTL at once;
+      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
+      if !queue_ttl.is_a?(::Integer) || queue_ttl <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:queue_ttl` argument should be a positive Integer, got #{queue_ttl.inspect}."
+        )
+      end
+      if !lock_index_grace_period.is_a?(::Integer) || lock_index_grace_period < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:lock_index_grace_period` argument should be a non-negative Integer, " \
+          "got #{lock_index_grace_period.inspect}."
+        )
+      end
+
+      idx_start_time = clock_gettime
+      idx_key_cnt = fully_reindex_locks(redis_client, scan_size, queue_ttl, lock_index_grace_period)
+      time_at = Time.now.to_f
+      idx_end_time = clock_gettime
+      idx_time = ((idx_end_time - idx_start_time) / 1_000.0).ceil(2)
+
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sample_this,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.reindex_locks] " \
+          "idx_key_cnt => #{idx_key_cnt} " \
+          "idx_time => #{idx_time} " \
+          "at => #{time_at}"
+        end
+      end if log_sampled
+
+      run_non_critical do
+        instrumenter.notify('redis_queued_locks.reindex_locks', {
+          idx_key_cnt: idx_key_cnt,
+          idx_time: idx_time,
+          at: time_at,
+          instrument: instrument
+        })
+      end if instr_sampled
+
+      { ok: true, result: { idx_key_cnt: } }
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+    # Adds the lock keys without the lock index entry to the lock index (see `reindex_locks`).
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @param queue_ttl [Integer] TTL of the lock queues without TTL (in seconds).
+    # @param lock_index_grace_period [Integer]
+    # @return [Integer] The number of indexed keys.
+    #
+    # @api private
+    # @since 1.21.0
+    def fully_reindex_locks(redis_client, scan_size, queue_ttl, lock_index_grace_period)
       # NOTE: `ceil` - queue ttl can be passed as a Float (in seconds), PEXPIRE requires Integer
       queue_pttl = (queue_ttl * 1_000).ceil
       idx_key_cnt = 0
@@ -61,11 +174,9 @@ module RedisQueuedLocks::Acquirer::ReindexLocks
         end
       end
 
-      { ok: true, result: { idx_key_cnt: } }
+      idx_key_cnt
     end
 
-    private
-
     # Adds the given batch of lock keys to the lock index (two round trips: key TTLs, then
     # the index entries).
     #
@@ -137,4 +248,6 @@ module RedisQueuedLocks::Acquirer::ReindexLocks
       1
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/acquirer/release_all_locks.rb

@@ -39,7 +39,7 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
     #   - works in tandem with <config['log_sampling_percent']> and <config['log_sampler']>;
     # @param 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;
     # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     #   - percent-based log sampler that decides should be RQL case logged or not;
@@ -60,7 +60,7 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
     #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
     # @param 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;
     # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
@@ -81,7 +81,8 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
+    # rubocop:disable Metrics/MethodLength
     def release_all_locks(
       redis,
       batch_size,
@@ -98,6 +99,15 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
       instr_sampler,
       instr_sample_this
     )
+      # NOTE: (arguments) the same ranges as the config keys: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      if !batch_size.is_a?(::Integer) || batch_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:batch_size` argument should be a positive Integer, got #{batch_size.inspect}."
+        )
+      end
+
       rel_start_time = clock_gettime
       # steep:ignore:start
       fully_release_all_locks(redis, batch_size, lock_index_enabled) => { ok:, result: }
@@ -110,6 +120,12 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
       rel_end_time = clock_gettime
       rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
       instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
         instr_sampling_enabled,
         instr_sample_this,
@@ -117,11 +133,21 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
         instr_sampler
       )
 
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.explicit_all_locks_release] " \
+          "at => #{time_at} " \
+          "rel_time => #{rel_time} " \
+          "rel_key_cnt => #{result[:rel_key_cnt]}"
+        end
+      end if log_sampled
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.explicit_all_locks_release', {
           at: time_at,
           rel_time: rel_time,
-          rel_key_cnt: result[:rel_key_cnt]
+          rel_key_cnt: result[:rel_key_cnt],
+          instrument: instrument
         })
       end if instr_sampled
 
@@ -130,6 +156,7 @@ module RedisQueuedLocks::Acquirer::ReleaseAllLocks
         result: { rel_key_cnt: result[:rel_key_cnt], rel_time: rel_time }
       }
     end
+    # rubocop:enable Metrics/MethodLength
 
     private
 

data/lib/redis_queued_locks/acquirer/release_lock.rb

@@ -2,10 +2,13 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.21.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::ReleaseLock
   # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
+  # rubocop:disable Metrics/ClassLength
   class << self
     # Release the concrete lock:
     # - 1. clear lock queue: al; related processes released
@@ -22,18 +25,21 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #   The lock name that should be released.
     # @param lock_index_enabled [Boolean]
     #   Drop the lock name from the lock index (the enabled lock index).
-    # @param instrumenter [#notify]
-    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @param instrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @param instrument [NilClass,Any]
+    #    - Custom instrumentation data wich will be passed to the instrumenter's payload
+    #      with :instrument key;
     # @param log_sampling_enabled [Boolean]
     #   - enables <log sampling>: only the configured percent of RQL cases will be logged;
     #   - disabled by default;
     #   - works in tandem with <config['log_sampling_percent']> and <config['log_sampler']>;
     # @param 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;
     # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     #   - percent-based log sampler that decides should be RQL case logged or not;
@@ -54,7 +60,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
     # @param 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;
     # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
@@ -75,14 +81,15 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def release_lock(
       redis,
       lock_name,
       lock_index_enabled,
-      instrumenter,
       logger,
+      instrumenter,
+      instrument,
       log_sampling_enabled,
       log_sampling_percent,
       log_sampler,
@@ -112,6 +119,12 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
       rel_end_time = clock_gettime
       rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
       instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
         instr_sampling_enabled,
         instr_sample_this,
@@ -119,12 +132,23 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
         instr_sampler
       )
 
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.explicit_lock_release] " \
+          "lock_key => '#{lock_key}' " \
+          "lock_key_queue => '#{lock_key_queue}' " \
+          "rel_time => #{rel_time} " \
+          "at => #{time_at}"
+        end
+      end if log_sampled
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.explicit_lock_release', {
           lock_key: lock_key,
           lock_key_queue: lock_key_queue,
           rel_time: rel_time,
-          at: time_at
+          at: time_at,
+          instrument: instrument
         })
       end if instr_sampled
 
@@ -229,4 +253,6 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     end
     # rubocop:enable Metrics/MethodLength
   end
+  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/acquirer/release_locks_of.rb

@@ -44,7 +44,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     #   - works in tandem with <config['log_sampling_percent']> and <config['log_sampler']>;
     # @param 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;
     # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     #   - percent-based log sampler that decides should be RQL case logged or not;
@@ -65,7 +65,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
     # @param 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;
     # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
@@ -93,7 +93,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     #
     # @api private
     # @since 1.14.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def release_locks_of(
       refused_host_id,
@@ -114,6 +114,22 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
       instr_sampler,
       instr_sample_this
     )
+      # NOTE: (arguments) the same ranges as the config keys: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      if !lock_scan_size.is_a?(::Integer) || lock_scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:lock_scan_size` argument should be a positive Integer, got #{lock_scan_size.inspect}."
+        )
+      end
+      if !queue_scan_size.is_a?(::Integer) || queue_scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:queue_scan_size` argument should be a positive Integer, " \
+          "got #{queue_scan_size.inspect}."
+        )
+      end
+
       rel_start_time = clock_gettime
 
       # steep:ignore:start
@@ -134,6 +150,12 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
       rel_end_time = clock_gettime
       rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
       instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
         instr_sampling_enabled,
         instr_sample_this,
@@ -141,6 +163,18 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
         instr_sampler
       )
 
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.release_locks_of] " \
+          "at => #{time_at} " \
+          "hst_id => '#{refused_host_id}' " \
+          "acq_id => '#{refused_acquirer_id}' " \
+          "rel_time => #{rel_time} " \
+          "rel_key_cnt => #{result[:rel_key_cnt]} " \
+          "tch_queue_cnt => #{result[:tch_queue_cnt]}"
+        end
+      end if log_sampled
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.release_locks_of', {
           at: time_at,
@@ -148,7 +182,8 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
           acq_id: refused_acquirer_id,
           rel_time: rel_time,
           rel_key_cnt: result[:rel_key_cnt],
-          tch_queue_cnt: result[:tch_queue_cnt]
+          tch_queue_cnt: result[:tch_queue_cnt],
+          instrument: instrument
         })
       end if instr_sampled
 

data/lib/redis_queued_locks/acquirer/release_read_lock.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.18.0
+# @version 1.21.0
 module RedisQueuedLocks::Acquirer::ReleaseReadLock
   # @since 1.18.0
   extend RedisQueuedLocks::Utilities
@@ -17,11 +18,11 @@ module RedisQueuedLocks::Acquirer::ReleaseReadLock
     #   The lock name whose read lock should be released.
     # @param acquirer_id [String]
     #   The read lock acquirer.
-    # @param instrumenter [#notify]
-    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @param instrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param instrument [NilClass,Any]
     #   - Custom instrumentation data wich will be passed to the instrumenter's payload
     #     with :instrument key;
@@ -52,13 +53,14 @@ module RedisQueuedLocks::Acquirer::ReleaseReadLock
     #
     # @api private
     # @since 1.18.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def release_read_lock(
       redis,
       lock_name,
       acquirer_id,
-      instrumenter,
       logger,
+      instrumenter,
       instrument,
       log_sampling_enabled,
       log_sampling_percent,
@@ -87,6 +89,12 @@ module RedisQueuedLocks::Acquirer::ReleaseReadLock
       rel_end_time = clock_gettime
       rel_time = ((rel_end_time - rel_start_time) / 1_000.0).ceil(2)
 
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
       instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
         instr_sampling_enabled,
         instr_sample_this,
@@ -94,6 +102,17 @@ module RedisQueuedLocks::Acquirer::ReleaseReadLock
         instr_sampler
       )
 
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.explicit_read_lock_release] " \
+          "lock_key => '#{lock_key}' " \
+          "acq_id => '#{acquirer_id}' " \
+          "lock_res => '#{result[:lock]}' " \
+          "rel_time => #{rel_time} " \
+          "at => #{time_at}"
+        end
+      end if log_sampled
+
       run_non_critical do
         instrumenter.notify('redis_queued_locks.explicit_read_lock_release', {
           lock_key: lock_key,