redis_queued_locks 1.20.0 → 1.22.0

data/Rakefile

@@ -55,4 +55,15 @@ end
 RSpec::Core::RakeTask.new(:rspec)
 Steep::RakeTask.new(:steep)
 
+# NOTE: (parallel specs) the runner: `spec/support/parallel_runner.rb`
+namespace :rspec do
+  desc 'Run the specs in parallel processes (WORKERS=<n>, each worker with its own Redis databases)'
+  task :parallel, [:paths] do |_task, args|
+    require_relative 'spec/support/parallel_runner'
+
+    workers = ENV.key?('WORKERS') ? Integer(ENV.fetch('WORKERS')) : nil
+    RQLParallelSpecs.run(workers, args[:paths].to_s.split)
+  end
+end
+
 task default: :rspec

data/lib/redis_queued_locks/acquirer/acquire_lock/dequeue_from_lock_queue/log_visitor.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.7.0
+# @version 1.18.0
 module RedisQueuedLocks::Acquirer::AcquireLock::DequeueFromLockQueue::LogVisitor
   class << self
     # @param logger [::Logger,#debug]

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

@@ -2,12 +2,16 @@
 
 # @api private
 # @since 1.7.0
+# @version 1.22.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
+  # rubocop:disable Metrics/ClassLength
   class << self
     # @param instrumenter [#notify]
     # @param instr_sampled [Boolean]
     # @param lock_key [String]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @param ttl [Integer, NilClass]
     # @param acq_id [String]
     # @param hst_id [String]
@@ -18,12 +22,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def extendable_reentrant_lock_obtained(
       instrumenter,
       instr_sampled,
       lock_key,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -33,7 +38,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.extendable_reentrant_lock_obtained', {
-        lock_key:, rw_mode:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+        lock_key:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
       }) rescue nil
     end
 
@@ -41,6 +46,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     # @param instr_sampled [Boolean]
     # @param lock_key [String]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @param ttl [Integer, NilClass]
     # @param acq_id [String]
     # @param hst_id [String]
@@ -51,12 +57,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def reentrant_lock_obtained(
       instrumenter,
       instr_sampled,
       lock_key,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -66,7 +73,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.reentrant_lock_obtained', {
-        lock_key:, rw_mode:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+        lock_key:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
       }) rescue nil
     end
 
@@ -74,6 +81,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     # @param instr_sampled [Boolean]
     # @param lock_key [String]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @param ttl [Integer, NilClass]
     # @param acq_id [String]
     # @param hst_id [String]
@@ -84,12 +92,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_obtained(
       instrumenter,
       instr_sampled,
       lock_key,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -99,7 +108,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.lock_obtained', {
-        lock_key:, rw_mode:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
+        lock_key:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument:
       }) rescue nil
     end
 
@@ -107,6 +116,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     # @param instr_sampled [Boolean]
     # @param lock_key [String]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @param ttl [Integer, NilClass]
     # @param acq_id [String]
     # @param hst_id [String]
@@ -118,12 +128,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def reentrant_lock_hold_completes(
       instrumenter,
       instr_sampled,
       lock_key,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -134,7 +145,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.reentrant_lock_hold_completes', {
-        hold_time:, ttl:, acq_id:, hst_id:, ts:, lock_key:, rw_mode:, acq_time:, instrument:
+        hold_time:, ttl:, acq_id:, hst_id:, ts:, lock_key:, rw_mode:, priority:, acq_time:,
+        instrument:
       }) rescue nil
     end
 
@@ -142,6 +154,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     # @param instr_sampled [Boolean]
     # @param lock_key [String]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @param ttl [Integer, NilClass]
     # @param acq_id [String]
     # @param hst_id [String]
@@ -153,12 +166,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_hold_and_release(
       instrumenter,
       instr_sampled,
       lock_key,
       rw_mode,
+      priority,
       ttl,
       acq_id,
       hst_id,
@@ -169,8 +183,52 @@ module RedisQueuedLocks::Acquirer::AcquireLock::InstrVisitor
     )
       return unless instr_sampled
       instrumenter.notify('redis_queued_locks.lock_hold_and_release', {
-        hold_time:, ttl:, acq_id:, hst_id:, ts:, lock_key:, rw_mode:, acq_time:, instrument:
+        hold_time:, ttl:, acq_id:, hst_id:, ts:, lock_key:, rw_mode:, priority:, acq_time:,
+        instrument:
+      }) rescue nil
+    end
+
+    # The lock is not obtained (the failure result of `#lock`/`#lock!`: the timeout, the retry
+    # limit, `fail_fast`, the dead lock or the lock upgrade conflict).
+    #
+    # @param instrumenter [#notify]
+    # @param instr_sampled [Boolean]
+    # @param lock_key [String]
+    # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
+    # @param ttl [Integer]
+    # @param acq_id [String]
+    # @param hst_id [String]
+    # @param ts [Numeric]
+    # @param acq_time [Numeric]
+    # @param result [Symbol] The failure result (`:timeout_reached`, `:retry_limit_reached`, ...).
+    # @param instrument [NilClass,Any]
+    # @return [void]
+    #
+    # @api private
+    # @since 1.21.0
+    # @version 1.22.0
+    def lock_obtaining_failed(
+      instrumenter,
+      instr_sampled,
+      lock_key,
+      rw_mode,
+      priority,
+      ttl,
+      acq_id,
+      hst_id,
+      ts,
+      acq_time,
+      result,
+      instrument
+    )
+      return unless instr_sampled
+      instrumenter.notify('redis_queued_locks.lock_obtaining_failed', {
+        lock_key:, rw_mode:, priority:, ttl:, acq_id:, hst_id:, ts:, acq_time:, result:,
+        instrument:
       }) rescue nil
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ModuleLength

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

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.7.0
+# @version 1.22.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
   # rubocop:disable Metrics/ClassLength
