redis_queued_locks 1.20.0 → 1.22.0

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

@@ -6,7 +6,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::WithAcqTimeout
   # @param redis [RedisClient]
   #   Redis connection manager required for additional data extraction for error message.
   # @param timeout [NilClass,Integer]
-  #   Time period after which the logic will fail with timeout error.
+  #   Time period after which the logic will fail with timeout error (`nil` and `0`: no timeout).
   # @param lock_key [String]
   #   Lock name in RQL notation (rql:lock:some-lock-name).
   # @param lock_name [String]
@@ -26,7 +26,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::WithAcqTimeout
   #
   # @api private
   # @since 1.0.0
-  # @version 1.11.0
+  # @version 1.21.0
   def with_acq_timeout(
     redis,
     timeout,

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

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

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

@@ -30,7 +30,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   # @param access_strategy [Symbol] Lock obtaining strategy.
   # @param timed [Boolean] Should the lock be wrapped by Timeout with with lock's ttl
   # @param ttl_shift [Numeric] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
-  # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
+  # @param ttl [Integer] Lock's time to live (in ms). A positive Integer.
   # @param queue_ttl [Integer] Lock request lifetime.
   # @param meta [NilClass,Hash<String|Symbol,Any>] Custom metadata wich is passed to the lock data;
   # @param log_sampled [Boolean] Should the logic be logged or not.
@@ -45,7 +45,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.18.0
+  # @version 1.21.0
   # rubocop:disable Metrics/MethodLength
   def yield_expire(
     redis,
@@ -71,7 +71,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
     initial_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
 
     if block_given?
-      if timed && ttl != nil
+      if timed
         # NOTE:
         #   - steep is ignored cuz steep can not recognize `::Integer - ::Integer|::Float`
         #     operation here for some mystical reason (it tryes to find overloadd `-` method for
@@ -150,7 +150,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
 
   # @param timeout [Float]
   # @param lock_key [String]
-  # @param lock_ttl [Integer,NilClass]
+  # @param lock_ttl [Integer]
   # @param acquirer_id [String]
   # @param host_id [String]
   # @param meta [NilClass,Hash<Symbol|String,Any>]
@@ -161,7 +161,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   #
   # @api private
   # @since 1.3.0
-  # @version 1.12.0
+  # @version 1.21.0
   def yield_with_timeout(timeout, lock_key, lock_ttl, acquirer_id, host_id, meta, &block)
     ::Timeout.timeout(timeout, RedisQueuedLocks::TimedLockIntermediateTimeoutError, &block)
   rescue RedisQueuedLocks::TimedLockIntermediateTimeoutError

data/lib/redis_queued_locks/acquirer/acquire_lock.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.20.0
+# @version 1.22.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
@@ -42,8 +42,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   A current fiber that want to acquire a lock.
     # @option ractor_id [Integer,String]
     #   The current ractor that want to acquire a lock.
-    # @option ttl [Integer,NilClass]
-    #   Lock's time to live (in milliseconds). Nil means "without timeout".
+    # @option ttl [Integer]
+    #   Lock's time to live (in milliseconds). A positive Integer (both modes).
     # @option queue_ttl [Integer]
     #   Lifetime of the acuier's lock request. In seconds.
     # @option lock_index_enabled [Boolean]
@@ -57,7 +57,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   - pre-configured in `config['lock_index_grace_period']`;
     #   - used only with the enabled lock index (`lock_index_enabled`);
     # @option timeout [Integer,NilClass]
-    #   Time period whe should try to acquire the lock (in seconds).
+    #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout"
+    #   (`0` is the same as `nil`: `Timeout.timeout(0)` sets no timeout).
     # @option timed [Boolean]
     #   Limit the invocation time period of the passed block of code by the lock's TTL.
     # @option retry_count [Integer,NilClass]
@@ -125,13 +126,29 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #       (but with checking the limist, retries, timeouts and so on). if lock is
     #       free to obtain - it will be obtained;
     #   - pre-configured in `config['default_access_strategy']`;
+    # @option priority [Integer,Symbol]
+    #   - The lock request priority: from `RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY` (`-100`)
+    #     to `RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY` (`100`), `0` by default, or a priority
+    #     name of `lock_priorities` (resolved to its Integer priority: the lock request queues,
+    #     the logs and the instrumentation use the Integer priority);
+    #   - `:queued` access strategy: the lock request is placed in the lock request queue after all
+    #     requests of the same or higher priority and before all requests of the lower priority
+    #     (strict priority, FIFO inside the same priority; between modes too: the read and write
+    #     lock request queues use the same positions);
+    #   - `:random` access strategy: the lock request does not wait for its turn (it ignores the
+    #     order of the lock request queues and the priorities of other requests), but it is queued
+    #     at the position of its priority like a `:queued` one: `:queued` lock requests wait for it;
+    #   - the obtained lock is never taken away: the priority orders the waiting lock requests only;
+    #   - pre-configured in `config['default_lock_priority']`;
+    # @option lock_priorities [Hash<Symbol,Integer>]
+    #   - The priority names (`config['lock_priorities']`): a priority name => its Integer priority;
     # @option 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']>;
     # @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;
@@ -152,7 +169,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #   - 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>]
@@ -176,7 +193,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.20.0
+    # @version 1.22.0
     def acquire_lock(
       redis,
       lock_name,
@@ -205,6 +222,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       conflict_strategy:,
       read_write_mode:,
       access_strategy:,
+      priority:,
+      lock_priorities:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
@@ -227,7 +246,9 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       end
 
       # Step 0.1 (RW): prevent :read_write_mode incompatabilities
-      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`, " \
@@ -235,29 +256,100 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         )
       end
 
-      # Step 0.1 (RW): prevent read lock incompatabilities
-      #   - read lock expiration time is calculated from the lock ttl;
-      if read_write_mode == :read && (!ttl.is_a?(::Integer) || ttl <= 0)
+      # Step 0.1: prevent :ttl incompatibilities (both modes)
+      #   - write lock: `PEXPIRE` with a non-positive ttl deletes the just obtained lock key in the
+      #     obtaining transaction (the lock is "obtained" without the mutual exclusion);
+      #   - read lock: the read lock expiration time is calculated from the lock ttl;
+      if !ttl.is_a?(::Integer) || ttl <= 0
         raise(
           RedisQueuedLocks::ArgumentError,
-          "`:ttl` argument should be a positive Integer for read locks, got #{ttl.inspect}."
+          "`:ttl` argument should be a positive Integer, got #{ttl.inspect}."
+        )
+      end
+
+      # Step 0.1: prevent :queue_ttl, :timeout, :retry_* and :lock_index_grace_period
+      #   incompatibilities (the same ranges as their config keys):
+      #   - a non-positive queue ttl drops the own lock request in the queueing pipeline (the lock
+      #     request is always dead);
+      #   - a negative timeout/retry delay/retry jitter fails `Timeout.timeout`/`sleep` in the
+      #     middle of the acquirement (`0` timeout is the same as `nil`: no timeout);
+      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 timeout != nil && (!timeout.is_a?(::Integer) || timeout < 0)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:timeout` argument should be nil or a non-negative Integer, got #{timeout.inspect}."
+        )
+      end
+      if retry_count != nil && (!retry_count.is_a?(::Integer) || retry_count < 0)
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_count` argument should be nil or a non-negative Integer, " \
+          "got #{retry_count.inspect}."
+        )
+      end
+      if !retry_delay.is_a?(::Integer) || retry_delay < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_delay` argument should be a non-negative Integer, got #{retry_delay.inspect}."
+        )
+      end
+      if !retry_jitter.is_a?(::Integer) || retry_jitter < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:retry_jitter` argument should be a non-negative Integer, got #{retry_jitter.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
+
+      # Step 0.1: prevent :priority incompatibilities (the same range as its config key)
+      #   - a Symbol is a priority name of `config['lock_priorities']`: it is resolved to its
+      #     Integer priority (the lock request queues, the logs and the instrumentation use the
+      #     Integer priority; an unknown name stays a Symbol and fails the check);
+      #   - each priority has its own band of positions in the lock request queues: the range
+      #     bounds the shift of the positions (float scores lose precision with the shift: the FIFO
+      #     order inside a priority keeps ~61 µs for -100..100, see `LOCK_PRIORITY_BAND`);
+      priority = lock_priorities.fetch(priority, priority) if priority.is_a?(::Symbol)
+      if !priority.is_a?(::Integer) ||
+         priority < RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY ||
+         priority > RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:priority` argument should be an Integer from " \
+          "#{RedisQueuedLocks::Resource::MIN_LOCK_PRIORITY} to " \
+          "#{RedisQueuedLocks::Resource::MAX_LOCK_PRIORITY} or a priority name of " \
+          "`config['lock_priorities']` (#{lock_priorities.keys.map(&:inspect).join(', ')}), " \
+          "got #{priority.inspect}."
         )
       end
 
       # Step 0.2: prevent :meta incompatabiltiies (structure)
