redis_queued_locks 0.0.3 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dbd11cefb9d18a816eb4c63fe1178f87325c30d75efc2bc806d29f41994fc2c
-  data.tar.gz: 9697f4bf452aaaa7cade45320c50d16b510c657074ba97513c5f8de9c51f6c49
+  metadata.gz: 1044ea4b8236b241132017ea9b9f2f8ac280c584be1158a9e7b52b15aa58d4ef
+  data.tar.gz: 5e6dc2141b05055f3641d88c9c181521ed6ad94100f6007573628e6aef7cee17
 SHA512:
-  metadata.gz: b28ef92375c7eef4d6c43fccb5e44105d653fb00e052edcf67316f8da13578ad7b39086b3799782592b38bf046760f8faa1238b92de293b83eb1e4a7c441413e
-  data.tar.gz: dfd3891ae8d0303b88ac95268056addc3b4e03f862a5200166de9553b412eee78b77f42193f133f9dd340793b67928806e2e05451517585c2282fb7e4c871d1f
+  metadata.gz: 8d8c0ac83545d663f0d558dc258364348a100e34c9636bf9663d8c021154c38c660ee626019f08bc5607c4ce01fc731a49c1fae3f5dc6e28d3a5d2ea41292d02
+  data.tar.gz: 1bbc2cfc740ff6eb3fa6e458dc5ed9dd4509885427eaf7e5eb8c2e74a605652dc9c39586d7282442befb1f199d0b84ff3ac573dfa43bfcc86bcb117f165e70ca

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [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;
+
 ## [0.0.3] - 2024-02-26
 ### Changed
 - Instrumentation events:

data/README.md

@@ -1,8 +1,288 @@
 # 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).
 
-## Instrumentation events
+---
+
+## 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
+
+clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
+  # (default: 3) (supports nil)
+  # - nil means "infinite retries" and you are only limited by the "try_to_lock_timeout" config;
+  config.retry_count = 3
+
+  # (milliseconds) (default: 200)
+  config.retry_delay = 200
+
+  # (milliseconds) (default: 50)
+  config.retry_jitter = 50
+
+  # (seconds) (supports nil)
+  # - nil means "no timeout" and you are only limited by "retry_count" config;
+  config.try_to_lock_timeout = 10
+
+  # (milliseconds) (default: 1)
+  # - expiration precision. affects the ttl (ttl + precision);
+  config.exp_precision = 1
+
+  # (milliseconds) (default: 5_000)
+  # - lock's time to live
+  config.default_lock_ttl = 5_000
+
+  # (seconds) (default: 15)
+  # - lock request timeout. after this timeout your lock request in queue will be requeued;
+  config.default_queue_ttl = 15
+
+  # (default: 100)
+  # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic;
+  # - affects the performancs capabilites (redis, rubyvm);
+  config.lock_release_batch_size = 100
+
+  # (default: RedisQueuedLocks::Instrument::VoidNotifier)
+  # - instrumentation layer;
+  # - you can provde your own instrumenter with `#notify(event, payload = {})`
+  #   - event: <string> requried;
+  #   - payload: <hash> requried;
+  # - disabled by default via VoidNotifier;
+  config.instrumenter = RedisQueuedLocks::Instrument::ActiveSupport
+end
+```
+
+---
+
+### 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
+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])
+```
+
+- `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
+
+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;
@@ -32,6 +312,32 @@ Distributed lock implementation with "lock acquisition queue" capabilities based
 - `"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 the lock release;
+    - `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

@@ -10,10 +10,10 @@ class RedisQueuedLocks::Client
     setting :retry_count, 3
     setting :retry_delay, 200 # NOTE: milliseconds
     setting :retry_jitter, 50 # NOTE: milliseconds
-    setting :default_timeout, 10 # NOTE: seconds
+    setting :try_to_lock_timeout, 10 # NOTE: seconds
     setting :exp_precision, 1 # NOTE: milliseconds
     setting :default_lock_ttl, 5_000 # NOTE: milliseconds
-    setting :default_queue_ttl, 30 # NOTE: seconds
+    setting :default_queue_ttl, 15 # NOTE: seconds
     setting :lock_release_batch_size, 100
     setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
 
@@ -23,7 +23,7 @@ class RedisQueuedLocks::Client
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay', :integer)
     validate('retry_jitter', :integer)
-    validate('default_timeout', :integer)
+    validate('try_to_lock_timeout') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('exp_precision', :integer)
     validate('default_lock_tt', :integer)
     validate('default_queue_ttl', :integer)
@@ -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 }.
@@ -86,7 +86,7 @@ class RedisQueuedLocks::Client
     thread_id: RedisQueuedLocks::Resource.get_thread_id,
     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],

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

@@ -4,6 +4,7 @@ module RedisQueuedLocks
   # @return [String]
   #
   # @api public
-  # @since 0.0.3
-  VERSION = '0.0.3'
+  # @since 0.0.1
+  # @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.3
+  version: 0.0.5
 platform: ruby
 authors:
 - Rustam Ibragimov