redis_queued_locks 1.20.0 → 1.22.0

data/lib/redis_queued_locks/acquirer/extend_lock_ttl.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.20.0
+# @version 1.21.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::ExtendLockTTL
   # @return [String]
@@ -14,11 +14,18 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     return redis.call("PEXPIRE", KEYS[1], new_lock_pttl);
   LUA_SCRIPT
 
+  # @since 1.21.0
+  extend RedisQueuedLocks::Utilities
+
   # rubocop:disable Metrics/ClassLength
   class << self
+    # Extends the lock TTL and reports the operation (one log and one instrumentation event
+    # `redis_queued_locks.extend_lock_ttl` with the time of the whole operation).
+    #
     # @param redis_client [RedisClient]
     # @param lock_name [String]
     # @param milliseconds [Integer]
+    #   How many milliseconds should be added: a positive Integer.
     # @param read_write_mode [Symbol]
     #   - `:write` - extends the write lock (of any acquirer);
     #   - `:read` - extends the read lock of the given acquirer (other read locks are not affected)
@@ -45,7 +52,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def extend_lock_ttl(
       redis_client,
@@ -67,7 +74,9 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
       instr_sampler,
       instr_sample_this
     )
-      if read_write_mode != :read && read_write_mode != :write
+      case read_write_mode # NOTE: (steep) case/when narrows `Symbol` to `RQL::readWriteMode` below
+      when :read, :write then nil
+      else
         raise(
           RedisQueuedLocks::ArgumentError,
           "`:read_write_mode` argument should be `:read` or `:write`, " \
@@ -75,16 +84,105 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
         )
       end
 