@@ -14,11 +15,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param host_id [String]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def start_lock_obtaining(
       logger,
       log_sampled,
@@ -27,7 +29,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       acquirer_id,
       host_id,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -38,7 +41,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "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
 
@@ -50,11 +54,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param host_id [String]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def start_try_to_lock_cycle(
       logger,
       log_sampled,
@@ -63,7 +68,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       acquirer_id,
       host_id,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -74,7 +80,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "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
 
@@ -86,11 +93,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param host_id [String]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def dead_score_reached__reset_acquirer_position(
       logger,
       log_sampled,
@@ -99,7 +107,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       acquirer_id,
       host_id,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -110,7 +119,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "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
 
@@ -123,11 +133,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param acq_time [Numeric]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def extendable_reentrant_lock_obtained(
       logger,
       log_sampled,
@@ -137,7 +148,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       host_id,
       acq_time,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -149,6 +161,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
         "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority} " \
         "acq_time => #{acq_time} (ms)"
       end rescue nil
     end
@@ -162,11 +175,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param acq_time [Numeric]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def reentrant_lock_obtained(
       logger,
       log_sampled,
@@ -176,7 +190,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       host_id,
       acq_time,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -188,6 +203,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
         "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority} " \
         "acq_time => #{acq_time} (ms)"
       end rescue nil
     end
@@ -201,11 +217,12 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
     # @param acq_time [Numeric]
     # @param access_strategy [Symbol]
     # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
     # @return [void]
     #
     # @api private
     # @since 1.7.0
-    # @version 1.18.0
+    # @version 1.22.0
     def lock_obtained(
       logger,
       log_sampled,
@@ -215,7 +232,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
       host_id,
       acq_time,
       access_strategy,
-      rw_mode
+      rw_mode,
+      priority
     )
       return unless log_sampled
 
@@ -227,9 +245,58 @@ module RedisQueuedLocks::Acquirer::AcquireLock::LogVisitor
         "hst_id => '#{host_id}' " \
         "acs_strat => '#{access_strategy}' " \
         "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority} " \
         "acq_time => #{acq_time} (ms)"
       end rescue nil
     end
+
+    # The lock is not obtained (the failure result of `#lock`/`#lock!`: the timeout, the retry
+    # limit, `fail_fast`, the dead lock or the lock upgrade conflict).
+    #
+    # @param logger [::Logger,#debug]
+    # @param log_sampled [Boolean]
+    # @param lock_key [String]
+    # @param queue_ttl [Integer]
+    # @param acquirer_id [String]
+    # @param host_id [String]
+    # @param acq_time [Numeric]
+    # @param access_strategy [Symbol]
+    # @param rw_mode [Symbol]
+    # @param priority [Integer] The lock request priority.
+    # @param result [Symbol] The failure result (`:timeout_reached`, `:retry_limit_reached`, ...).
+    # @return [void]
+    #
+    # @api private
+    # @since 1.21.0
+    # @version 1.22.0
+    def lock_obtaining_failed(
+      logger,
+      log_sampled,
+      lock_key,
+      queue_ttl,
+      acquirer_id,
+      host_id,
+      acq_time,
+      access_strategy,
+      rw_mode,
+      priority,
+      result
+    )
+      return unless log_sampled
+
+      logger.debug do
+        "[redis_queued_locks.lock_obtaining_failed] " \
+        "lock_key => '#{lock_key}' " \
+        "queue_ttl => #{queue_ttl} " \
+        "acq_id => '#{acquirer_id}' " \
+        "hst_id => '#{host_id}' " \
+        "acs_strat => '#{access_strategy}' " \
+        "rw_mode => '#{rw_mode}' " \
+        "priority => #{priority} " \
+        "acq_time => #{acq_time} (ms) " \
+        "result => '#{result}'"
+      end rescue nil
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end