redis_queued_locks 0.0.38 → 0.0.40

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -23,8 +23,8 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
-    #   Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean<Hash<Symbol,Numeric|String|Symbol>>]
+    #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
     # @since 0.1.0
@@ -34,7 +34,7 @@ module RedisQueuedLocks::Acquier::ReleaseLock
 
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_lock(redis, lock_key, lock_key_queue) => { ok:, result: }
-      time_at = Time.now.to_i
+      time_at = Time.now.to_f
       rel_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       rel_time = ((rel_end_time - rel_start_time) * 1_000).ceil(2)
 
@@ -49,7 +49,13 @@ module RedisQueuedLocks::Acquier::ReleaseLock
 
       RedisQueuedLocks::Data[
         ok: true,
-        result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue }
+        result: {
+          rel_time: rel_time,
+          rel_key: lock_key,
+          rel_queue: lock_key_queue,
+          queue_res: result[:queue],
+          lock_res: result[:lock]
+        }
       ]
     end
 
@@ -60,7 +66,14 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param redis [RedisClient]
     # @param lock_key [String]
     # @param lock_key_queue [String]
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Symbol>>]
+    #   Format: {
+    #     ok: true/false,
+    #     result: {
+    #       queue: :released/:nothing_to_release,
+    #       lock: :released/:nothing_to_release
+    #     }
+    #   }
     #
     # @api private
     # @since 0.1.0
@@ -72,7 +85,13 @@ module RedisQueuedLocks::Acquier::ReleaseLock
         end
       end
 
-      RedisQueuedLocks::Data[ok: true, result:]
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: {
+          queue: (result[0] != 0) ? :released : :nothing_to_release,
+          lock: (result[1] != 0) ? :released : :nothing_to_release
+        }
+      ]
     end
   end
 end

data/lib/redis_queued_locks/acquier.rb

@@ -14,4 +14,5 @@ module RedisQueuedLocks::Acquier
   require_relative 'acquier/queues'
   require_relative 'acquier/keys'
   require_relative 'acquier/extend_lock_ttl'
+  require_relative 'acquier/clear_dead_requests'
 end

data/lib/redis_queued_locks/client.rb

@@ -20,6 +20,8 @@ class RedisQueuedLocks::Client
     setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
     setting :logger, RedisQueuedLocks::Logging::VoidLogger
     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
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -32,6 +34,8 @@ class RedisQueuedLocks::Client
     validate('uniq_identifier', :proc)
     validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
     validate('log_lock_try', :boolean)
+    validate('dead_request_ttl') { |val| val.is_a?(::Integer) && val > 0 }
+    validate('is_timed_by_default', :boolean)
   end
 
   # @return [RedisClient]
@@ -40,15 +44,14 @@ class RedisQueuedLocks::Client
   # @since 0.1.0
   attr_reader :redis_client
 
+  # NOTE: attr_access here is chosen intentionally in order to have an ability to change
+  #  uniq_identity value for debug purposes in runtime;
   # @return [String]
   #
   # @api private
   # @since 0.1.0
   attr_accessor :uniq_identity
 
-  # NOTE: attr_access is chosen intentionally in order to have an ability to change
-  #  uniq_identity values for debug purposes in runtime;
-
   # @param redis_client [RedisClient]
   #   Redis connection manager, which will be used for the lock acquierment and distribution.
   #   It should be an instance of RedisClient.
@@ -119,7 +122,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
-    timed: false,
+    timed: config[:is_timed_by_default],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -167,7 +170,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
-    timed: false,
+    timed: config[:is_timed_by_default],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -191,20 +194,38 @@ class RedisQueuedLocks::Client
       raise_errors: true,
       identity:,
       fail_fast:,
+      logger:,
+      log_lock_try:,
       meta:,
       instrument:,
       &block
     )
   end
 
-  # @param lock_name [String]
-  #   The lock name that should be released.
+  # @param lock_name [String] The lock name that should be released.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
   # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  #   Format: {