+      # NOTE: a non-positive value would decrease the lock ttl or delete the lock;
+      if !milliseconds.is_a?(::Integer) || milliseconds <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`milliseconds` argument should be a positive Integer, got #{milliseconds.inspect}."
+        )
+      end
+
+      if read_write_mode == :read && all_read_locks != true && all_read_locks != false
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:all_read_locks` argument should be a boolean, got #{all_read_locks.inspect}."
+        )
+      end
+
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 
-      if read_write_mode == :read
-        if all_read_locks != true && all_read_locks != false
-          raise(
-            RedisQueuedLocks::ArgumentError,
-            "`:all_read_locks` argument should be a boolean, got #{all_read_locks.inspect}."
-          )
+      ext_start_time = clock_gettime
+      result = fully_extend_lock_ttl(
+        redis_client, lock_name, lock_key, milliseconds, read_write_mode, all_read_locks,
+        acquirer_id, lock_index_enabled
+      )
+      time_at = Time.now.to_f
+      ext_end_time = clock_gettime
+      ext_time = ((ext_end_time - ext_start_time) / 1_000.0).ceil(2)
+      ext_result = result[:result]
+      extended_locks_count = ext_result.is_a?(::Hash) ? ext_result[:extended_locks_count] : 0
+
+      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.extend_lock_ttl] " \
+          "lock_key => '#{lock_key}' " \
+          "rw_mode => '#{read_write_mode}' " \
+          "all_read_locks => #{all_read_locks} " \
+          "ext_ttl => #{milliseconds} " \
+          "extended_locks_count => #{extended_locks_count} " \
+          "ext_time => #{ext_time} " \
+          "at => #{time_at}"
         end
+      end if log_sampled
+
+      run_non_critical do
+        instrumenter.notify('redis_queued_locks.extend_lock_ttl', {
+          lock_key: lock_key,
+          rw_mode: read_write_mode,
+          all_read_locks: all_read_locks,
+          ext_ttl: milliseconds,
+          extended_locks_count: extended_locks_count,
+          ext_time: ext_time,
+          at: time_at,
+          instrument: instrument
+        })
+      end if instr_sampled
 
+      result
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+    # Extends the write lock, the read lock of the acquirer or all read locks of the lock.
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @param lock_key [String]
+    # @param milliseconds [Integer]
+    # @param read_write_mode [Symbol]
+    # @param all_read_locks [Boolean]
+    # @param acquirer_id [String]
+    # @param lock_index_enabled [Boolean]
+    # @return [Hash<Symbol,Boolean|Symbol|Hash<Symbol,Integer>>]
+    #
+    # @api private
+    # @since 1.21.0
+    # rubocop:disable Metrics/MethodLength
+    def fully_extend_lock_ttl(
+      redis_client,
+      lock_name,
+      lock_key,
+      milliseconds,
+      read_write_mode,
+      all_read_locks,
+      acquirer_id,
+      lock_index_enabled
+    )
+      if read_write_mode == :read
         # NOTE: (RW) all live read locks of the lock
         if all_read_locks
           return extend_all_read_locks_ttl(
@@ -131,8 +229,6 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     end
     # rubocop:enable Metrics/MethodLength
 
-    private
-
     # Extends the live read lock of the acquirer:
     #   - the read lock expiration (readers registry score), the registry TTL and the read lock
     #     data TTL are extended;
@@ -149,7 +245,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     #
     # @api private
     # @since 1.18.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def extend_read_lock_ttl(
       redis_client,
@@ -191,6 +287,14 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
             end
           end
         end
+      rescue RedisQueuedLocks::LockAcquirementIntermediateTimeoutError,
+             RedisQueuedLocks::TimedLockIntermediateTimeoutError,
+             ::Timeout::ExitException
+        # NOTE: (timeouts) an interrupted WATCH block (the internal timeouts and the user's
+        #   `Timeout.timeout` without an exception class): the closed connection drops the WATCH
+        #   state (redis-client sends `UNWATCH` only on `StandardError`);
+        rconn.close
+        raise
       end
 
       # NOTE:
@@ -223,7 +327,7 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
     #
     # @api private
     # @since 1.18.0
-    # @version 1.20.0
+    # @version 1.21.0
     # rubocop:disable Metrics/MethodLength
     def extend_all_read_locks_ttl(
       redis_client,
@@ -278,6 +382,14 @@ module RedisQueuedLocks::Acquirer::ExtendLockTTL
             end
           end
         end
+      rescue RedisQueuedLocks::LockAcquirementIntermediateTimeoutError,
+             RedisQueuedLocks::TimedLockIntermediateTimeoutError,
+             ::Timeout::ExitException
+        # NOTE: (timeouts) an interrupted WATCH block (the internal timeouts and the user's
+        #   `Timeout.timeout` without an exception class): the closed connection drops the WATCH
+        #   state (redis-client sends `UNWATCH` only on `StandardError`);
+        rconn.close
+        raise
       end
 
       # NOTE:

data/lib/redis_queued_locks/acquirer/is_locked.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
 module RedisQueuedLocks::Acquirer::IsLocked
   class << self
     # @param redis_client [RedisClient]

data/lib/redis_queued_locks/acquirer/is_queued.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
 module RedisQueuedLocks::Acquirer::IsQueued
   class << self
     # @param redis_client [RedisClient]

data/lib/redis_queued_locks/acquirer/keys.rb

@@ -32,8 +32,17 @@ module RedisQueuedLocks::Acquirer::Keys
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.21.0
     def keys(redis_client, scan_size:, lock_index_enabled:)
+      # NOTE: (arguments) the same range as the config key: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      if !scan_size.is_a?(::Integer) || scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:scan_size` argument should be a positive Integer, got #{scan_size.inspect}."
+        )
+      end
+
       Set.new.tap do |keyset|
         # @type var keyset: Set[String]
         if lock_index_enabled
@@ -125,7 +134,8 @@ module RedisQueuedLocks::Acquirer::Keys
 
     # Iterates over the lock names of the lock index (one ZSCAN pass) in batches of `scan_size`
     # lock names (batches are collected across ZSCAN pages). Expired lock names (not dropped from
-    # the index yet) are skipped: all their keys are expired.
+    # the index yet) are skipped: all their keys are expired (`+inf` names, keys without TTL, never
+    # expire: see `RedisQueuedLocks::Resource.lock_index_score_expired?`).
     #
     # NOTE: each operation module iterates over the lock index by itself (duplicated on purpose:
     #   operation modules are independent of each other, see `Locks.each_lock_name_batch`);
@@ -138,6 +148,7 @@ module RedisQueuedLocks::Acquirer::Keys
     #
     # @api private
     # @since 1.20.0
+    # @version 1.22.0
     def each_lock_name_batch(redis_client, scan_size)
       lock_index_time = RedisQueuedLocks::Resource.lock_index_time
       # @type var lock_names: Array[String]
