redis_queued_locks 1.6.0 → 1.7.0

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -2,16 +2,20 @@
 
 # @api private
 # @since 1.0.0
+# @version 1.7.0
 # rubocop:disable Metrics/ModuleLength
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
 # rubocop:disable Metrics/BlockNesting
 # rubocop:disable Style/IfInsideElse
 module RedisQueuedLocks::Acquier::AcquireLock
+  require_relative 'acquire_lock/log_visitor'
+  require_relative 'acquire_lock/instr_visitor'
   require_relative 'acquire_lock/delay_execution'
   require_relative 'acquire_lock/with_acq_timeout'
   require_relative 'acquire_lock/yield_expire'
   require_relative 'acquire_lock/try_to_lock'
+  require_relative 'acquire_lock/dequeue_from_lock_queue'
 
   # @since 1.0.0
   extend TryToLock
@@ -21,8 +25,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
   extend YieldExpire
   # @since 1.0.0
   extend WithAcqTimeout
-  # @since 1.0.0
-  extend RedisQueuedLocks::Utilities
+  # @since 1.7.0
+  extend DequeueFromLockQueue
 
   class << self
     # @param redis [RedisClient]
@@ -86,6 +90,16 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
+    # @option access_strategy [Symbol]
+    #   - The way in which the lock will be obtained;
+    #   - By default it uses `:queued` strategy;
+    #   - Supports following strategies:
+    #     - `:queued` (FIFO): the classic queued behavior (default), your lock will be
+    #       obitaned if you are first in queue and the required lock is free;
+    #     - `:random` (RANDOM): obtain a lock without checking the positions in the queue
+    #       (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 log_sampling_enabled [Boolean]
     #   - enables <log sampling>: only the configured percent of RQL cases will be logged;
     #   - disabled by default;
@@ -129,7 +143,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.6.0
+    # @version 1.7.0
     def acquire_lock(
       redis,
       lock_name,
@@ -153,6 +167,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
+      access_strategy:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,
@@ -236,19 +251,16 @@ module RedisQueuedLocks::Acquier::AcquireLock
           lock_key_queue,
           queue_ttl,
           acquier_id,
+          access_strategy,
           log_sampled,
           instr_sampled
         )
       end
 
-      run_non_critical do
-        logger.debug do
-          "[redis_queued_locks.start_lock_obtaining] " \
-          "lock_key => '#{lock_key}' " \
-          "queue_ttl => #{queue_ttl} " \
-          "acq_id => '#{acquier_id}'"
-        end
-      end if log_sampled
+      LogVisitor.start_lock_obtaining(
+        logger, log_sampled,
+        lock_key, queue_ttl, acquier_id, access_strategy
+      )
 
       # Step 2: try to lock with timeout
       with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
@@ -256,28 +268,21 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
         # Step 2.1: cyclically try to obtain the lock
         while acq_process[:should_try]
-          run_non_critical do
-            logger.debug do
-              "[redis_queued_locks.start_try_to_lock_cycle] " \
-              "lock_key => '#{lock_key}' " \
-              "queue_ttl => #{queue_ttl} " \
-              "acq_id => '{#{acquier_id}'"
-            end
-          end if log_sampled
+
+          LogVisitor.start_try_to_lock_cycle(
+            logger, log_sampled,
+            lock_key, queue_ttl, acquier_id, access_strategy
+          )
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
           if RedisQueuedLocks::Resource.dead_score_reached?(acquier_position, queue_ttl)
             # Step 2.X.X: dead score reached => re-queue the lock request with the new score;
             acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
 
