redis_queued_locks 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1044ea4b8236b241132017ea9b9f2f8ac280c584be1158a9e7b52b15aa58d4ef
-  data.tar.gz: 5e6dc2141b05055f3641d88c9c181521ed6ad94100f6007573628e6aef7cee17
+  metadata.gz: 9e98a72e1519c54d21a6273176a7d8a3bd9fa3033b7f30ca73fdca5a4335341d
+  data.tar.gz: b2cf62db6016bd456a379feb3703989cc4a481f2eed4103c5c27a60bec624d46
 SHA512:
-  metadata.gz: 8d8c0ac83545d663f0d558dc258364348a100e34c9636bf9663d8c021154c38c660ee626019f08bc5607c4ce01fc731a49c1fae3f5dc6e28d3a5d2ea41292d02
-  data.tar.gz: 1bbc2cfc740ff6eb3fa6e458dc5ed9dd4509885427eaf7e5eb8c2e74a605652dc9c39586d7282442befb1f199d0b84ff3ac573dfa43bfcc86bcb117f165e70ca
+  metadata.gz: d90c848b5fb00614c3f61719d470d7a2dae008d3b6349c395674fe7bf262feea09795dafc74756a16426f499652e9cb0dcb4eef8b0dc9e2c1cc8abff2a1345d1
+  data.tar.gz: ccc6e73175a2c41988303e3ea73feeacf95833b8d318dc1318c91f800d656ea157aeca62d7eba491ca489253a01ba4489f6a4c254c32f54ef3a540c9312ca179

data/CHANGELOG.md

@@ -1,7 +1,14 @@
 ## [Unreleased]
 
+## [0.0.6] - 2024-02-27
+### Changed
+- Major documentation updates;
+- `RedisQueuedLock#release_lock!` now returns detaield semantic result;
+- `RediSQueuedLock#release_all_locks!` now returns detailed semantic result;
+
 ## [0.0.5] - 2024-02-26
-- Minor update with documentation and configuration updates inside.
+### Changed
+- Minor gem update with documentation and configuration updates inside.
 
 ## [0.0.4] - 2024-02-26
 ### Changed

data/README.md

@@ -127,7 +127,7 @@ end
 
 ---
 
-#### lock - obtain a lock
+#### #lock - obtain a lock
 
 ```ruby
 def lock(
@@ -186,9 +186,8 @@ Return value:
   ```
 - for failed lock obtaining:
   ```ruby
-  { ok: false, result: :acquier_is_not_first_in_queue }
-  { ok: false, result: :lock_is_still_acquired }
-  { ok: false, result: :lock_is_acquired_during_acquire_race }
+  { ok: false, result: :timeout_reached }
+  { ok: false, result: :retry_count_reached }
   { ok: false, result: :unknown }
   ```
 
@@ -197,9 +196,9 @@ Return value:
 
 #### #lock! - exceptional lock obtaining
 
-- fails when:
-  - `timeout` limit reached before lock is obtained;
-  - `retry_count` limit reached before lock is obtained;
+- fails when (and with):
+  - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
+  - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
 
 ```ruby
 def lock!(
@@ -233,7 +232,18 @@ def unlock(lock_name)
   - the lock name that should be released.
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Symbol/Hash }`;
+- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
+
+```ruby
+{
+  ok: true,
+  result: {
+    rel_time: 0.02, # time spent to lock release (in seconds)
+    rel_key: "rql:lock:your_lock_name", # released lock key
+    rel_queue: "rql:lock_queue:your_lock_name" # released lock key queue
+  }
+}
+```
 
 ---
 
@@ -250,7 +260,17 @@ def clear_locks(batch_size: config[:lock_release_batch_size])
   - batch of cleared locks and lock queus unde the one pipelined redis command;
 
 Return:
-- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Symbol/Hash }`;
+- `[Hash<Symbol,Any>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
+
+```ruby
+{
+  ok: true,
+  result: {
+    rel_time: 3.07, # time spent to release all locks and related lock queues
+    rel_key_cnt: 100_500 # released redis keys (released locks + released lock queues)
+  }
+}
+```
 
 ---
 

data/lib/redis_queued_locks/acquier.rb

@@ -60,7 +60,7 @@ module RedisQueuedLocks::Acquier
     #
     # @api private
     # @since 0.1.0
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/MethodLength, Metrics/BlockNesting
     def acquire_lock!(
       redis,
       lock_name,
@@ -147,6 +147,7 @@ module RedisQueuedLocks::Acquier
             if retry_count != nil && acq_process[:tries] >= retry_count
               # NOTE: reached the retry limit => 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_dequeue.call
               # NOTE: check and raise an error
@@ -154,10 +155,11 @@ module RedisQueuedLocks::Acquier
                 Failed to acquire the lock "#{lock_key}"
                 for the given retry_count limit (#{retry_count} times).
               ERROR_MESSAGE
-            elsif delay_execution(retry_delay, retry_jitter)
+            else
               # NOTE:
               #   delay the exceution in order to prevent chaotic attempts
               #   and to allow other processes and threads to obtain the lock too.
+              delay_execution(retry_delay, retry_jitter)
             end
           end
         end
@@ -191,12 +193,18 @@ module RedisQueuedLocks::Acquier
           { ok: true, result: acq_process[:lock_info] }
         end
       else
-        # Step 3.b: lock is not acquired:
-        #   => drop itslef from the queue and return the reason of the failed acquirement
+        unless acq_process[:result] == :retry_limit_reached
+          # NOTE: we have only two situations if lock is not acquired:
+          #   - time limit is reached
+          #   - retry count limit is reached
+          #   In other cases the lock obtaining time and tries count are infinite.
+          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] }
       end
     end
-    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/MethodLength, Metrics/BlockNesting
 
     # Release the concrete lock:
     # - 1. clear lock queue: al; related processes released
@@ -208,7 +216,7 @@ module RedisQueuedLocks::Acquier
     # @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: Any }
+    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
     #
     # @api private
     # @since 0.1.0
@@ -231,7 +239,7 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: result }
+      { ok: true, result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue } }
     end
 
     # Release all locks:
@@ -241,7 +249,7 @@ module RedisQueuedLocks::Acquier
     # @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: Any }
+    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 0.1.0
@@ -260,7 +268,7 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: result }
+      { ok: true, result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time } }
     end
 
     private

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - Rustam Ibragimov