+      #   - Symbol keys are written to the lock data as Strings (`Symbol#name`, as redis-client
+      #     does it) and would overwrite the reserved lock data fields too;
       if meta.is_a?(::Hash) && (meta.any? do |key, _value|
-        key == 'acq_id' ||
-        key == 'hst_id' ||
-        key == 'ts' ||
-        key == 'ini_ttl' ||
-        key == 'lock_key' ||
-        key == 'rem_ttl' ||
-        key == 'spc_ext_ttl' ||
-        key == 'spc_cnt' ||
-        key == 'l_spc_ext_ini_ttl' ||
-        key == 'l_spc_ext_ts' ||
-        key == 'l_spc_ts' ||
-        key == 'rw_mode'
+        meta_key = key.is_a?(::Symbol) ? key.name : key
+        meta_key == 'acq_id' ||
+        meta_key == 'hst_id' ||
+        meta_key == 'ts' ||
+        meta_key == 'ini_ttl' ||
+        meta_key == 'lock_key' ||
+        meta_key == 'rem_ttl' ||
+        meta_key == 'spc_ext_ttl' ||
+        meta_key == 'spc_cnt' ||
+        meta_key == 'l_spc_ext_ini_ttl' ||
+        meta_key == 'l_spc_ext_ts' ||
+        meta_key == 'l_spc_ts' ||
+        meta_key == 'rw_mode'
       end)
         raise(
           RedisQueuedLocks::ArgumentError,
@@ -295,7 +387,9 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
         end
 
-      acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position
+      # NOTE: the position in the lock request queue: the enqueue time shifted by the priority band
+      #   (see `RedisQueuedLocks::Resource::LOCK_PRIORITY_BAND`);
+      acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position(priority)
 
       log_sampled = RedisQueuedLocks::Logging.should_log?(
         log_sampling_enabled,
@@ -342,10 +436,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock
 
       LogVisitor.start_lock_obtaining(
         logger, log_sampled, lock_key,
-        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
+        queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
       )
 
       # Step 2: try to lock with timeout
+      # NOTE: the acquirement start time is defined out of the timeout block: the failed
+      #   acquirement reports the acquirement time too (Steps 3.b and 3.c);
+      acq_start_time = clock_gettime
       with_acq_timeout(
         redis,
         timeout,
@@ -355,24 +452,23 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         detailed_acq_timeout_error,
         on_timeout: acq_dequeue
       ) do
-        acq_start_time = clock_gettime
-
         # Step 2.1: cyclically try to obtain the lock
         while acq_process[:should_try]
 
           LogVisitor.start_try_to_lock_cycle(
             logger, log_sampled, lock_key,
-            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
+            queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
           )
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
-          if RedisQueuedLocks::Resource.dead_score_reached?(acquirer_position, queue_ttl)
-            # Step 2.X.X: dead score reached => re-queue the lock request with the new score;
-            acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position
+          if RedisQueuedLocks::Resource.dead_score_reached?(acquirer_position, priority, queue_ttl)
+            # Step 2.X.X: dead score reached => re-queue the lock request with the new score
+            #   (the end of the requests of the same priority);
+            acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position(priority)
 
             LogVisitor.dead_score_reached__reset_acquirer_position(
               logger, log_sampled, lock_key,
-              queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode
+              queue_ttl, acquirer_id, host_id, access_strategy, read_write_mode, priority
             )
           end
 
@@ -392,6 +488,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             acquirer_id,
             host_id,
             acquirer_position,
+            priority,
             lock_ttl,
             queue_ttl,
             lock_index_enabled,
@@ -425,10 +522,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # instrumetnation: (reentrant lock with ttl extension)
               LogVisitor.extendable_reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                priority
               )
               InstrVisitor.extendable_reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -436,10 +534,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # instrumetnation: (reentrant lock without ttl extension)
               LogVisitor.reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                priority
               )
               InstrVisitor.reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -448,10 +547,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
               # NOTE: classic is: acq_process[:result][:process] == :lock_obtaining
               LogVisitor.lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy, read_write_mode,