+  #     ok: true/false,
+  #     result: {
+  #       rel_time: Integer, # <millisecnds>
+  #       rel_key: String, # lock key
+  #       rel_queue: String, # lock queue
+  #       queue_res: Symbol, # :released or :nothing_to_release
+  #       lock_res: Symbol # :released or :nothing_to_release
+  #     }
+  #   }
   #
   # @api public
   # @since 0.1.0
-  def unlock(lock_name)
+  def unlock(
+    lock_name,
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
     RedisQueuedLocks::Acquier::ReleaseLock.release_lock(
       redis_client,
       lock_name,
@@ -249,33 +270,60 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquier::QueueInfo.queue_info(redis_client, lock_name)
   end
 
+  # This method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension.
+  # So the methid is spliited into the two commands:
+  #   (1) read current pttl
+  #   (2) set new ttl that is calculated as "current pttl + additional milliseconds"
+  # What can happen during these steps
+  # - lock is expired between commands or before the first command;
+  # - lock is expired before the second command;
+  # - lock is expired AND newly acquired by another process (so you will extend the
+  #   totally new lock with fresh PTTL);
+  # Use it at your own risk and consider async nature when calling this method.
+  #
   # @param lock_name [String]
   # @param milliseconds [Integer] How many milliseconds should be added.
-  # @return [?]
+  # @return [Hash<Symbol,Boolean|Symbol>]
+  #   - { ok: true, result: :ttl_extended }
+  #   - { ok: false, result: :async_expire_or_no_lock }
   #
   # @api public
   # @since 0.1.0
-  def extend_lock_ttl(lock_name, milliseconds)
+  def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
       lock_name,
       milliseconds,
-      config[:logger]
+      logger
     )
   end
 
+  # Releases all queues and locks.
+  # Returns:
+  #   - :rel_time - (milliseconds) - time spent to release all locks and queues;
+  #   - :rel_key_cnt - (integer) - the number of released redis keys (queus+locks);
+  #
   # @option batch_size [Integer]
-  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Numeric>>]
+  #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
   # @since 0.1.0
-  def clear_locks(batch_size: config[:lock_release_batch_size])
+  def clear_locks(
+    batch_size: config[:lock_release_batch_size],
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
     RedisQueuedLocks::Acquier::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
-      config[:instrumenter],
-      config[:logger]
+      logger,
+      instrumenter,
+      instrument
     )
   end
 
@@ -352,5 +400,36 @@ class RedisQueuedLocks::Client
   def keys(scan_size: config[:key_extraction_batch_size])
     RedisQueuedLocks::Acquier::Keys.keys(redis_client, scan_size:)
   end
+
+  # @option dead_ttl [Integer]
+  #  - the time period (in millsiecnds) after whcih the lock request is
+  #    considered as dead;
+  #  - `config[:dead_request_ttl]` is used by default;
+  # @option scan_size [Integer]
+  #   The batch of scanned keys for Redis'es SCAN command.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
+  # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
+  #   Format: { ok: true, result: { processed_queus: Set<String> } }
+  #
+  # @api public
+  # @since 0.1.0
+  def clear_dead_requests(
+    dead_ttl: config[:dead_request_ttl],
+    scan_size: config[:key_extraction_batch_size],
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
+    RedisQueuedLocks::Acquier::ClearDeadRequests.clear_dead_requests(
+      redis_client,
+      scan_size,
+      dead_ttl,
+      logger,
+      instrumenter,
+      instrument
+    )
+  end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/data.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-# NOTE: wiill be rewritten with Ruby's 3.2 "Data" class;
 class RedisQueuedLocks::Data < Hash
 end

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.38
+  version: 0.0.40
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-28 00:00:00.000000000 Z
+date: 2024-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -61,6 +61,7 @@ files:
 - lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb
 - lib/redis_queued_locks/acquier/acquire_lock/with_acq_timeout.rb
 - lib/redis_queued_locks/acquier/acquire_lock/yield_with_expire.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
 - lib/redis_queued_locks/acquier/is_queued.rb
@@ -107,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.1
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Queued distributed locks based on Redis.