redis_queued_locks 0.0.13 → 0.0.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0067915f812330a031b51bc20300a13eee31aa2628aa2b26c90524c58d80ab60'
-  data.tar.gz: f322cbff42c80656ad09d075008c48461db991c153ab04b42e4187f54bcc6bce
+  metadata.gz: 3270e2a14a4eed87379d84fe0622f4a231a681fb1e48325a1d6e22becafb5a60
+  data.tar.gz: b67274aeec060e1bef07d64933928c5be3632cc68f88f12cbe01b9105ae41478
 SHA512:
-  metadata.gz: fbe61d02314ec926529a30cb3771903199897b798f386ff6a5ebb562d3857b92c11d5579a4d6cc9219fa64e152ff1e4f6aeb1ceb98cf8eae094c443b8ec2f6b9
-  data.tar.gz: 3462b766ffb13ca57d21caa7d4725b076a3dc6c594601288f8c7593cb496f58d3ce4b66082035d8ab4bbfa3eba395db475995cacb3a4eb588b03ab06a25eef27
+  metadata.gz: a40531666d37dc44d738fba4e67e027520a58f029c392a46db8a2e465200d4162ad1fdd44e16b17001edab183b8f9f90621d35f6b026a9c2628abc00ab9ea5b3
+  data.tar.gz: 40392bb5de7d615e52e4a92b5f193c7c72970d220a9963ef89346364788c2dc1d11ef5664b20d0864dd3b151aba6a1f6bb76b45cdc5c016882dd51883df25281

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.0.15] - 2024-02-28
+### Added
+- An ability to fail fast if the required lock is already obtained;
+
+## [0.0.14] - 2024-02-28
+### Changed
+- Minor documentation updates;
+
 ## [0.0.13] - 2024-02-27
 ### Changed
 - Minor development updates;

data/README.md

@@ -2,7 +2,7 @@
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
-Each lock request is put into a request queue and processed in order of their priority (FIFO).
+Each lock request is put into the request queue and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
 
 ---
 
@@ -145,6 +145,8 @@ end
 
 - If block is passed the obtained lock will be released after the block execution or the lock's ttl (what will happen first);
 - If block is not passed the obtained lock will be released after lock's ttl;
