redis_queued_locks 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e1e1a54762132f92451d595938cb467b7b644dffc0817abe99209e1f92160f8
-  data.tar.gz: 297eec3d7fcee35d12e7f3509e8e3dfd4b8b3c52889c7570a79cd6a30f45eda4
+  metadata.gz: 9e98a72e1519c54d21a6273176a7d8a3bd9fa3033b7f30ca73fdca5a4335341d
+  data.tar.gz: b2cf62db6016bd456a379feb3703989cc4a481f2eed4103c5c27a60bec624d46
 SHA512:
-  metadata.gz: 6d2c64622bd3b8465a749b5f6a8050d5fd1d5b623990f91421f91004c444baab12114964ded28d5ac0fa43fed56f3e893798feb31b00ab173d536e57fcfdfaa4
-  data.tar.gz: 02ee9d8742ffd3a7b16b8c23b8d4c4f58a8cb1b9db4d215ece4bf34de0c79830bd3417186b2d75dbbd48f6845d736361af7503f641e7faa16d139cbe193263d3
+  metadata.gz: d90c848b5fb00614c3f61719d470d7a2dae008d3b6349c395674fe7bf262feea09795dafc74756a16426f499652e9cb0dcb4eef8b0dc9e2c1cc8abff2a1345d1
+  data.tar.gz: ccc6e73175a2c41988303e3ea73feeacf95833b8d318dc1318c91f800d656ea157aeca62d7eba491ca489253a01ba4489f6a4c254c32f54ef3a540c9312ca179

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [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
+### Changed
+- Minor gem update with documentation and configuration updates inside.
+
 ## [0.0.4] - 2024-02-26
 ### Changed
 - changed default configuration values of `RedisQueuedLocks::Client` config;

data/README.md

@@ -1,8 +1,75 @@
 # RedisQueuedLocks
 
 Distributed lock implementation 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).
 
