redis_queued_locks 0.0.17 → 0.0.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb745a97296f4661f7a68d7719d7bdb894521348d6aa25b92b23b4fcffce56cd
-  data.tar.gz: e12566b1c653ad97bf973887d4511482c628d8ec27fd265901d1d4bfba9c112b
+  metadata.gz: c77f863ddb9f33c75a636ea12281ce1f4df1215d50f43b113b5be5f79b679526
+  data.tar.gz: 9585690846e55b141e089d26ac160f6481297cfa6f43d21df1403411903221be
 SHA512:
-  metadata.gz: c3e6f4c421c8e6fb9b3933c01ebcd23d5762f0bdb0581333e2d85ab478a8002d8bce360bfabaab29d819c92a4f148e6562d0fa426e5999b0fc2d1c9b59f3eaa7
-  data.tar.gz: 42a5800757191ea80797c7462b765c5dd4187771ce73c6c9af70f6653dea5599710d8569b5a2fc1a0c30cb0b3483abfac557bd888a7f4bcbde4ac4a7de308021
+  metadata.gz: 9e132a1464d92aa59539d5489d5b7d777399de6c38f313cbad063b819e0e32503591532eb010f5c6b87da41096172e9dde8f5fa2fc84623ca2256b84cd3fa98d
+  data.tar.gz: ea8dc9808a5c16697e5606ce8394c987ceb8df4f561fbf06250bd7669188665f56825a582e9c82240a52b6376767eedda9afeed588f960498fb32070466c512c

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.0.19] - 2024-03-12
+### Added
+- An ability to set the invocation time period to the block of code invoked under
+  the obtained lock;
+
+## [0.0.18] - 2024-03-04
+### Changed
+- Semantic results for methods returning `{ ok: true/false, result: Any }` hash objects.
+  Now these objects are represented as `RedisQueuedLocks::Data` objects inherited from `Hash`;
+
 ## [0.0.17] - 2024-02-29
 ### Added
 - `RedisQueuedLocks::Client#locks` - list of obtained locks;

data/README.md

@@ -1,4 +1,4 @@
-# RedisQueuedLocks · [![Gem Version](https://badge.fury.io/rb/redis_queued_locks.svg)](https://badge.fury.io/rb/redis_queued_locks)
+# RedisQueuedLocks
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
@@ -167,6 +167,7 @@ def lock(
   ttl: config[:default_lock_ttl],
   queue_ttl: config[:default_queue_ttl],
   timeout: config[:try_to_lock_timeout],
+  timed: false,
   retry_count: config[:retry_count],
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
@@ -185,6 +186,8 @@ def lock(
   - Lifetime of the acuier's lock request. In seconds.
 - `timeout` - `[Integer,NilClass]`
   - Time period whe should try to acquire the lock (in seconds). Nil means "without timeout".
+- `timed` - `[Boolean]`
+  - Limit the invocation time period of the passed block of code by the lock's TTL.
 - `retry_count` - `[Integer,NilClass]`
   - How many times we should try to acquire a lock. Nil means "infinite retries".
 - `retry_delay` - `[Integer]`
@@ -244,6 +247,7 @@ Return value:
 #### #lock! - exceptional lock obtaining
 
 - fails when (and with):
+  - (`RedisQueuedLocks::LockAlreadyObtainedError`) when `fail_fast` is `true` and lock is already obtained;
   - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
   - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
 

data/lib/redis_queued_locks/acquier/release.rb

@@ -8,7 +8,7 @@ module RedisQueuedLocks::Acquier::Release
   # @param redis [RedisClient]
   # @param lock_key [String]
   # @param lock_key_queue [String]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
@@ -18,14 +18,14 @@ module RedisQueuedLocks::Acquier::Release
       transact.call('EXPIRE', lock_key, '0')
     end
 
-    { ok: true, result: }
+    RedisQueuedLocks::Data[ok: true, result:]
   end
 
   # Release all locks: clear all lock queus and expire all locks.
   #
   # @param redis [RedisClient]
   # @param batch_size [Integer]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
@@ -55,6 +55,6 @@ module RedisQueuedLocks::Acquier::Release
 
     rel_keys = result.count { |red_res| red_res == 0 }
 
-    { ok: true, result: { rel_keys: rel_keys } }
+    RedisQueuedLocks::Data[ok: true, result: { rel_keys: rel_keys }]
   end
 end

data/lib/redis_queued_locks/acquier/try.rb

@@ -130,13 +130,13 @@ module RedisQueuedLocks::Acquier::Try
     case
     when fail_fast && inter_result == :fail_fast_no_try
       # Step 7.a: lock is still acquired and we should exit from the logic as soon as possible
-      { ok: false, result: inter_result }
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     when inter_result == :lock_is_still_acquired || inter_result == :acquier_is_not_first_in_queue
       # Step 7.b: lock is still acquired by another process => failed to acquire
-      { ok: false, result: inter_result }
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     when result == nil || (result.is_a?(::Array) && result.empty?)
       # Step 7.c: lock is already acquired durign the acquire race => failed to acquire
-      { ok: false, result: :lock_is_acquired_during_acquire_race }
+      RedisQueuedLocks::Data[ok: false, result: :lock_is_acquired_during_acquire_race]
     when result.is_a?(::Array) && result.size == 3 # NOTE: 3 is a count of redis lock commands
       # TODO:
       #   => (!) analyze the command result and do actions with the depending on it;
@@ -147,10 +147,13 @@ module RedisQueuedLocks::Acquier::Try
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.d: locked! :) let's go! => successfully acquired
-      { ok: true, result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl }
+      ]
     else
       # Ste 7.3: unknown behaviour :thinking:
-      { ok: false, result: :unknown }
+      RedisQueuedLocks::Data[ok: false, result: :unknown]
     end
     # rubocop:enable Lint/DuplicateBranch
   end
@@ -170,6 +173,6 @@ module RedisQueuedLocks::Acquier::Try
       "Step ~ [СМЕРТЬ ПРОЦЕССА]: [#{acquier_id} :: #{lock_key_queue}] РЕЗУЛЬТАТ: #{result}"
     )
 
-    { ok: true, result: result }
+    RedisQueuedLocks::Data[ok: true, result: result]
   end
 end

data/lib/redis_queued_locks/acquier/yield_expire.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::YieldExpire
+  # @param redis [RedisClient] Redis connection manager.
+  # @param lock_key [String] Lock key to be expired.
+  # @param timed [Boolean] Should the lock be wrapped by Tiemlout with with lock's ttl
+  # @param ttl_shift [Float] 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 block [Block] Custom logic that should be invoked unter the obtained lock.
+  # @return [Any,NilClass] nil is returned no block parametr is provided.
+  #
+  # @api private
+  # @since 0.1.0
+  def yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
+    if block_given?
+      if timed && ttl != nil
+        timeout = ((ttl - ttl_shift) / 1000.0).yield_self { |time| (time < 0) ? 0.0 : time }
+        yield_with_timeout(timeout, lock_key, ttl, &block)
+      else
+        yield
+      end
+    end
+  ensure
+    redis.call('EXPIRE', lock_key, '0')
+  end
+
+  private
+
+  # @param timeout [Float]
+  # @parma lock_key [String]
+  # @param lock_ttl [Integer,NilClass]
+  # @param block [Blcok]
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def yield_with_timeout(timeout, lock_key, lock_ttl, &block)
+    ::Timeout.timeout(timeout, &block)
+  rescue ::Timeout::Error
+    raise(RedisQueuedLocks::TimedLockTimeoutError, <<~ERROR_MESSAGE)
+      Passed <timed> block of code exceeded the lock TTL (lock: "#{lock_key}", ttl: #{lock_ttl})
+    ERROR_MESSAGE
+  end
+end

data/lib/redis_queued_locks/acquier.rb

@@ -6,7 +6,7 @@
 module RedisQueuedLocks::Acquier
   require_relative 'acquier/try'
   require_relative 'acquier/delay'
-  require_relative 'acquier/expire'
+  require_relative 'acquier/yield_expire'
   require_relative 'acquier/release'
 
   # @since 0.1.0
@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquier
   # @since 0.1.0
   extend Delay
   # @since 0.1.0
-  extend Expire
+  extend YieldExpire
   # @since 0.1.0
   extend Release
 
@@ -44,6 +44,8 @@ module RedisQueuedLocks::Acquier
     #   Lifetime of the acuier's lock request. In seconds.
     # @option timeout [Integer]
     #   Time period whe should try to acquire the lock (in seconds).
+    # @option timed [Boolean]
+    #   Limit the invocation time period of the passed block of code by the lock's TTL.
     # @option retry_count [Integer,NilClass]
     #   How many times we should try to acquire a lock. Nil means "infinite retries".
     # @option retry_delay [Integer]
@@ -63,7 +65,7 @@ module RedisQueuedLocks::Acquier
     #   already obtained.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
-    # @return [Hash<Symbol,Any>,yield]
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
     #  - Format: { ok: true/false, result: Any }
     #  - If block is given the result of block's yeld will be returned.
     #
@@ -80,6 +82,7 @@ module RedisQueuedLocks::Acquier
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
@@ -119,7 +122,7 @@ module RedisQueuedLocks::Acquier
       acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
 
       # Step 2: try to lock with timeout
-      with_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
+      with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
         acq_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
 
         # Step 2.1: caclically try to obtain the lock
@@ -140,6 +143,7 @@ module RedisQueuedLocks::Acquier
 
           # Step X: save the intermediate results to the result observer
           acq_process[:result] = result
+          acq_process[:acq_end_time] = acq_end_time
 
           # Step 2.1: analyze an acquirement attempt
           if ok
@@ -212,7 +216,9 @@ module RedisQueuedLocks::Acquier
         # Step 3.a: acquired successfully => run logic or return the result of acquirement
         if block_given?
           begin
-            yield_with_expire(redis, lock_key, &block)
+            yield_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            ttl_shift = ((yield_time - acq_process[:acq_end_time]) * 1000).ceil(2)
+            yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
           ensure
             acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
             acq_process[:hold_time] = (
@@ -232,7 +238,7 @@ module RedisQueuedLocks::Acquier
             end
           end
         else
-          { ok: true, result: acq_process[:lock_info] }
+          RedisQueuedLocks::Data[ok: true, result: acq_process[:lock_info]]
         end
       else
         if acq_process[:result] != :retry_limit_reached &&
@@ -245,7 +251,7 @@ module RedisQueuedLocks::Acquier
           acq_process[:result] = :timeout_reached
         end
         # Step 3.b: lock is not acquired (acquier is dequeued by timeout callback)
-        { ok: false, result: acq_process[:result] }
+        RedisQueuedLocks::Data[ok: false, result: acq_process[:result]]
       end
     end
     # rubocop:enable Metrics/MethodLength, Metrics/BlockNesting
@@ -257,10 +263,14 @@ module RedisQueuedLocks::Acquier
     # It is safe because the lock obtain logic is transactional and
     # watches the original lock for changes.
     #
-    # @param redis [RedisClient] Redis connection client.
-    # @param lock_name [String] The lock name that should be released.
-    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param lock_name [String]
+    #   The lock name that should be released.
+    # @param isntrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+    #   Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
     #
     # @api private
     # @since 0.1.0
@@ -283,17 +293,24 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue }
+      ]
     end
 
     # Release all locks:
     # - 1. clear all lock queus: drop them all from Redis database by the lock queue pattern;
     # - 2. delete all locks: drop lock keys from Redis by the lock key pattern;
     #