+- If block is passed the block's yield result will be returned;
+- If block is not passed the lock information will be returned;
 
 ```ruby
 def lock(
@@ -156,6 +158,7 @@ def lock(
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
   raise_errors: false,
+  fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   &block
 )
@@ -179,6 +182,11 @@ def lock(
   - See RedisQueuedLocks::Instrument::ActiveSupport for example.
 - `raise_errors` - `[Boolean]`
   - Raise errors on library-related limits such as timeout or retry count limit.
+- `fail_fast` - `[Boolean]`
+    - Should the required lock to be checked before the try and exit immidietly if lock is
+      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;
 - `identity` - `[String]`
   - An unique string that is unique per `RedisQueuedLock::Client` instance. Resolves the
     collisions between the same process_id/thread_id/fiber_id/ractor_id identifiers on different
@@ -191,25 +199,32 @@ def lock(
   - If block is **not passed** the obtained lock will be released after it's ttl;
 
 Return value:
-- `[Hash<Symbol,Any>]` Format: `{ ok: true/false, result: Symbol/Hash }`;
-- for successful lock obtaining:
-  ```ruby
-  {
-    ok: true,
-    result: {
-      lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
-      acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
-      ts: Integer, # time (epoch) when lock was obtained (integer)
-      ttl: Integer # lock's time to live in milliseconds (integer)
+
+- If block is passed the block's yield result will be returned;
+- If block is not passed the lock information will be returned;
+- Lock information result:
+  - Signature: `[yield, Hash<Symbol,Boolean|Hash<Symbol,Numeric|String>>]`
+  - Format: `{ ok: true/false, result: <Symbol|Hash<Symbol,Hash>> }`;
+  - for successful lock obtaining:
+    ```ruby
+    {
+      ok: true,
+      result: {
+        lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
+        acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
+        ts: Integer, # time (epoch) when lock was obtained (integer)
+        ttl: Integer # lock's time to live in milliseconds (integer)
+      }
     }
-  }
-  ```
-- for failed lock obtaining:
-  ```ruby
-  { ok: false, result: :timeout_reached }
-  { ok: false, result: :retry_count_reached }
-  { ok: false, result: :unknown }
-  ```
+    ```
+  - for failed lock obtaining:
+    ```ruby
+    { ok: false, result: :timeout_reached }
+    { ok: false, result: :retry_count_reached }
+    { ok: false, result: :fail_fast_no_try } # see <fail_fast> option
+    { ok: false, result: :fail_fast_after_try } # see <fail_fast> option
+    { ok: false, result: :unknown }
+    ```
 
 ---
 
@@ -229,6 +244,7 @@ def lock!(
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
   identity: uniq_identity,
+  fail_fast: false,
   &block
 )
 ```
@@ -277,6 +293,14 @@ rql.lock_info("your_lock_name")
     - `acq_id` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity by default);
     - `score` - `float`/`epoch` - time when the lock request was made (epoch);
 
+```
+| Returns an information about the required lock queue by the lock name. The result
+| represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
+| lock acquirers and their position in queue. Async nature with redis communcation can lead
+| the situation when the queue becomes empty during the queue data extraction. So sometimes
+| you can receive the lock queue info with empty queue value (an empty array).
+```
+
 ```ruby
 rql.queue_info("your_lock_name")
 
@@ -327,7 +351,7 @@ def unlock(lock_name)
   - the lock name that should be released.
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
+- `[Hash<Symbol,Numeric|String>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
 
 ```ruby
 {
@@ -352,10 +376,10 @@ def clear_locks(batch_size: config[:lock_release_batch_size])
 ```
 
 - `batch_size` - `[Integer]`
-  - batch of cleared locks and lock queus unde the one pipelined redis command;
+  - the size of batch of locks and lock queus that should be cleared under the one pipelined redis command at once;
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
+- `[Hash<Symbol,Numeric>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
 
 ```ruby
 {
@@ -392,44 +416,44 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 List of instrumentation events
 
-- **redis_queued_locks.lock_obtained**
-- **redis_queued_locks.lock_hold_and_release**
-- **redis_queued_locks.explicit_lock_release**
-- **redis_queued_locks.explicit_all_locks_release**
+- `redis_queued_locks.lock_obtained`
+- `redis_queued_locks.lock_hold_and_release`
+- `redis_queued_locks.explicit_lock_release`
+- `redis_queued_locks.explicit_all_locks_release`
 
 Detalized event semantics and payload structure:
 
 - `"redis_queued_locks.lock_obtained"`
   - a moment when the lock was obtained;
   - payload:
-    - `ttl` - `integer`/`milliseconds` - lock ttl;
-    - `acq_id` - `string` - lock acquier identifier;
-    - `lock_key` - `string` - lock name;
-    - `ts` - `integer`/`epoch` - the time when the lock was obtaiend;
-    - `acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+    - `:ttl` - `integer`/`milliseconds` - lock ttl;
+    - `:acq_id` - `string` - lock acquier identifier;
+    - `:lock_key` - `string` - lock name;
+    - `:ts` - `integer`/`epoch` - the time when the lock was obtaiend;
+    - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
 - `"redis_queued_locks.lock_hold_and_release"`
   - an event signalizes about the "hold+and+release" process
     when the lock obtained and hold by the block of logic;
   - payload:
-    - `hold_time` - `float`/`milliseconds` - lock hold time;
-    - `ttl` - `integer`/`milliseconds` - lock ttl;
-    - `acq_id` - `string` - lock acquier identifier;
-    - `lock_key` - `string` - lock name;
-    - `ts` - `integer`/`epoch` - the time when lock was obtained;
-    - `acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+    - `:hold_time` - `float`/`milliseconds` - lock hold time;
+    - `:ttl` - `integer`/`milliseconds` - lock ttl;
+    - `:acq_id` - `string` - lock acquier identifier;
+    - `:lock_key` - `string` - lock name;
+    - `:ts` - `integer`/`epoch` - the time when lock was obtained;
+    - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
   - payload:
-    - `at` - `integer`/`epoch` - the time when the lock was released;
-    - `rel_time` - `float`/`milliseconds` - time spent on lock releasing;
-    - `lock_key` - `string` - released lock (lock name);
-    - `lock_key_queue` - `string` - released lock queue (lock queue name);
+    - `:at` - `integer`/`epoch` - the time when the lock was released;
+    - `:rel_time` - `float`/`milliseconds` - time spent on lock releasing;
+    - `:lock_key` - `string` - released lock (lock name);
+    - `:lock_key_queue` - `string` - released lock queue (lock queue name);
 - `"redis_queued_locks.explicit_all_locks_release"`
   - an event signalizes about the explicit all locks release (invoked via `RedisQueuedLock#clear_locks`);
   - payload:
-    - `rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
-    - `at` - `integer`/`epoch` - the time when the operation has ended;
-    - `rel_keys` - `integer` - released redis keys count (`released queue keys` + `released lock keys`);
+    - `:rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
+    - `:at` - `integer`/`epoch` - the time when the operation has ended;
+    - `:rel_keys` - `integer` - released redis keys count (`released queue keys` + `released lock keys`);
 
 ---
 
@@ -438,7 +462,10 @@ Detalized event semantics and payload structure:
 - **Major**
   - Semantic Error objects for unexpected Redis errors;
   - `100%` test coverage;
-  - sidecar `Ractor` object and `in progress queue` in RedisDB that will extend an acquired lock for long-running blocks of code (that invoked "under" the lock);
+  - per-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
+    the acquired lock for long-running blocks of code (that invoked "under" the lock
+    whose ttl may expire before the block execution completes);
+  - an ability to add custom metadata to the lock and an ability to read this data;
 - **Minor**
   - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
   - better code stylization and interesting refactorings;

data/lib/redis_queued_locks/acquier/try.rb

@@ -10,112 +10,132 @@ module RedisQueuedLocks::Acquier::Try
   # @param acquier_position [Numeric]
   # @param ttl [Integer]
   # @param queue_ttl [Integer]
+  # @param fail_fast [Boolean]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
   # @since 0.1.0
   # rubocop:disable Metrics/MethodLength
-  def try_to_lock(redis, lock_key, lock_key_queue, acquier_id, acquier_position, ttl, queue_ttl)
+  def try_to_lock(
+    redis,
+    lock_key,
+    lock_key_queue,
+    acquier_id,
+    acquier_position,
+    ttl,
+    queue_ttl,
+    fail_fast
+  )
     # Step X: intermediate invocation results
     inter_result = nil
     timestamp = nil
 
     # Step 0: watch the lock key changes (and discard acquirement if lock is already acquired)
     result = redis.multi(watch: [lock_key]) do |transact|
-      # Step 1: add an acquier to the lock acquirement queue
-      res = redis.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
-
-      RedisQueuedLocks.debug(
-        "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
-      )
-
-      # Step 2.1: drop expired acquiers from the lock queue
-      res = redis.call(
-        'ZREMRANGEBYSCORE',
-        lock_key_queue,
-        '-inf',
-        RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
-      )
-
-      RedisQueuedLocks.debug(
-        "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
-      )
-
-      # Step 3: get the actual acquier waiting in the queue
-      waiting_acquier = Array(redis.call('ZRANGE', lock_key_queue, '0', '0')).first
+      # Fast-Step X0: fail-fast check
+      if fail_fast && redis.call('HGET', lock_key, 'acq_id')
+        # Fast-Step X1: is lock already obtained. fail fast - no try.
+        inter_result = :fail_fast_no_try
+      else
+        # Step 1: add an acquier to the lock acquirement queue
+        res = redis.call('ZADD', lock_key_queue, 'NX', acquier_position, acquier_id)
 
-      RedisQueuedLocks.debug(
-        "Step №3: какой процесс в очереди сейчас ждет. " \
-        "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
-      )
+        RedisQueuedLocks.debug(
+          "Step №1: добавление в очередь (#{acquier_id}). [ZADD to the queue: #{res}]"
+        )
 
-      # Step 4: check the actual acquier: is it ours? are we aready to lock?
-      unless waiting_acquier == acquier_id
-        # Step ROLLBACK 1.1: our time hasn't come yet. retry!
+        # Step 2.1: drop expired acquiers from the lock queue
+        res = redis.call(
+          'ZREMRANGEBYSCORE',
+          lock_key_queue,
+          '-inf',
+          RedisQueuedLocks::Resource.acquier_dead_score(queue_ttl)
+        )
 
         RedisQueuedLocks.debug(
-          "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
-          "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
+          "Step №2: дропаем из очереди просроченных ожидающих. [ZREMRANGE: #{res}]"
         )
 
-        inter_result = :acquier_is_not_first_in_queue
-      else
-        # NOTE: our time has come! let's try to acquire the lock!
-
-        # Step 5: check if the our lock is already acquired
-        locked_by_acquier = redis.call('HGET', lock_key, 'acq_id')
+        # Step 3: get the actual acquier waiting in the queue
+        waiting_acquier = Array(redis.call('ZRANGE', lock_key_queue, '0', '0')).first
 
         RedisQueuedLocks.debug(
-          "Ste №5: Ищем требуемый лок. " \
-          "[HGET<#{lock_key}>: " \
-          "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
+          "Step №3: какой процесс в очереди сейчас ждет. " \
+          "[ZRANGE <следующий процесс>: #{waiting_acquier} :: <текущий процесс>: #{acquier_id}]"
         )
 
-        if locked_by_acquier
-          # Step ROLLBACK 2: required lock is stil acquired. retry!
+        # Step 4: check the actual acquier: is it ours? are we aready to lock?
+        unless waiting_acquier == acquier_id
+          # Step ROLLBACK 1.1: our time hasn't come yet. retry!
 
           RedisQueuedLocks.debug(
-            "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
-            "[Занят процессом: #{locked_by_acquier}]"
+            "Step ROLLBACK №1: не одинаковые ключи. выходим. " \
+            "[Ждет: #{waiting_acquier}. А нужен: #{acquier_id}]"
           )
 
-          inter_result = :lock_is_still_acquired
+          inter_result = :acquier_is_not_first_in_queue
         else
-          # NOTE: required lock is free and ready to be acquired! acquire!
+          # NOTE: our time has come! let's try to acquire the lock!
 
-          # Step 6.1: remove our acquier from waiting queue
-          transact.call('ZPOPMIN', lock_key_queue, '1')
-
-          RedisQueuedLocks.debug(
-            'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
-          )
+          # Step 5: check if the our lock is already acquired
+          locked_by_acquier = redis.call('HGET', lock_key, 'acq_id')
 
           RedisQueuedLocks.debug(
-            "===> <FINAL> Step №6: закрепляем лок за процессом [HSET<#{lock_key}>: #{acquier_id}]"
-          )
-
-          # Step 6.2: acquire a lock and store an info about the acquier
-          transact.call(
-            'HSET',
-            lock_key,
-            'acq_id', acquier_id,
-            'ts', (timestamp = Time.now.to_i),
-            'ini_ttl', ttl
+            "Ste №5: Ищем требуемый лок. " \
+            "[HGET<#{lock_key}>: " \
+            "#{(locked_by_acquier == nil) ? 'не занят' : "занят процессом <#{locked_by_acquier}>"}"
           )
 
-          # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
-          transact.call('PEXPIRE', lock_key, ttl) # NOTE: in seconds
+          if locked_by_acquier
+            # Step ROLLBACK 2: required lock is stil acquired. retry!
+
+            RedisQueuedLocks.debug(
+              "Step ROLLBACK №2: Ключ уже занят. Ничего не делаем. " \
+              "[Занят процессом: #{locked_by_acquier}]"
+            )
+
+            inter_result = :lock_is_still_acquired
+          else
+            # NOTE: required lock is free and ready to be acquired! acquire!
+
+            # Step 6.1: remove our acquier from waiting queue
+            transact.call('ZPOPMIN', lock_key_queue, '1')
+
+            RedisQueuedLocks.debug(
+              'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
+            )
+
+            RedisQueuedLocks.debug(
+              "===> <FINAL> Step №6: закрепляем лок за процессом [HSET<#{lock_key}>: #{acquier_id}]"
+            )
+
+            # Step 6.2: acquire a lock and store an info about the acquier
+            transact.call(
+              'HSET',
+              lock_key,
+              'acq_id', acquier_id,
+              'ts', (timestamp = Time.now.to_i),
+              'ini_ttl', ttl
+            )
+
+            # Step 6.3: set the lock expiration time in order to prevent "infinite locks"
+            transact.call('PEXPIRE', lock_key, ttl) # NOTE: in milliseconds
+          end
         end
       end
     end
 
     # Step 7: Analyze the aquirement attempt:
+    # rubocop:disable Lint/DuplicateBranch
     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 }
     when inter_result == :lock_is_still_acquired || inter_result == :acquier_is_not_first_in_queue
-      # Step 7.a: lock is still acquired by another process => failed to acquire
+      # Step 7.b: lock is still acquired by another process => failed to acquire
       { ok: false, result: inter_result }
     when result == nil || (result.is_a?(::Array) && result.empty?)
-      # Step 7.b: lock is already acquired durign the acquire race => failed to acquire
+      # Step 7.c: lock is already acquired durign the acquire race => failed to acquire
       { 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:
@@ -126,12 +146,13 @@ module RedisQueuedLocks::Acquier::Try
       #   2. hset should return 2 (lock key is added to the redis as a hashmap with 2 fields)
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
-      # Step 7.c: locked! :) let's go! => successfully acquired
+      # Step 7.d: locked! :) let's go! => successfully acquired
       { ok: true, result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl } }
     else
-      # Ste 7.d: unknown behaviour :thinking:
+      # Ste 7.3: unknown behaviour :thinking:
       { ok: false, result: :unknown }
     end
+    # rubocop:enable Lint/DuplicateBranch
   end
   # rubocop:enable Metrics/MethodLength, Metrics/PerceivedComplexity
 

data/lib/redis_queued_locks/acquier.rb

@@ -58,10 +58,14 @@ module RedisQueuedLocks::Acquier
     #   Unique acquire identifier that is also should be unique between processes and pods
     #   on different machines. By default the uniq identity string is
     #   represented as 10 bytes hexstr.
+    # @option fail_fast [Boolean]
+    #   Should the required lock to be checked before the try and exit immidetly if lock is
+    #   already obtained.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
-    # @return [Hash<Symbol,Any>]
-    #   Format: { ok: true/false, result: Any }
+    # @return [Hash<Symbol,Any>,yield]
+    #  - Format: { ok: true/false, result: Any }
+    #  - If block is given the result of block's yeld will be returned.
     #
     # @api private
     # @since 0.1.0
@@ -82,6 +86,7 @@ module RedisQueuedLocks::Acquier
       raise_errors:,
       instrumenter:,
       identity:,
+      fail_fast:,
       &block
     )
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
@@ -126,7 +131,8 @@ module RedisQueuedLocks::Acquier
             acquier_id,
             acquier_position,
             lock_ttl,
-            queue_ttl
+            queue_ttl,
+            fail_fast
           ) => { ok:, result: }
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
@@ -157,21 +163,40 @@ module RedisQueuedLocks::Acquier
             acq_process[:should_try] = false
             acq_process[:acq_time] = acq_time
             acq_process[:acq_end_time] = acq_end_time