@@ -146,7 +157,9 @@ module RedisQueuedLocks::Acquirer::Keys
       redis_client.zscan(
         RedisQueuedLocks::Resource::LOCK_INDEX_KEY, count: scan_size
       ) do |lock_name, lock_index_score|
-        next if lock_index_score.to_f < lock_index_time
+        next if RedisQueuedLocks::Resource.lock_index_score_expired?(
+          lock_index_score, lock_index_time
+        )
 
         lock_names << lock_name
         next if lock_names.size < scan_size

data/lib/redis_queued_locks/acquirer/lock_info.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.20.0
+# @version 1.18.0
 module RedisQueuedLocks::Acquirer::LockInfo
   class << self
     # @param redis_client [RedisClient]
@@ -56,46 +56,38 @@ module RedisQueuedLocks::Acquirer::LockInfo
         pipeline.call('ZRANGE', lock_readers_key, '0', '-1', 'WITHSCORES')
       end
 
-      if result == nil
-        # NOTE:
-        #   - nil result means that during transaction invocation the lock is changed (CAS):
-        #     - lock is expired;
-        #     - lock is released;
-        #     - lock is expired + re-obtained;
-        nil
-      else
-        # NOTE: the result of MULTI-command is an array of results of each internal command
-        #   - result[0] (HGETALL) (Hash<String,String>)
-        #     => (will be mutated further with different value types)
-        #   - result[1] (PTTL) (Integer)
-        #     => (without any mutation, integer is atomic)
-        #   - result[2] (TIME) (Array<String>) (redis time)
-        #   - result[3] (ZRANGE) (Array<[String,Float]>) (read locks)
+      # NOTE: (pipeline layout) the replies of the pipeline commands (`pipelined` always returns
+      #   an array of the replies):
+      #   - result[0] (HGETALL) (Hash<String,String>)
+      #     => (will be mutated further with different value types)
+      #   - result[1] (PTTL) (Integer)
+      #     => (without any mutation, integer is atomic)
+      #   - result[2] (TIME) (Array<String>) (redis time)
+      #   - result[3] (ZRANGE) (Array<[String,Float]>) (read locks)
 
-        # rubocop:disable Layout/LineLength
-        # @type var result: [Hash[String,String|Float|Integer], Integer, Array[String], Array[[String, Float]]]
-        # rubocop:enable Layout/LineLength
-        hget_cmd_res = result[0]
-        pttl_cmd_res = result[1]
+      # rubocop:disable Layout/LineLength
+      # @type var result: [Hash[String,String|Float|Integer], Integer, Array[String], Array[[String, Float]]]
+      # rubocop:enable Layout/LineLength
+      hget_cmd_res = result[0]
+      pttl_cmd_res = result[1]
 
-        if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
-          # NOTE: (RW) there is no write lock => check read locks
-          read_lock_info(redis_client, lock_name, lock_key, result[2], result[3])
-        else
-          hget_cmd_res.tap do |lock_data|
-            lock_data['lock_key'] = lock_key
-            lock_data['rw_mode'] = 'write'
-            lock_data['ts'] = Float(lock_data['ts'])
-            lock_data['ini_ttl'] = Integer(lock_data['ini_ttl'])
-            lock_data['rem_ttl'] = ((pttl_cmd_res == -1) ? Float::INFINITY : pttl_cmd_res)
-            lock_data['spc_cnt'] = Integer(lock_data['spc_cnt']) if lock_data['spc_cnt']
-            lock_data['l_spc_ts'] = Float(lock_data['l_spc_ts']) if lock_data['l_spc_ts']
-            lock_data['spc_ext_ttl'] = Integer(lock_data['spc_ext_ttl']) if lock_data['spc_ext_ttl']
-            lock_data['l_spc_ext_ini_ttl'] =
-              Integer(lock_data['l_spc_ext_ini_ttl']) if lock_data.key?('l_spc_ext_ini_ttl')
-            lock_data['l_spc_ext_ts'] =
-              Float(lock_data['l_spc_ext_ts']) if lock_data['l_spc_ext_ts']
-          end
+      if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
+        # NOTE: (RW) there is no write lock => check read locks
+        read_lock_info(redis_client, lock_name, lock_key, result[2], result[3])
+      else
+        hget_cmd_res.tap do |lock_data|
+          lock_data['lock_key'] = lock_key
+          lock_data['rw_mode'] = 'write'
+          lock_data['ts'] = Float(lock_data['ts'])
+          lock_data['ini_ttl'] = Integer(lock_data['ini_ttl'])
+          lock_data['rem_ttl'] = ((pttl_cmd_res == -1) ? Float::INFINITY : pttl_cmd_res)
+          lock_data['spc_cnt'] = Integer(lock_data['spc_cnt']) if lock_data['spc_cnt']
+          lock_data['l_spc_ts'] = Float(lock_data['l_spc_ts']) if lock_data['l_spc_ts']
+          lock_data['spc_ext_ttl'] = Integer(lock_data['spc_ext_ttl']) if lock_data['spc_ext_ttl']
+          lock_data['l_spc_ext_ini_ttl'] =
+            Integer(lock_data['l_spc_ext_ini_ttl']) if lock_data.key?('l_spc_ext_ini_ttl')
+          lock_data['l_spc_ext_ts'] =
+            Float(lock_data['l_spc_ext_ts']) if lock_data['l_spc_ext_ts']
         end
       end
     end

