redis_queued_locks 1.21.0 → 1.23.0

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.23.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
@@ -106,7 +106,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
-    # @option read_write_mode [Symbol]
+    # @option rw_mode [Symbol]
     #   - `:write` (default) - exclusive lock: waits for the write lock and for all read locks;
     #   - `:read` - shared lock: waits for the write lock only (read locks do not block each other);
     #   - `:queued` access strategy orders read and write requests in FIFO between modes
@@ -126,6 +126,22 @@ 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;
@@ -177,7 +193,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.21.0
+    # @version 1.23.0
     def acquire_lock(
       redis,
       lock_name,
@@ -204,8 +220,10 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
+      priority:,
+      lock_priorities:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
@@ -227,12 +245,14 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         )
       end
 
-      # Step 0.1 (RW): prevent :read_write_mode incompatabilities
-      if read_write_mode != :read && read_write_mode != :write
+      # Step 0.1 (RW): prevent :rw_mode incompatabilities
+      case rw_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`, " \
-          "got #{read_write_mode.inspect}."
+          "`:rw_mode` argument should be `:read` or `:write`, " \
+          "got #{rw_mode.inspect}."
         )
       end
 
@@ -292,6 +312,27 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         )
       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;
@@ -342,11 +383,13 @@ module RedisQueuedLocks::Acquirer::AcquireLock
       # NOTE: (RW) read lock data key is required by read lock requests only (write lock requests
       #   never obtain read locks: read-to-write lock upgrade is not supported);
       read_lock_key =
-        if read_write_mode == :read
+        if rw_mode == :read
           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,
@@ -379,7 +422,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
           redis,
           logger,
           lock_key,
-          read_write_mode,
+          rw_mode,
           lock_key_queue,
           read_lock_key_queue,
           queue_ttl,
@@ -393,7 +436,7 @@ 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, rw_mode, priority
       )
 
       # Step 2: try to lock with timeout
@@ -414,17 +457,18 @@ module RedisQueuedLocks::Acquirer::AcquireLock
 
           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, rw_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, rw_mode, priority
             )
           end
 
@@ -435,7 +479,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             logger,
             log_lock_try,
             lock_key,
-            read_write_mode,
+            rw_mode,
             lock_key_queue,
             read_lock_key_queue,
             lock_readers_key,
@@ -444,6 +488,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             acquirer_id,
             host_id,
             acquirer_position,
+            priority,
             lock_ttl,
             queue_ttl,
             lock_index_enabled,
@@ -477,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, rw_mode,
+                priority
               )
               InstrVisitor.extendable_reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -488,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, rw_mode,
+                priority
               )
               InstrVisitor.reentrant_lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -500,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, rw_mode,
+                priority
               )
               InstrVisitor.lock_obtained(
-                instrumenter, instr_sampled, result[:lock_key], read_write_mode,
+                instrumenter, instr_sampled, result[:lock_key], rw_mode, priority,
                 result[:ttl], result[:acq_id], result[:hst_id], result[:ts], acq_time,
                 instrument
               )
@@ -660,7 +708,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instrumenter,
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
-                read_write_mode,
+                rw_mode,
+                priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
                 acq_process[:lock_info][:hst_id],
@@ -675,7 +724,8 @@ module RedisQueuedLocks::Acquirer::AcquireLock
                 instrumenter,
                 instr_sampled,
                 acq_process[:lock_info][:lock_key],
-                read_write_mode,
+                rw_mode,
+                priority,
                 acq_process[:lock_info][:ttl],
                 acq_process[:lock_info][:acq_id],
                 acq_process[:lock_info][:hst_id],
@@ -705,11 +755,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         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, acq_process[:result]
+          acq_time, access_strategy, rw_mode, priority, acq_process[:result]
         )
         InstrVisitor.lock_obtaining_failed(
-          instrumenter, instr_sampled, lock_key, read_write_mode, lock_ttl, acquirer_id, host_id,
-          Time.now.to_f, acq_time, acq_process[:result], instrument
+          instrumenter, instr_sampled, lock_key, rw_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
@@ -730,11 +780,11 @@ module RedisQueuedLocks::Acquirer::AcquireLock
         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, acq_process[:result]
+          acq_time, access_strategy, rw_mode, priority, acq_process[:result]
         )
         InstrVisitor.lock_obtaining_failed(
-          instrumenter, instr_sampled, lock_key, read_write_mode, lock_ttl, acquirer_id, host_id,
-          Time.now.to_f, acq_time, acq_process[:result], instrument
+          instrumenter, instr_sampled, lock_key, rw_mode, priority, lock_ttl, acquirer_id,
+          host_id, Time.now.to_f, acq_time, acq_process[:result], instrument
         )
       end
       # steep:ignore:end