-            run_non_critical do
-              logger.debug do
-                "[redis_queued_locks.dead_score_reached__reset_acquier_position] " \
-                "lock_key => '#{lock_key} " \
-                "queue_ttl => #{queue_ttl} " \
-                "acq_id => '#{acquier_id}'"
-              end
-            end if log_sampled
+            LogVisitor.dead_score_reached__reset_acquier_position(
+              logger, log_sampled,
+              lock_key, queue_ttl, acquier_id, access_strategy
+            )
           end
 
           try_to_lock(
@@ -292,6 +297,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
             queue_ttl,
             fail_fast,
             conflict_strategy,
+            access_strategy,
             meta,
             log_sampled,
             instr_sampled
@@ -309,72 +315,38 @@ module RedisQueuedLocks::Acquier::AcquireLock
             # Step X: (instrumentation)
             if acq_process[:result][:process] == :extendable_conflict_work_through
               # instrumetnation: (reentrant lock with ttl extension)
-              run_non_critical do
-                logger.debug do
-                  "[redis_queued_locks.extendable_reentrant_lock_obtained] " \
-                  "lock_key => '#{result[:lock_key]}' " \
-                  "queue_ttl => #{queue_ttl} " \
-                  "acq_id => '#{acquier_id}' " \
-                  "acq_time => #{acq_time} (ms)"
-                end
-              end if log_sampled
-
-              run_non_critical do
-                instrumenter.notify('redis_queued_locks.extendable_reentrant_lock_obtained', {
-                  lock_key: result[:lock_key],
-                  ttl: result[:ttl],
-                  acq_id: result[:acq_id],
-                  ts: result[:ts],
-                  acq_time: acq_time,
-                  instrument:
-                })
-              end if instr_sampled
+              LogVisitor.extendable_reentrant_lock_obtained(
+                logger, log_sampled,
+                result[:lock_key], queue_ttl, acquier_id, acq_time, access_strategy
+              )
+              InstrVisitor.extendable_reentrant_lock_obtained(
+                instrumenter, instr_sampled,
+                result[:lock_key], result[:ttl], result[:acq_id], result[:ts], acq_time,
+                instrument
+              )
             elsif acq_process[:result][:process] == :conflict_work_through
               # instrumetnation: (reentrant lock without ttl extension)
-              run_non_critical do
-                logger.debug do
-                  "[redis_queued_locks.reentrant_lock_obtained] " \
-                  "lock_key => '#{result[:lock_key]}' " \
-                  "queue_ttl => #{queue_ttl} " \
-                  "acq_id => '#{acquier_id}' " \
-                  "acq_time => #{acq_time} (ms)"
-                end
-              end if log_sampled
-
-              run_non_critical do
-                instrumenter.notify('redis_queued_locks.reentrant_lock_obtained', {
-                  lock_key: result[:lock_key],
-                  ttl: result[:ttl],
-                  acq_id: result[:acq_id],
-                  ts: result[:ts],
-                  acq_time: acq_time,
-                  instrument:
-                })
-              end if instr_sampled
+              LogVisitor.reentrant_lock_obtained(
+                logger, log_sampled,
+                result[:lock_key], queue_ttl, acquier_id, acq_time, access_strategy
+              )
+              InstrVisitor.reentrant_lock_obtained(
+                instrumenter, instr_sampled,
+                result[:lock_key], result[:ttl], result[:acq_id], result[:ts], acq_time,
+                instrument
+              )
             else
               # instrumentation: (classic lock obtain)
               # NOTE: classic is: acq_process[:result][:process] == :lock_obtaining
-              run_non_critical do
-                logger.debug do
-                  "[redis_queued_locks.lock_obtained] " \
-                  "lock_key => '#{result[:lock_key]}' " \
-                  "queue_ttl => #{queue_ttl} " \
-                  "acq_id => '#{acquier_id}' " \
-                  "acq_time => #{acq_time} (ms)"
-                end
-              end if log_sampled
-
-              # Step X (instrumentation): lock obtained
-              run_non_critical do
-                instrumenter.notify('redis_queued_locks.lock_obtained', {
-                  lock_key: result[:lock_key],
-                  ttl: result[:ttl],
-                  acq_id: result[:acq_id],
-                  ts: result[:ts],
-                  acq_time: acq_time,
-                  instrument:
-                })
-              end if instr_sampled
+              LogVisitor.lock_obtained(
+                logger, log_sampled,
+                result[:lock_key], queue_ttl, acquier_id, acq_time, access_strategy
+              )
+              InstrVisitor.lock_obtained(
+                instrumenter, instr_sampled,
+                result[:lock_key], result[:ttl], result[:acq_id], result[:ts], acq_time,
+                instrument
+              )
             end
 
             # Step 2.1.a: successfully acquired => build the result
@@ -478,6 +450,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               logger,
               lock_key,
               acquier_id,
+              access_strategy,
               timed,
               ttl_shift,
               ttl,
@@ -499,30 +472,30 @@ module RedisQueuedLocks::Acquier::AcquireLock
             if acq_process[:result][:process] == :extendable_conflict_work_through ||
                acq_process[:result][:process] == :conflict_work_through
               # Step X (instrumentation): reentrant_lock_hold_completes
-              run_non_critical do
-                instrumenter.notify('redis_queued_locks.reentrant_lock_hold_completes', {
-                  hold_time: acq_process[:hold_time],
-                  ttl: acq_process[:lock_info][:ttl],
-                  acq_id: acq_process[:lock_info][:acq_id],
-                  ts: acq_process[:lock_info][:ts],
-                  lock_key: acq_process[:lock_info][:lock_key],
-                  acq_time: acq_process[:acq_time],
-                  instrument:
-                })
-              end if instr_sampled
+              InstrVisitor.reentrant_lock_hold_completes(
+                instrumenter,
+                instr_sampled,
+                acq_process[:lock_info][:lock_key],
+                acq_process[:lock_info][:ttl],
+                acq_process[:lock_info][:acq_id],
+                acq_process[:lock_info][:ts],
+                acq_process[:acq_time],
+                acq_process[:hold_time],
+                instrument
+              )
             else
               # Step X (instrumentation): lock_hold_and_release
-              run_non_critical do
-                instrumenter.notify('redis_queued_locks.lock_hold_and_release', {
-                  hold_time: acq_process[:hold_time],
-                  ttl: acq_process[:lock_info][:ttl],
-                  acq_id: acq_process[:lock_info][:acq_id],
-                  ts: acq_process[:lock_info][:ts],
-                  lock_key: acq_process[:lock_info][:lock_key],
-                  acq_time: acq_process[:acq_time],
-                  instrument:
-                })
-              end if instr_sampled
+              InstrVisitor.lock_hold_and_release(
+                instrumenter,
+                instr_sampled,
+                acq_process[:lock_info][:lock_key],
+                acq_process[:lock_info][:ttl],
+                acq_process[:lock_info][:acq_id],
+                acq_process[:lock_info][:ts],
+                acq_process[:lock_info][:lock_key],
+                acq_process[:acq_time],
+                instrument
+              )
             end
           end
         else

data/lib/redis_queued_locks/client.rb

@@ -23,6 +23,7 @@ class RedisQueuedLocks::Client
     setting :dead_request_ttl, (1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds
     setting :is_timed_by_default, false
     setting :default_conflict_strategy, :wait_for_lock
+    setting :default_access_strategy, :queued
     setting :log_sampling_enabled, false
     setting :log_sampling_percent, 15
     setting :log_sampler, RedisQueuedLocks::Logging::Sampler
@@ -57,6 +58,12 @@ class RedisQueuedLocks::Client
       val == :dead_locking
       # rubocop:enable Layout/MultilineOperationIndentation
     end
+    validate('default_access_strategy') do |val|
+      # rubocop:disable Layout/MultilineOperationIndentation
+      val == :queued ||
+      val == :random
+      # rubocop:enable Layout/MultilineOperationIndentation
+    end
   end
 
   # @return [RedisClient]
@@ -126,6 +133,16 @@ class RedisQueuedLocks::Client
   #     - `:wait_for_lock` - (default) - work in classic way
   #       (with timeouts, retry delays, retry limits, etc - in classic way :));
   #     - `:dead_locking` - fail with deadlock exception;
+  # @option access_strategy [Symbol]
+  #   - The way in which the lock will be obtained;
+  #   - By default it uses `:queued` strategy;
+  #   - Supports following strategies:
+  #     - `:queued` (FIFO): the classic queued behavior (default), your lock will be
+  #       obitaned if you are first in queue and the required lock is free;
+  #     - `:random` (RANDOM): obtain a lock without checking the positions in the queue
+  #       (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 meta [NilClass,Hash<String|Symbol,Any>]
   #   - A custom metadata wich will be passed to the lock data in addition to the existing data;
   #   - Metadata can not contain reserved lock data keys;
@@ -189,7 +206,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.7.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
@@ -203,6 +220,7 @@ class RedisQueuedLocks::Client
     raise_errors: false,
     fail_fast: false,
     conflict_strategy: config[:default_conflict_strategy],
+    access_strategy: config[:default_access_strategy],
     identity: uniq_identity,
     meta: nil,
     logger: config[:logger],
@@ -236,6 +254,7 @@ class RedisQueuedLocks::Client
       identity:,
       fail_fast:,
       conflict_strategy:,
+      access_strategy:,
       meta:,
       logger:,
       log_lock_try:,
@@ -255,7 +274,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.7.0
   # rubocop:disable Metrics/MethodLength
   def lock!(
     lock_name,
@@ -268,6 +287,7 @@ class RedisQueuedLocks::Client
     retry_jitter: config[:retry_jitter],
     fail_fast: false,
     conflict_strategy: config[:default_conflict_strategy],
+    access_strategy: config[:default_access_strategy],
     identity: uniq_identity,
     instrumenter: config[:instrumenter],
     meta: nil,
@@ -300,6 +320,7 @@ class RedisQueuedLocks::Client
       instrument:,
       instrumenter:,
       conflict_strategy:,
+      access_strategy:,
       log_sampling_enabled:,
       log_sampling_percent:,
       log_sampler:,

data/lib/redis_queued_locks/utilities.rb

@@ -2,7 +2,6 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.5.0
 module RedisQueuedLocks::Utilities
   module_function
 

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.6.0
-  VERSION = '1.6.0'
+  # @version 1.7.0
+  VERSION = '1.7.0'
 end

data/lib/redis_queued_locks/watcher.rb

@@ -0,0 +1 @@
+# frozen_string_literal: true

data/redis_queued_locks.gemspec

@@ -10,9 +10,29 @@ Gem::Specification.new do |spec|
   spec.authors = ['Rustam Ibragimov']
   spec.email   = ['iamdaiver@gmail.com']
 
-  spec.summary     = 'Queued distributed locks based on Redis.'
-  spec.description = 'Distributed locks with "lock acquisition queue" ' \
-                     'capabilities based on the Redis Database.'
+  spec.summary =
+    'Distributed locks with "prioritized lock acquisition queue" ' \
+    'capabilities based on the Redis Database.'
+
+  spec.description =
+    'Distributed locks with "prioritized lock acquisition queue" capabilities ' \
+    'based on the Redis Database. ' \
+    # ---
+    'Each lock request is put into the request queue ' \
+    "(each lock is hosted by it's own queue separately from other queues) and processed " \
+    'in order of their priority (FIFO). ' \
+    # ---
+    'Each lock request lives some period of time (RTTL) ' \
+    '(with requeue capabilities) which guarantees the request queue will never be stacked. ' \
+    # ---
+    'In addition to the classic `queued` (FIFO) strategy RQL supports ' \
+    '`random` (RANDOM) lock obtaining strategy when any acquirer from the lock queue ' \
+    'can obtain the lock regardless the position in the queue. ' \
+    # ---
+    'Provides flexible invocation flow, parametrized limits ' \
+    '(lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), ' \
+    'logging and instrumentation.'
+
   spec.homepage    = 'https://github.com/0exp/redis_queued_locks'
   spec.license     = 'MIT'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-25 00:00:00.000000000 Z
+date: 2024-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.28'
-description: Distributed locks with "lock acquisition queue" capabilities based on
-  the Redis Database.
+description: 'Distributed locks with "prioritized lock acquisition queue" capabilities
+  based on the Redis Database. '
 email:
 - iamdaiver@gmail.com
 executables: []
@@ -58,9 +58,15 @@ files:
 - lib/redis_queued_locks/acquier.rb
 - lib/redis_queued_locks/acquier/acquire_lock.rb
 - lib/redis_queued_locks/acquier/acquire_lock/delay_execution.rb
+- lib/redis_queued_locks/acquier/acquire_lock/dequeue_from_lock_queue.rb
+- lib/redis_queued_locks/acquier/acquire_lock/dequeue_from_lock_queue/log_visitor.rb
+- lib/redis_queued_locks/acquier/acquire_lock/instr_visitor.rb
+- lib/redis_queued_locks/acquier/acquire_lock/log_visitor.rb
 - lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb
+- lib/redis_queued_locks/acquier/acquire_lock/try_to_lock/log_visitor.rb
 - lib/redis_queued_locks/acquier/acquire_lock/with_acq_timeout.rb
 - lib/redis_queued_locks/acquier/acquire_lock/yield_expire.rb
+- lib/redis_queued_locks/acquier/acquire_lock/yield_expire/log_visitor.rb
 - lib/redis_queued_locks/acquier/clear_dead_requests.rb
 - lib/redis_queued_locks/acquier/extend_lock_ttl.rb
 - lib/redis_queued_locks/acquier/is_locked.rb
@@ -87,6 +93,7 @@ files:
 - lib/redis_queued_locks/resource.rb
 - lib/redis_queued_locks/utilities.rb
 - lib/redis_queued_locks/version.rb
+- lib/redis_queued_locks/watcher.rb
 - redis_queued_locks.gemspec
 homepage: https://github.com/0exp/redis_queued_locks
 licenses:
@@ -113,5 +120,6 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
-summary: Queued distributed locks based on Redis.
+summary: Distributed locks with "prioritized lock acquisition queue" capabilities
+  based on the Redis Database.
 test_files: []