+          elsif fail_fast && acq_process[:result] == :fail_fast_no_try
+            acq_process[:should_try] = false
+            if raise_errors
+              raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
+                Lock "#{lock_key}" is already obtained.
+              ERROR_MESSAGE
+            end
           else
             # Step 2.1.b: failed acquirement => retry
             acq_process[:tries] += 1
 
-            if retry_count != nil && acq_process[:tries] >= retry_count
-              # NOTE: reached the retry limit => quit from the loop
+            if (retry_count != nil && acq_process[:tries] >= retry_count) || fail_fast
+              # NOTE:
+              #   - reached the retry limit => quit from the loop
+              #   - should fail fast => quit from the loop
               acq_process[:should_try] = false
-              acq_process[:result] = :retry_limit_reached
-              # NOTE: reached the retry limit => dequeue from the lock queue
+              acq_process[:result] = fail_fast ? :fail_fast_after_try : :retry_limit_reached
+
+              # NOTE:
+              #   - reached the retry limit => dequeue from the lock queue
+              #   - should fail fast => dequeue from the lock queue
               acq_dequeue.call
+
               # NOTE: check and raise an error
-              raise(LockAcquiermentRetryLimitError, <<~ERROR_MESSAGE.strip) if raise_errors
-                Failed to acquire the lock "#{lock_key}"
-                for the given retry_count limit (#{retry_count} times).
-              ERROR_MESSAGE
+              if fail_fast && raise_errors
+                raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
+                  Lock "#{lock_key}" is already obtained.
+                ERROR_MESSAGE
+              elsif raise_errors
+                raise(RedisQueuedLocks::LockAcquiermentRetryLimitError, <<~ERROR_MESSAGE.strip)
+                  Failed to acquire the lock "#{lock_key}"
+                  for the given retry_count limit (#{retry_count} times).
+                ERROR_MESSAGE
+              end
             else
               # NOTE:
               #   delay the exceution in order to prevent chaotic attempts
@@ -210,8 +235,10 @@ module RedisQueuedLocks::Acquier
           { ok: true, result: acq_process[:lock_info] }
         end
       else
-        unless acq_process[:result] == :retry_limit_reached
-          # NOTE: we have only two situations if lock is not acquired:
+        if acq_process[:result] != :retry_limit_reached &&
+           acq_process[:result] != :fail_fast_no_try &&
+           acq_process[:result] != :fail_fast_after_try
+          # NOTE: we have only two situations if lock is not acquired withou fast-fail flag:
           #   - time limit is reached
           #   - retry count limit is reached
           #   In other cases the lock obtaining time and tries count are infinite.
@@ -363,7 +390,7 @@ module RedisQueuedLocks::Acquier
     # Returns an information about the required lock queue by the lock name. The result
     # represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
     # lock acquirers and their position in queue. Async nature with redis communcation can lead
-    # the sitation when the queue becomes empty during the queue data extraction. So sometimes
+    # the sitaution when the queue becomes empty during the queue data extraction. So sometimes
     # you can receive the lock queue info with empty queue.
     #
     # @param redis_client [RedisClient]

data/lib/redis_queued_locks/client.rb

@@ -22,8 +22,8 @@ class RedisQueuedLocks::Client
     # TODO: setting :debug, true/false
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
-    validate('retry_delay', :integer)
-    validate('retry_jitter', :integer)
+    validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
+    validate('retry_jitter') { |val| val.is_a?(::Integer) && val >= 0 }
     validate('try_to_lock_timeout') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('default_lock_tt', :integer)
     validate('default_queue_ttl', :integer)
@@ -44,6 +44,9 @@ class RedisQueuedLocks::Client
   # @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.
@@ -81,10 +84,16 @@ class RedisQueuedLocks::Client
   #   Unique acquire identifier that is also should be unique between processes and pods
   #   on different machines. By default the uniq identity string is
   #   represented as 10 bytes hexstr.
+  # @option fail_fast [Boolean]
+  #   - Should the required lock to be checked before the try and exit immidietly if lock is
+  #   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;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [Hash<Symbol,Any>,yield]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  #   - Format: { ok: true/false, result: Symbol/Hash }.
+  #   - If block is given the result of block's yeld will be returned.
   #
   # @api public
   # @since 0.1.0
@@ -97,6 +106,7 @@ class RedisQueuedLocks::Client
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
     raise_errors: false,
+    fail_fast: false,
     identity: uniq_identity,
     &block
   )
@@ -116,6 +126,7 @@ class RedisQueuedLocks::Client
       raise_errors:,
       instrumenter: config[:instrumenter],
       identity:,
+      fail_fast:,
       &block
     )
   end
@@ -128,10 +139,11 @@ class RedisQueuedLocks::Client
     lock_name,
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
-    timeout: config[:default_timeout],
+    timeout: config[:try_to_lock_timeout],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
+    fail_fast: false,
     identity: uniq_identity,
     &block
   )
@@ -145,6 +157,7 @@ class RedisQueuedLocks::Client
       retry_jitter:,
       raise_errors: true,
       identity:,
+      fail_fast:,
       &block
     )
   end

data/lib/redis_queued_locks/errors.rb

@@ -9,6 +9,10 @@ module RedisQueuedLocks
   # @since 0.1.0
   ArgumentError = Class.new(::ArgumentError)
 
+  # @api public
+  # @since 0.1.0
+  LockAlreadyObtainedError = Class.new(Error)
+
   # @api public
   # @since 0.1.0
   LockAcquiermentTimeoutError = Class.new(Error)

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.13
+  version: 0.0.15
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-27 00:00:00.000000000 Z
+date: 2024-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client