+                priority
               )
               InstrVisitor.lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], read_write_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -609,6 +709,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
                 read_write_mode,
+                priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
                 acq_process[:lock_info][:hst_id],
@@ -624,6 +725,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
                 read_write_mode,
+                priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
                 acq_process[:lock_info][:hst_id],
@@ -650,8 +752,43 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           acq_process[:result] = :timeout_reached
         end
         # Step 3.b: lock is not acquired (acquirer is dequeued by timeout callback)
+        acq_time = ((clock_gettime - acq_start_time) / 1_000.0).ceil(2)
+        LogVisitor.lock_obtaining_failed(
+          logger, log_sampled, lock_key, queue_ttl, acquirer_id, host_id,
+          acq_time, access_strategy, read_write_mode, priority, acq_process[:result]
+        )
+        InstrVisitor.lock_obtaining_failed(
+          instrumenter, instr_sampled, lock_key, read_write_mode, priority, lock_ttl, acquirer_id,
+          host_id, Time.now.to_f, acq_time, acq_process[:result], instrument
+        )
         { ok: false, result: acq_process[:result] } #: { ok: bool, result: Symbol }
       end
+    rescue RedisQueuedLocks::LockAlreadyObtainedError,
+           RedisQueuedLocks::ConflictLockObtainError,
+           RedisQueuedLocks::LockAcquirementRetryLimitError,
+           RedisQueuedLocks::LockAcquirementTimeoutError => error
+      # Step 3.c: (raise_errors) the failed acquirement is reported before the error is raised
+      #   (like Step 3.b); errors of the block of code under the obtained lock are not reported;
+      # NOTE: (steep) the locals of the method body are nilable in the method-level `rescue` for
+      #   Steep, but these errors are raised by the acquirement only (after Step 1: the locals
+      #   are assigned);
+      # steep:ignore:start
+      unless acq_process[:acquired]
+        if error.is_a?(RedisQueuedLocks::LockAcquirementTimeoutError)
+          acq_process[:result] = :timeout_reached
+        end
+        acq_time = ((clock_gettime - acq_start_time) / 1_000.0).ceil(2)
+        LogVisitor.lock_obtaining_failed(
+          logger, log_sampled, lock_key, queue_ttl, acquirer_id, host_id,
+          acq_time, access_strategy, read_write_mode, priority, acq_process[:result]
+        )
+        InstrVisitor.lock_obtaining_failed(
+          instrumenter, instr_sampled, lock_key, read_write_mode, priority, lock_ttl, acquirer_id,
+          host_id, Time.now.to_f, acq_time, acq_process[:result], instrument
+        )
+      end
+      # steep:ignore:end
+      raise
     end
   end
 end