-    # @param redis [RedisClient] Redis connection client.
-    # @param batch_size [Integer] The number of lock keys that should be released in a time.
-    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbol,Numeric> }
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param batch_size [Integer]
+    #   The number of lock keys that should be released in a time.
+    # @param isntrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+    #   Format: { ok: true/false, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 0.1.0
@@ -312,7 +329,10 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time }
+      ]
     end
 
     # @param redis_client [RedisClient]
@@ -512,7 +532,7 @@ module RedisQueuedLocks::Acquier
     #
     # @api private
     # @since 0.1.0
-    def with_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
+    def with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
       ::Timeout.timeout(timeout, &block)
     rescue ::Timeout::Error
       on_timeout.call unless on_timeout == nil

data/lib/redis_queued_locks/client.rb

@@ -71,6 +71,8 @@ class RedisQueuedLocks::Client
   #   Lifetime of the acuier's lock request. In seconds.
   # @option timeout [Integer,NilClass]
   #   Time period whe should try to acquire the lock (in seconds). Nil means "without 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]
   #   How many times we should try to acquire a lock. Nil means "infinite retries".
   # @option retry_delay [Integer]
@@ -92,7 +94,7 @@ class RedisQueuedLocks::Client
   #   by another process while the lock request queue was initially empty;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
