redis_queued_locks 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e1e1a54762132f92451d595938cb467b7b644dffc0817abe99209e1f92160f8
-  data.tar.gz: 297eec3d7fcee35d12e7f3509e8e3dfd4b8b3c52889c7570a79cd6a30f45eda4
+  metadata.gz: 1044ea4b8236b241132017ea9b9f2f8ac280c584be1158a9e7b52b15aa58d4ef
+  data.tar.gz: 5e6dc2141b05055f3641d88c9c181521ed6ad94100f6007573628e6aef7cee17
 SHA512:
-  metadata.gz: 6d2c64622bd3b8465a749b5f6a8050d5fd1d5b623990f91421f91004c444baab12114964ded28d5ac0fa43fed56f3e893798feb31b00ab173d536e57fcfdfaa4
-  data.tar.gz: 02ee9d8742ffd3a7b16b8c23b8d4c4f58a8cb1b9db4d215ece4bf34de0c79830bd3417186b2d75dbbd48f6845d736361af7503f641e7faa16d139cbe193263d3
+  metadata.gz: 8d8c0ac83545d663f0d558dc258364348a100e34c9636bf9663d8c021154c38c660ee626019f08bc5607c4ce01fc731a49c1fae3f5dc6e28d3a5d2ea41292d02
+  data.tar.gz: 1bbc2cfc740ff6eb3fa6e458dc5ed9dd4509885427eaf7e5eb8c2e74a605652dc9c39586d7282442befb1f199d0b84ff3ac573dfa43bfcc86bcb117f165e70ca

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## [Unreleased]
 
+## [0.0.5] - 2024-02-26
+- Minor 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,173 @@ 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: :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: :unknown }
+  ```
+
+
+---
+
+#### #lock! - exceptional lock obtaining
+
+- fails when:
+  - `timeout` limit reached before lock is obtained;
+  - `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: Symbol/Hash }`;
+
+---
+
+#### #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])
 ```
 
-- `#lock`
-- `#lock!`
-- `#unlock`
-- `#clear_locks`
+- `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: Symbol/Hash }`;
+
+---
+
+## Instrumentation
 
-## Instrumentation events
+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 +315,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

@@ -149,6 +149,11 @@ module RedisQueuedLocks::Acquier
               acq_process[:should_try] = false
               # NOTE: reached the retry limit => 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
             elsif delay_execution(retry_delay, retry_jitter)
               # NOTE:
               #   delay the exceution in order to prevent chaotic attempts

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.5
+  VERSION = '0.0.5'
 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.5
 platform: ruby
 authors:
 - Rustam Ibragimov