redis_queued_locks 1.1.0 → 1.3.0

data/lib/redis_queued_locks/acquier/queues.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::Queues
   class << self
     # @param redis_client [RedisClient]
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<String>,Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def queues(redis_client, scan_size:, with_info:)
       redis_client.with do |rconn|
         lock_queues = scan_queues(rconn, scan_size)
@@ -25,7 +25,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<String>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def scan_queues(redis_client, scan_size)
       Set.new.tap do |lock_queues|
         redis_client.scan(
@@ -44,7 +44,7 @@ module RedisQueuedLocks::Acquier::Queues
     # @return [Set<Hash<Symbol,Any>>]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def extract_queues_info(redis_client, lock_queues)
       # TODO: refactor with RedisQueuedLocks::Acquier::QueueInfo
       Set.new.tap do |seeded_queues|

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ReleaseAllLocks
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   class << self
@@ -27,7 +27,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   Format: { ok: true, result: Hash<Symbol,Numeric> }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def release_all_locks(redis, batch_size, logger, instrumenter, instrument)
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
@@ -59,7 +59,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   - Exmaple: { ok: true, result: { rel_key_cnt: 12345 } }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def fully_release_all_locks(redis, batch_size)
       result = redis.with do |rconn|
         rconn.pipelined do |pipeline|

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::ReleaseLock
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
   class << self
@@ -27,7 +27,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def release_lock(redis, lock_name, instrumenter, logger)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
@@ -76,7 +76,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     #   }
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def fully_release_lock(redis, lock_key, lock_key_queue)
       result = redis.with do |rconn|
         rconn.multi do |transact|

data/lib/redis_queued_locks/acquier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier
   require_relative 'acquier/acquire_lock'
   require_relative 'acquier/release_lock'

data/lib/redis_queued_locks/client.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
-  # @since 0.1.0
+  # @since 1.0.0
   include Qonfig::Configurable
 
   configuration do
@@ -22,6 +22,7 @@ class RedisQueuedLocks::Client
     setting :log_lock_try, false
     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
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -36,12 +37,20 @@ class RedisQueuedLocks::Client
     validate('log_lock_try', :boolean)
     validate('dead_request_ttl') { |val| val.is_a?(::Integer) && val > 0 }
     validate('is_timed_by_default', :boolean)
+    validate('default_conflict_strategy') do |val|
+      # rubocop:disable Layout/MultilineOperationIndentation
+      val == :work_through ||
+      val == :extendable_work_through ||
+      val == :wait_for_lock ||
+      val == :dead_locking
+      # rubocop:enable Layout/MultilineOperationIndentation
+    end
   end
 
   # @return [RedisClient]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   attr_reader :redis_client
 
   # NOTE: attr_access here is chosen intentionally in order to have an ability to change
@@ -49,7 +58,7 @@ class RedisQueuedLocks::Client
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   attr_accessor :uniq_identity
 
   # @param redis_client [RedisClient]
@@ -60,7 +69,7 @@ class RedisQueuedLocks::Client
   # @return [void]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def initialize(redis_client, &configs)
     configure(&configs)
     @uniq_identity = config[:uniq_identifier].call
@@ -96,19 +105,31 @@ class RedisQueuedLocks::Client
   #   already obtained;
   #   - Should the logic exit immidietly after the first try if the lock was obtained
   #   by another process while the lock request queue was initially empty;
+  # @option conflict_strategy [Symbol]
+  #   - The conflict strategy mode for cases when the process that obtained the lock
+  #     want to acquire this lock again;
+  #   - By default uses `:wait_for_lock` strategy;
+  #   - pre-confured in `config[:default_conflict_strategy]`;
+  #   - Supports:
+  #     - `:work_through` - continue working under the lock without lock's TTL extension;
+  #     - `:extendable_work_through` - continue working under the lock with lock's TTL extension;
+  #     - `: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 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;
   # @option logger [::Logger,#debug]
   #   - Logger object used from the configuration layer (see config[:logger]);
   #   - See `RedisQueuedLocks::Logging::VoidLogger` for example;
+  #   - Supports `SemanticLogger::Logger` (see "semantic_logger" gem)
   # @option log_lock_try [Boolean]
   #   - should be logged the each try of lock acquiring (a lot of logs can
   #     be generated depending on your retry configurations);
   #   - see `config[:log_lock_try]`;
   # @option instrument [NilClass,Any]
-  #    - Custom instrumentation data wich will be passed to the instrumenter's payload
-  #      with :instrument key;
+  #   - Custom instrumentation data wich will be passed to the instrumenter's payload
+  #     with :instrument key;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
@@ -116,7 +137,8 @@ class RedisQueuedLocks::Client
   #   - If block is given the result of block's yeld will be returned.
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.3.0
   def lock(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -128,6 +150,7 @@ class RedisQueuedLocks::Client
     retry_jitter: config[:retry_jitter],
     raise_errors: false,
     fail_fast: false,
+    conflict_strategy: config[:default_conflict_strategy],
     identity: uniq_identity,
     meta: nil,
     logger: config[:logger],
@@ -153,6 +176,7 @@ class RedisQueuedLocks::Client
       instrumenter: config[:instrumenter],
       identity:,
       fail_fast:,
+      conflict_strategy:,
       meta:,
       logger: config[:logger],
       log_lock_try: config[:log_lock_try],
@@ -164,7 +188,8 @@ class RedisQueuedLocks::Client
   # @note See #lock method signature.
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.3.0
   def lock!(
     lock_name,
     ttl: config[:default_lock_ttl],
@@ -175,6 +200,7 @@ class RedisQueuedLocks::Client
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
     fail_fast: false,
+    conflict_strategy: config[:default_conflict_strategy],
     identity: uniq_identity,
     meta: nil,
     logger: config[:logger],
@@ -198,6 +224,7 @@ class RedisQueuedLocks::Client
       log_lock_try:,
       meta:,
       instrument:,
+      conflict_strategy:,
       &block
     )
   end
@@ -219,7 +246,7 @@ class RedisQueuedLocks::Client
   #   }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def unlock(
     lock_name,
     logger: config[:logger],
@@ -238,7 +265,7 @@ class RedisQueuedLocks::Client
   # @return [Boolean]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locked?(lock_name)
     RedisQueuedLocks::Acquier::IsLocked.locked?(redis_client, lock_name)
   end
@@ -247,7 +274,7 @@ class RedisQueuedLocks::Client
   # @return [Boolean]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queued?(lock_name)
     RedisQueuedLocks::Acquier::IsQueued.queued?(redis_client, lock_name)
   end
@@ -256,7 +283,7 @@ class RedisQueuedLocks::Client
   # @return [Hash<String,String|Numeric>,NilClass]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def lock_info(lock_name)
     RedisQueuedLocks::Acquier::LockInfo.lock_info(redis_client, lock_name)
   end
@@ -265,7 +292,7 @@ class RedisQueuedLocks::Client
   # @return [Hash<String|Array<Hash<String,String|Numeric>>,NilClass]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queue_info(lock_name)
     RedisQueuedLocks::Acquier::QueueInfo.queue_info(redis_client, lock_name)
   end
@@ -288,7 +315,7 @@ class RedisQueuedLocks::Client
   #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
@@ -311,7 +338,7 @@ class RedisQueuedLocks::Client
   #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def clear_locks(
     batch_size: config[:lock_release_batch_size],
     logger: config[:logger],
@@ -345,7 +372,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>,Set<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locks(scan_size: config[:key_extraction_batch_size], with_info: false)
     RedisQueuedLocks::Acquier::Locks.locks(redis_client, scan_size:, with_info:)
   end
@@ -356,7 +383,7 @@ class RedisQueuedLocks::Client
   # @return [Set<Hash<String,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def locks_info(scan_size: config[:key_extraction_batch_size])
     locks(scan_size:, with_info: true)
   end
@@ -376,7 +403,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>,String<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queues(scan_size: config[:key_extraction_batch_size], with_info: false)
     RedisQueuedLocks::Acquier::Queues.queues(redis_client, scan_size:, with_info:)
   end
@@ -387,7 +414,7 @@ class RedisQueuedLocks::Client
   # @return [Set<Hash<Symbol,Any>>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def queues_info(scan_size: config[:key_extraction_batch_size])
     queues(scan_size:, with_info: true)
   end
@@ -396,7 +423,7 @@ class RedisQueuedLocks::Client
   # @return [Set<String>]
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   def keys(scan_size: config[:key_extraction_batch_size])
     RedisQueuedLocks::Acquier::Keys.keys(redis_client, scan_size:)
   end
@@ -415,7 +442,8 @@ class RedisQueuedLocks::Client
   #   Format: { ok: true, result: { processed_queus: Set<String> } }
   #
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.1.0
   def clear_dead_requests(
     dead_ttl: config[:dead_request_ttl],
     scan_size: config[:lock_release_batch_size],

data/lib/redis_queued_locks/debugger/interface.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Debugger::Interface
   # @param message [String]
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def debug(message)
     RedisQueuedLocks::Debugger.debug(message)
   end
@@ -15,7 +15,7 @@ module RedisQueuedLocks::Debugger::Interface
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def enable_debugger!
     RedisQueuedLocks::Debugger.enable!
   end
@@ -23,7 +23,7 @@ module RedisQueuedLocks::Debugger::Interface
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def disable_debugger!
     RedisQueuedLocks::Debugger.disable!
   end

data/lib/redis_queued_locks/debugger.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Debugger
   require_relative 'debugger/interface'
 
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   DEBUG_ENABLED_METHOD = <<~METHOD_DECLARATION.strip.freeze
     def debug(message) = STDOUT.write("#\{message}\n")
   METHOD_DECLARATION
@@ -16,20 +16,20 @@ module RedisQueuedLocks::Debugger
   # @return [String]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   DEBUG_DISABLED_MEHTOD = <<~METHOD_DECLARATION.strip.freeze
     def debug(message); end
   METHOD_DECLARATION
 
   class << self
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     instance_variable_set(:@enabled, false)
 
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def enable!
       @enabled = true
       eval(DEBUG_ENABLED_METHOD)
@@ -38,7 +38,7 @@ module RedisQueuedLocks::Debugger
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def disable!
       @enabled = false
       eval(DEBUG_DISABLED_MEHTOD)
@@ -47,7 +47,7 @@ module RedisQueuedLocks::Debugger
     # @return [Boolean]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def enabled?
       @enabled
     end
@@ -56,7 +56,7 @@ module RedisQueuedLocks::Debugger
     # @return [void]
     #
     # @api private
-    # @since 0.1.0
+    # @since 1.0.0
     def debug(message); end
   end
 end

data/lib/redis_queued_locks/errors.rb

@@ -2,26 +2,30 @@
 
 module RedisQueuedLocks
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   Error = Class.new(::StandardError)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   ArgumentError = Class.new(::ArgumentError)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAlreadyObtainedError = Class.new(Error)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAcquiermentTimeoutError = Class.new(Error)
 
   # @api public
-  # @since 0.1.0
+  # @since 1.0.0
   LockAcquiermentRetryLimitError = Class.new(Error)
 
   # @api pulic
-  # @since 0.1.0
+  # @since 1.0.0
   TimedLockTimeoutError = Class.new(Error)
+
+  # @api public
+  # @since 1.3.0
+  ConflictLockObtainError = Class.new(Error)
 end

data/lib/redis_queued_locks/instrument/active_support.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument::ActiveSupport
   class << self
     # @param event [String]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Instrument::ActiveSupport
     # @return [void]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def notify(event, payload = {})
       ::ActiveSupport::Notifications.instrument(event, payload)
     end

data/lib/redis_queued_locks/instrument/void_notifier.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument::VoidNotifier
   class << self
     # @param event [String]
@@ -9,7 +9,7 @@ module RedisQueuedLocks::Instrument::VoidNotifier
     # @return [void]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def notify(event, payload = {}); end
   end
 end

data/lib/redis_queued_locks/instrument.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Instrument
   require_relative 'instrument/void_notifier'
   require_relative 'instrument/active_support'
@@ -11,7 +11,7 @@ module RedisQueuedLocks::Instrument
     # @return [Boolean]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def valid_interface?(instrumenter)
       if instrumenter == RedisQueuedLocks::Instrument::ActiveSupport
         # NOTE: active_support should be required in your app

data/lib/redis_queued_locks/logging/void_logger.rb

@@ -1,43 +1,43 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Logging::VoidLogger
   class << self
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def warn(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def unknown(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def log(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def info(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def error(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def fatal(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def debug(progname = nil, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def add(*, &block); end
 
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
     def <<(message); end
   end
 end

data/lib/redis_queued_locks/logging.rb

@@ -1,19 +1,26 @@
 # frozen_string_literal: true
 
 # @api public
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Logging
   require_relative 'logging/void_logger'
 
   class << self
-    # @param logger [::Logger,#debug]
+    # @param logger [::Logger,#debug,::SemanticLogger::Logger]
     # @return [Boolean]
     #
     # @api public
-    # @since 0.1.0
+    # @since 1.0.0
+    # @version 1.2.0
     def valid_interface?(logger)
       return true if logger.is_a?(::Logger)
 
+      # NOTE:
+      #   - convinient/conventional way to support the popular `semantic_logger` library
+      #   - see https://logger.rocketjob.io/
+      #   - see https://github.com/reidmorrison/semantic_logger
+      return true if defined?(::SemanticLogger::Logger) && logger.is_a?(::SemanticLogger::Logger)
+
       # NOTE: should provide `#debug` method.
       return false unless logger.respond_to?(:debug)