-  # @return [Hash<Symbol,Any>,yield]
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
   #   - Format: { ok: true/false, result: Symbol/Hash }.
   #   - If block is given the result of block's yeld will be returned.
   #
@@ -103,6 +105,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
+    timed: false,
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -121,6 +124,7 @@ class RedisQueuedLocks::Client
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
@@ -141,6 +145,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
+    timed: false,
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -153,6 +158,7 @@ class RedisQueuedLocks::Client
       ttl:,
       queue_ttl:,
       timeout:,
+      timed:,
       retry_count:,
       retry_delay:,
       retry_jitter:,
@@ -163,8 +169,10 @@ class RedisQueuedLocks::Client
     )
   end
 
-  # @param lock_name [String] The lock name that should be released.
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
+  # @param lock_name [String]
+  #   The lock name that should be released.
+  # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
+  #   Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
@@ -219,7 +227,8 @@ class RedisQueuedLocks::Client
   end
 
   # @option batch_size [Integer]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+  #   Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0

data/lib/redis_queued_locks/data.rb

@@ -0,0 +1,5 @@
+# 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/errors.rb

@@ -20,4 +20,8 @@ module RedisQueuedLocks
   # @api public
   # @since 0.1.0
   LockAcquiermentRetryLimitError = Class.new(Error)
+
+  # @api pulic
+  # @since 0.1.0
+  TimedLockTimeoutError = Class.new(Error)
 end

data/lib/redis_queued_locks/version.rb

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

data/lib/redis_queued_locks.rb

@@ -10,6 +10,7 @@ require 'securerandom'
 module RedisQueuedLocks
   require_relative 'redis_queued_locks/version'
   require_relative 'redis_queued_locks/errors'
+  require_relative 'redis_queued_locks/data'
   require_relative 'redis_queued_locks/debugger'
   require_relative 'redis_queued_locks/resource'
   require_relative 'redis_queued_locks/acquier'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.17
+  version: 0.0.19
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-29 00:00:00.000000000 Z
+date: 2024-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -57,10 +57,11 @@ files:
 - lib/redis_queued_locks.rb
 - lib/redis_queued_locks/acquier.rb
 - lib/redis_queued_locks/acquier/delay.rb
-- lib/redis_queued_locks/acquier/expire.rb
 - lib/redis_queued_locks/acquier/release.rb
 - lib/redis_queued_locks/acquier/try.rb
+- lib/redis_queued_locks/acquier/yield_expire.rb
 - lib/redis_queued_locks/client.rb
+- lib/redis_queued_locks/data.rb
 - lib/redis_queued_locks/debugger.rb
 - lib/redis_queued_locks/debugger/interface.rb
 - lib/redis_queued_locks/errors.rb

data/lib/redis_queued_locks/acquier/expire.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# @api private
-# @since 0.1.0
-module RedisQueuedLocks::Acquier::Expire
-  # @param redis [RedisClient] Redis connection manager.
-  # @param lock_key [String] Lock key to be expired.
-  # @param block [Block] Custom logic that should be invoked unter the obtained lock.
-  # @return [Any,NilClass] nil is returned no block parametr is provided.
-  #
-  # @api private
-  # @since 0.1.0
-  def yield_with_expire(redis, lock_key, &block)
-    yield if block_given?
-  ensure
-    redis.call('EXPIRE', lock_key, '0')
-  end
-end