redis_queued_locks 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1044ea4b8236b241132017ea9b9f2f8ac280c584be1158a9e7b52b15aa58d4ef
-  data.tar.gz: 5e6dc2141b05055f3641d88c9c181521ed6ad94100f6007573628e6aef7cee17
+  metadata.gz: 56120a88eb6ffa4f377c014b8619cdcd227ac0efaab1c6ec6495042c74739a63
+  data.tar.gz: d1e7240b5ca0c8a18842cd609b1e9280813a0a51a62d2ed9bcacdb66d707801f
 SHA512:
-  metadata.gz: 8d8c0ac83545d663f0d558dc258364348a100e34c9636bf9663d8c021154c38c660ee626019f08bc5607c4ce01fc731a49c1fae3f5dc6e28d3a5d2ea41292d02
-  data.tar.gz: 1bbc2cfc740ff6eb3fa6e458dc5ed9dd4509885427eaf7e5eb8c2e74a605652dc9c39586d7282442befb1f199d0b84ff3ac573dfa43bfcc86bcb117f165e70ca
+  metadata.gz: f3df6ebf409fa4d97ebe51632832d6c9c64eb03a4102d68e6951def7a3d351c62e86e63014b8cc1d5c6ea4c5cd6bf9bdf5595ebdb2a3334550e7a27f2f6b0bcd
+  data.tar.gz: 6e512298fb8be556e5370574e87529b936670bec1b13250233c6ce08d9feb4c8032b1b07e90a514ff4d4687e01391424be5b546a124119c7937492baa7ef87ee

data/CHANGELOG.md

@@ -1,7 +1,18 @@
 ## [Unreleased]
 
+## [0.0.7] - 2024-02-27
+### Changed
+- Minor documentation updates;
+
+## [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

@@ -1,6 +1,7 @@
 # RedisQueuedLocks
 
-Distributed lock implementation with "lock acquisition queue" capabilities based on the Redis Database.
+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).
 
 ---
@@ -18,7 +19,7 @@ Each lock request is put into a request queue and processed in order of their pr
   - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
-- [TODO](#todo)
+- [Todo](#todo)
 - [Contributing](#contributing)
 - [License](#license)
 - [Authors](#authors)
@@ -65,6 +66,7 @@ rq_lock_client = RedisQueuedLocks::Client.new(redis_client) do |config|
 end
 
 # Step 3: start to work with locks :)
+rq_lock_client.lock("some-lock") { puts "Hello, lock!" }
 ```
 
 ---
@@ -127,7 +129,7 @@ end
 
 ---
 
-#### lock - obtain a lock
+#### #lock - obtain a lock
 
 ```ruby
 def lock(
@@ -166,9 +168,11 @@ def lock(
 - `instrumenter` - `[#notify]`
   - See RedisQueuedLocks::Instrument::ActiveSupport for example.
 - `raise_errors` - `[Boolean]`
-  - Raise errors on library-related limits such as timeout or failed lock obtain.
+  - Raise errors on library-related limits such as timeout or retry count limit.
 - `block` - `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
+  - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
+  - 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 }`;
@@ -186,20 +190,18 @@ 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 }
   ```
 
-
 ---
 
 #### #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 +235,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,15 +263,25 @@ 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)
+  }
+}
+```
 
 ---
 
 ## Instrumentation
 
-An instrumentation layer is incapsulated in `instrumenter` object stored in configurations.
+An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
 
-Instrumenter object should provide `notify(event, payload)` method with following signarue:
+Instrumenter object should provide `notify(event, payload)` method with the following signarue:
 
 - `event` - `string`;
 - `payload` - `hash<Symbol,Any>`;
@@ -266,7 +289,7 @@ Instrumenter object should provide `notify(event, payload)` method with followin
 `redis_queued_locks` provides two instrumenters:
 
 - `RedisQueuedLocks::Instrument::ActiveSupport` - `ActiveSupport::Notifications` instrumenter
-  that instrument events via `ActiveSupport::Notifications` api;
+  that instrument events via `ActiveSupport::Notifications` API;
 - `RedisQueuedLocks::Instrument::VoidNotifier` - instrumenter that does nothing;
 
 By default `RedisQueuedLocks::Client` is configured with the void notifier (which means "instrumentation is disabled").
@@ -318,11 +341,11 @@ Detalized event semantics and payload structure:
 
 ---
 
-## TODO
+## Todo
 
 - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
 - `100%` test coverage;
-- better code stylization and interesting refactorings :)
+- better code stylization and interesting refactorings;
 
 ---
 

data/lib/redis_queued_locks/acquier/release.rb

@@ -38,7 +38,7 @@ module RedisQueuedLocks::Acquier::Release
         count: batch_size
       ) do |lock_queue|
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
-        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), "0")
+        pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
       end
 
       # Step B: release all locks

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.7
+  VERSION = '0.0.7'
 end

data/redis_queued_locks.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.email   = ['iamdaiver@gmail.com']
 
   spec.summary     = 'Queued distributed locks based on Redis.'
-  spec.description = 'Distributed lock implementation with "lock acquisition queue" ' \
+  spec.description = 'Distributed locks with "lock acquisition queue" ' \
                      'capabilities based on the Redis Database.'
   spec.homepage    = 'https://github.com/0exp/redis_queued_locks'
   spec.license     = 'MIT'

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.7
 platform: ruby
 authors:
 - Rustam Ibragimov
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.28'
-description: Distributed lock implementation with "lock acquisition queue" capabilities
-  based on the Redis Database.
+description: Distributed locks with "lock acquisition queue" capabilities based on
+  the Redis Database.
 email:
 - iamdaiver@gmail.com
 executables: []