-## Configuration
+---
+
+## Table of Contents
+
+- [Algorithm](#algorithm)
+- [Installation](#installation)
+- [Setup](#setup)
+- [Configuration](#configuration)
+- [Usage](#usage)
+  - [lock](#lock---obtain-a-lock)
+  - [lock!](#lock---exeptional-lock-obtaining)
+  - [unlock](#unlock---release-a-lock)
+  - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+- [Instrumentation](#instrumentation)
+  - [Instrumentation Events](#instrumentation-events)
+- [TODO](#todo)
+- [Contributing](#contributing)
+- [License](#license)
+- [Authors](#authors)
+
+---
+
+### Algorithm
+
+- soon;
+
+---
+
+### Installation
+
+```ruby
+gem 'redis_queued_locks'
+```
+
+```shell
+bundle install
+# --- or ---
+gem install redis_queued_locks
+```
+
+```ruby
+require 'redis_queued_locks'
+```
+
+---
+
+### Setup
+
+```ruby
+require 'redis_queued_locks'
+
+# Step 1: initialize RedisClient instance
+redis_clinet = RedisClient.config.new_pool # NOTE: provide your ounw RedisClient instance
+
+# Step 2: initialize RedisQueuedLock::Client instance
+rq_lock_client = RedisQueuedLocks::Client.new(redis_client) do |config|
+  # NOTE:
+  #   - some your application-related configs;
+  #   - for documentation see <Configuration> section in readme;
+end
+
+# Step 3: start to work with locks :)
+```
+
+---
+
+### Configuration
 
 ```ruby
 redis_client = RedisClient.config.new_pool # NOTE: provide your own RedisClient instance
@@ -49,21 +116,193 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
 end
 ```
 
-## Usage
+---
+
+### Usage
+
+- [lock](#lock---obtain-a-lock)
+- [lock!](#lock---exeptional-lock-obtaining)
+- [unlock](#unlock---release-a-lock)
+- [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+
+---
+
+#### #lock - obtain a lock
 
 ```ruby
-redis_clinet = RedisClient.config.new_pool # NOTE: provide your ounw RedisClient instance
-rq_lock = RedisQueuedLocks::Client.new(redis_client) do |config|
-  # NOTE: some your application-related configs
-end
+def lock(
+  lock_name,
+  process_id: RedisQueuedLocks::Resource.get_process_id,
+  thread_id: RedisQueuedLocks::Resource.get_thread_id,
+  ttl: config[:default_lock_ttl],
+  queue_ttl: config[:default_queue_ttl],
+  timeout: config[:try_to_lock_timeout],
+  retry_count: config[:retry_count],
+  retry_delay: config[:retry_delay],
+  retry_jitter: config[:retry_jitter],
+  raise_errors: false,
+  &block
+)
+```
+
+- `lock_name` - `[String]`
+  - Lock name to be obtained.
+- `process_id` - `[Integer,String]`
+  - The process that want to acquire the lock.
+- `thread_id` - `[Integer,String]`
+  - The process's thread that want to acquire the lock.
+- `ttl` [Integer]
+  - Lock's time to live (in milliseconds).
+- `queue_ttl` - `[Integer]`
+  - 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".
+- `retry_count` - `[Integer,NilClass]`
+  - How many times we should try to acquire a lock. Nil means "infinite retries".
+- `retry_delay` - `[Integer]`
+  - A time-interval between the each retry (in milliseconds).
+- `retry_jitter` - `[Integer]`
+  - Time-shift range for retry-delay (in milliseconds).
+- `instrumenter` - `[#notify]`
+  - See RedisQueuedLocks::Instrument::ActiveSupport for example.
+- `raise_errors` - `[Boolean]`
+  - Raise errors on library-related limits such as timeout or failed lock obtain.
+- `block` - `[Block]`
+  - A block of code that should be executed after the successfully acquired lock.
+
+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 ("your_process_id/your_thread_id")
+      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 }
+  ```
+
+
+---
+
+#### #lock! - exceptional lock obtaining
+
+- 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!(
+  lock_name,
+  process_id: RedisQueuedLocks::Resource.get_process_id,
+  thread_id: RedisQueuedLocks::Resource.get_thread_id,
+  ttl: config[:default_lock_ttl],
+  queue_ttl: config[:default_queue_ttl],
+  timeout: config[:default_timeout],
+  retry_count: config[:retry_count],
+  retry_delay: config[:retry_delay],
+  retry_jitter: config[:retry_jitter],
+  &block
+)
+```
+
+See `#lock` method [documentation](#lock---obtain-a-lock).
+
+---
+
+#### #unlock - release a lock
+
+- release the concrete lock with lock request queue;
+- queue will be relased first;
+
+```ruby
+def unlock(lock_name)
+```
+
+- `lock_name` - `[String]`
+  - the lock name that should be released.
+
+Return:
+- `[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
+  }
+}
+```
+
+---
+
+#### #clear_locks - release all locks and lock queues
+
+- release all obtained locks and related lock request queues;
+- queues will be released first;
+
+```ruby
+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;
+
+Return:
+- `[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)
+  }
+}
 ```
 
-- `#lock`
-- `#lock!`
-- `#unlock`
-- `#clear_locks`
+---
 
-## Instrumentation events
+## Instrumentation
+
+An instrumentation layer is incapsulated in `instrumenter` object stored in configurations.
+
+Instrumenter object should provide `notify(event, payload)` method with following signarue:
+
+- `event` - `string`;
+- `payload` - `hash<Symbol,Any>`;
+
+`redis_queued_locks` provides two instrumenters:
+
+- `RedisQueuedLocks::Instrument::ActiveSupport` - `ActiveSupport::Notifications` instrumenter
+  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").
+
+---
+
+### Instrumentation Events
+
+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**
+
+Detalized event semantics and payload structure:
 
 - `"redis_queued_locks.lock_obtained"`
   - a moment when the lock was obtained;
@@ -96,3 +335,29 @@ end
     - `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 queu keys` + `released lock keys`);
+
+---
+
+## TODO
+
+- `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
+- `100%` test coverage;
+- better code stylization and interesting refactorings :)
+
+---
+
+## Contributing
+
+- Fork it ( https://github.com/0exp/redis_queued_locks )
+- Create your feature branch (`git checkout -b feature/my-new-feature`)
+- Commit your changes (`git commit -am '[feature_context] Add some feature'`)
+- Push to the branch (`git push origin feature/my-new-feature`)
+- Create new Pull Request
+
+## License
+
+Released under MIT License.
+
+## Authors
+
+[Rustam Ibragimov](https://github.com/0exp)

data/lib/redis_queued_locks/acquier/release.rb

@@ -37,7 +37,6 @@ module RedisQueuedLocks::Acquier::Release
         RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
         count: batch_size
       ) do |lock_queue|
-        puts "RELEASE (lock_queue): #{lock_queue}"
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
         pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), "0")
       end
@@ -48,7 +47,6 @@ module RedisQueuedLocks::Acquier::Release
         RedisQueuedLocks::Resource::LOCK_PATTERN,
         count: batch_size
       ) do |lock_key|
-        puts "RELEASE (lock_key): #{lock_key}"
         pipeline.call('EXPIRE', lock_key, '0')
       end
     end

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,12 +147,19 @@ 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
-            elsif delay_execution(retry_delay, retry_jitter)
+              # 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
+            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
@@ -186,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
@@ -203,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
@@ -226,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:
@@ -236,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
@@ -255,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/client.rb

@@ -52,7 +52,7 @@ class RedisQueuedLocks::Client
   end
 
   # @param lock_name [String]
-  #   Lock name to be acquier.
+  #   Lock name to be obtained.
   # @option process_id [Integer,String]
   #   The process that want to acquire the lock.
   # @option thread_id [Integer,String]
@@ -73,7 +73,7 @@ class RedisQueuedLocks::Client
   #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
   # @option raise_errors [Boolean]
   #   Raise errors on library-related limits such as timeout or failed lock obtain.
-  # @param [Block]
+  # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
   # @return [Hash<Symbol,Any>]
   #   Format: { ok: true/false, result: Symbol/Hash }.

data/lib/redis_queued_locks/errors.rb

@@ -15,5 +15,5 @@ module RedisQueuedLocks
 
   # @api public
   # @since 0.1.0
-  LockAcquiermentLimitError = Class.new(Error)
+  LockAcquiermentRetryLimitError = 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.4
-  VERSION = '0.0.4'
+  # @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.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Rustam Ibragimov