data/lib/redis_queued_locks/acquirer/lock_series_poc/instr_visitor.rb

@@ -3,18 +3,21 @@
 # NOTE: Lock Series PoC
 # @api private
 # @since 1.16.1
+# @version 1.22.0
 module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
   class << self
     # NOTE: Lock Series PoC
     # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
     # @api private
     # @since 1.16.1
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_series_obtained( # steep:ignore
       instrumenter,
       instr_sampled,
       lock_keys,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -24,20 +27,22 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.lock_series_obtained', {
-        lock_keys:, rw_mode:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+        lock_keys:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
       }) rescue nil
     end
 
     # NOTE: Lock Series PoC
     # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
     # @api private
     # @since 1.16.1
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_series_hold_and_release( # steep:ignore
       instrumenter,
       instr_sampled,
       lock_keys,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -48,8 +53,9 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.lock_series_hold_and_release', {
-        lock_keys:, rw_mode:, hold_time:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
-      }) # rescue nil
+        lock_keys:, rw_mode:, priority:, hold_time:, ttl:, acq_id:, hst_id:, ts:, acq_time:,
+        instrument:
+      }) rescue nil
     end
   end
 end

data/lib/redis_queued_locks/acquirer/lock_series_poc/log_visitor.rb

@@ -3,13 +3,15 @@
 # NOTE: Lock Series PoC
 # @api private
 # @since 1.16.1
+# @version 1.22.0
 module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
   class << self
     # NOTE: Lock Series PoC
     # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
     # @api private
     # @since 1.16.0
-    # @version 1.18.0
+    # @version 1.22.0
     def start_lock_series_obtaining( # steep:ignore
       logger,
       log_sampled,
@@ -18,7 +20,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
       acquirer_id,
       host_id,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -29,15 +32,17 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
         "acq_id => '#{acquirer_id}' " \
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
-        "rw_mode => '#{rw_mode}'"
-      end # rescue nil
+        "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority}"
+      end rescue nil
     end
 
     # NOTE: Lock Series PoC
     # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
     # @api private
     # @since 1.16.0
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_series_obtained( # steep:ignore
       logger,
       log_sampled,
@@ -47,7 +52,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
       host_id,
       acq_time,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -59,15 +65,17 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
         "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority} " \
         "acq_time => #{acq_time} (ms)"
-      end # rescue nil
+      end rescue nil
     end
 
     # NOTE: Lock Series PoC
     # @param rw_mode [Symbol] The mode of the lock series (`:read` or `:write`).
+    # @param priority [Integer] The lock request priority of the series.
     # @api private
     # @since 1.16.0
-    # @version 1.18.0
+    # @version 1.22.0
     def expire_lock_series( # steep:ignore
       logger,
       log_sampled,
@@ -76,7 +84,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
       acquirer_id,
       host_id,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -87,7 +96,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore
         "acq_id => '#{acquirer_id}' " \
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
-        "rw_mode => '#{rw_mode}'"
+        "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority}"
       end rescue nil
     end
   end