redis_queued_locks 0.0.39 → 0.0.40

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df02925d34d26ec7181e33c783a2c368f84e2981a1b6249da100f0fc19515d5c
-  data.tar.gz: 4ae526151618eecba0ac733677e2d3e5dd8ae2558058c8407b693a6085e712d0
+  metadata.gz: b46bd07dab8fc9ce3228eb7bb804569a99dfc8f7f65a1eaf085c3af9061ae09e
+  data.tar.gz: 2c9470b5dd4b41a112c93bb891f33ff68f930dc47fd78a37516540249ded415d
 SHA512:
-  metadata.gz: 44f6546626e39b0fd1378a2cdcd8d72f2d394cba7478cbd2594c3b50b60cd2d484d0d4fca584a09391f5a5cc68c275b3b8f5c7fdf52d0c8c55976518bf3fe03b
-  data.tar.gz: 6c1251c02654e7b816e993d8e4a24c7cbf92ea0d908ba2d3efb60b99f711d0c7ce93902199f29c40e35b42fac2d76de4693380b72d01df0192c43e630e2cdf8e
+  metadata.gz: a7e0740247300cf79385c477a66bc823621888104887de33c3868cf4d06a2087ae6b2ea972e8844fd148e8e3b0da9468cfaf276f68f5d1be7e3b80f72e0c31fe
+  data.tar.gz: d920cda1d4f89da24123df0cf95595c87c21e1e4ed18495765ae0f78c1714af325f94e8e88a7971e4bb10250dde4f392095e8d19f010e9a5f0341d3d3201dc0c

data/.rubocop.yml

@@ -36,3 +36,6 @@ Metrics/CyclomaticComplexity:
 
 Metrics/PerceivedComplexity:
   Enabled: false
+
+Layout/LineEndStringConcatenationIndentation:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.0.40] - 2024-04-01
+### Added
+- `RedisQueuedLocks::Client#clear_dead_requests` implementation;
+- Logger and instrumentation are passed everywhere where any changes in Redis (with locks and queus)
+  are expected;
+- New config `is_timed_by_default` (boolean, `false` by default) that reflects the `timed` option of `#lock` and `#lock!` methods;
+- Ther result of `#unlock` is changed: added `:lock_res` and `:queue_res` result data in order to reflect
+  what happened inside (`:released` or `:nothing_to_release`) and to adopt to the case when you trying
+  to unlock the non-existent lock;
+- A lot of documentation updates;
+- Github CI Workflow;
+### Changed
+- `:rel_key_cnt` result of `#clear_locks` is more accurate now;
+
 ## [0.0.39] - 2024-03-31
 ### Added
 - Logging:

data/README.md

@@ -1,6 +1,6 @@
 # RedisQueuedLocks · [![Gem Version](https://badge.fury.io/rb/redis_queued_locks.svg)](https://badge.fury.io/rb/redis_queued_locks)
 
-Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
+<a href="https://redis.io/docs/manual/patterns/distributed-locks/">Distributed locks</a> with "lock acquisition queue" capabilities based on the Redis Database.
 
 Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttls, queue ttls, fast failing, etc), logging and instrumentation.
 
@@ -32,6 +32,7 @@ Each lock request is put into the request queue (each lock is hosted by it's own
   - [locks_info](#locks_info---get-list-of-locks-with-their-info)
   - [queues_info](#queues_info---get-list-of-queues-with-their-info)
   - [clear_dead_requests](#clear_dead_requests)
+- [Logging](#logging)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
@@ -43,14 +44,19 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 ### Requirements
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - Redis Version: `~> 7.x`;
 - Redis Protocol: `RESP3`;
 - gem `redis-client`: `~> 0.20`;
+- Ruby: `>= 3.1`;
 
 ---
 
 ### Experience
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - Battle-tested on huge ruby projects in production: `~1500` locks-per-second are obtained and released on an ongoing basis;
 - Works well with `hiredis` driver enabled (it is enabled by default on our projects where `redis_queued_locks` are used);
 
@@ -58,6 +64,8 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 ### Algorithm
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 > Each lock request is put into the request queue (each lock is hosted by it's own queue separately from other queues) and processed in order of their priority (FIFO). Each lock request lives some period of time (RTTL) which guarantees that the request queue will never be stacked.
 
 **Soon**: detailed explanation.
@@ -66,6 +74,8 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 ### Installation
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 ```ruby
 gem 'redis_queued_locks'
 ```
@@ -84,6 +94,8 @@ require 'redis_queued_locks'
 
 ### Setup
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 ```ruby
 require 'redis_queued_locks'
 
@@ -105,6 +117,8 @@ rq_lock_client.lock("some-lock") { puts "Hello, lock!" }
 
 ### Configuration
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 ```ruby
 redis_client = RedisClient.config.new_pool # NOTE: provide your own RedisClient instance
 
@@ -131,6 +145,10 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - lock request timeout. after this timeout your lock request in queue will be requeued with new position (at the end of the queue);
   config.default_queue_ttl = 15
 
+  # (boolean) (default: false)
+  # - should be all blocks of code are timed by default;
+  config.is_timed_by_default = false
+
   # (default: 100)
   # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic (uses SCAN);
   # - affects the performancs of your Redis and Ruby Application (configure thoughtfully);
@@ -167,6 +185,7 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id");
   #   - "[redis_queued_locks.lock_obtained]" (logs "lockkey", "queue_ttl", "acq_id", "acq_time");
   #   - "[redis_queued_locks.fail_fast_or_limits_reached__dequeue] (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
@@ -182,7 +201,7 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id");
   #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "<current_lock_data>");
   #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-  #   - "[redis_queued_locks.try_lock.obtain_free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id");
   config.log_lock_try = false
 end
 ```
@@ -191,6 +210,8 @@ end
 
 ### Usage
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - [lock](#lock---obtain-a-lock)
 - [lock!](#lock---exeptional-lock-obtaining)
 - [lock_info](#lock_info)
@@ -211,6 +232,8 @@ end
 
 #### #lock - obtain a lock
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - If block is passed the obtained lock will be released after the block execution or the lock's ttl (what will happen first);
 - If block is not passed the obtained lock will be released after lock's ttl;
 - If block is passed the block's yield result will be returned;
@@ -237,48 +260,64 @@ def lock(
 )
 ```
 
-- `lock_name` - `[String]`
+- `lock_name` - (required) `[String]`
   - Lock name to be obtained.
-- `ttl` [Integer]
-  - Lock's time to live (in milliseconds).
-- `queue_ttl` - `[Integer]`
+- `ttl` - (optional) - [Integer]
+  - Lock's time to live (in milliseconds);
+  - pre-configured in `config[:default_lock_ttl]`;
+- `queue_ttl` - (optional) `[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".
-- `timed` - `[Boolean]`
+  - pre-configured in `config[:default_queue_ttl]`;
+- `timeout` - (optional) `[Integer,NilClass]`
+  - Time period a client should try to acquire the lock (in seconds). Nil means "without timeout".
+  - pre-configured in `config[:try_to_lock_timeout]`;
+- `timed` - (optiona) `[Boolean]`
   - Limit the invocation time period of the passed block of code by the lock's TTL.
-- `retry_count` - `[Integer,NilClass]`
+  - pre-configured in `config[:is_timed_by_default]`;
+  - `false` by default;
+- `retry_count` - (optional) `[Integer,NilClass]`
   - How many times we should try to acquire a lock. Nil means "infinite retries".
-- `retry_delay` - `[Integer]`
+  - pre-configured in `config[:retry_count]`;
+- `retry_delay` - (optional) `[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 retry count limit.
-- `fail_fast` - `[Boolean]`
+  - pre-configured in `config[:retry_delay]`;
+- `retry_jitter` - (optional) `[Integer]`
+  - Time-shift range for retry-delay (in milliseconds);
+  - pre-configured in `config[:retry_jitter]`;
+- `instrumenter` - (optional) `[#notify]`
+  - See RedisQueuedLocks::Instrument::ActiveSupport for example;
+  - See [Instrumentation](#instrumentation) section of docs;
+  - pre-configured in `config[:isntrumenter]` with void notifier (`RedisQueuedLocks::Instrumenter::VoidNotifier`);
+- `raise_errors` - (optional) `[Boolean]`
+  - Raise errors on library-related limits such as timeout or retry count limit;
+  - `false` by default;
+- `fail_fast` - (optional) `[Boolean]`
     - Should the required lock to be checked before the try and exit immidietly if lock is
       already obtained;
     - Should the logic exit immidietly after the first try if the lock was obtained
       by another process while the lock request queue was initially empty;
-- `identity` - `[String]`
+    - `false` by default;
+- `identity` - (optional) `[String]`
   - An unique string that is unique per `RedisQueuedLock::Client` instance. Resolves the
     collisions between the same process_id/thread_id/fiber_id/ractor_id identifiers on different
     pods or/and nodes of your application;
   - It is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`
     ivar (accessed via `uniq_dentity` accessor method);
-- `meta` - `[NilClass,Hash<String|Symbol,Any>]`
+  - Identity calculator is pre-configured in `config[:uniq_identifier]`;
+- `meta` - (optional) `[NilClass,Hash<String|Symbol,Any>]`
   - A custom metadata wich will be passed to the lock data in addition to the existing data;
   - Custom metadata can not contain reserved lock data keys (such as `lock_key`, `acq_id`, `ts`, `ini_ttl`, `rem_ttl`);
-- `instrument` - `[NilClass,Any]`
+  - `nil` by default (means "no metadata");
+- `instrument` - (optional) `[NilClass,Any]`
   - Custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
-- `logger` - `[::Logger,#debug]`
-  - Logger object used from the configuration layer (see config[:logger]);
-  - See `RedisQueuedLocks::Logging::VoidLogger` for example;
-- `log_lock_try` - `[Boolean]`
+  - `nil` by default (means "no custom instrumentation data");
+- `logger` - (optional) `[::Logger,#debug]`
+  - Logger object used for loggin internal mutation oeprations and opertioan results / process progress;
+  - pre-configured in `config[:logger]` with void logger `RedisQueuedLocks::Logging::VoidLogger`;
+- `log_lock_try` - (optional) `[Boolean]`
   - should be logged the each try of lock acquiring (a lot of logs can be generated depending on your retry configurations);
-  - see `config[:log_lock_try]`;
+  - pre-configured in `config[:log_lock_try]`;
+  - `false` by default;
 - `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);
@@ -286,8 +325,25 @@ def lock(
 
 Return value:
 
-- If block is passed the block's yield result will be returned;
-- If block is not passed the lock information will be returned;
+- If block is passed the block's yield result will be returned:
+  ```ruby
+  result = rql.lock("my_lock") { 1 + 1 }
+  result # => 2
+  ```
+- If block is not passed the lock information will be returned:
+  ```ruby
+  result = rql.lock("my_lock")
+  result # =>
+  {
+    ok: true,
+    result: {
+      lock_key: "rql:lock:my_lock",
+      acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
+      ts: 1711909612.653696,
+      ttl: 10000
+    }
+  }
+  ```
 - Lock information result:
   - Signature: `[yield, Hash<Symbol,Boolean|Hash<Symbol,Numeric|String>>]`
   - Format: `{ ok: true/false, result: <Symbol|Hash<Symbol,Hash>> }`;
@@ -298,11 +354,23 @@ Return value:
       result: {
         lock_key: String, # acquierd lock key ("rql:lock:your_lock_name")
         acq_id: String, # acquier identifier ("process_id/thread_id/fiber_id/ractor_id/identity")
-        ts: Integer, # time (epoch) when lock was obtained (integer)
+        ts: Float, # time (epoch) when lock was obtained (float, Time#to_f)
         ttl: Integer # lock's time to live in milliseconds (integer)
       }
     }
     ```
+    ```ruby
+    # example:
+    {
+      ok: true,
+      result: {
+        lock_key: "rql:lock:my_lock",
+        acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
+        ts: 1711909612.653696,
+        ttl: 10000
+      }
+    }
+    ```
   - for failed lock obtaining:
     ```ruby
     { ok: false, result: :timeout_reached }
@@ -312,10 +380,61 @@ Return value:
     { ok: false, result: :unknown }
     ```
 
+Examples:
+
+- obtain a lock:
+
+```ruby
+rql.lock("my_lock") { print "Hello!" }
+```
+
+- obtain a lock with custom lock TTL:
+
+```ruby
+rql.lock("my_lock", ttl: 5_000) { print "Hello!" } # for 5 seconds
+```
+
+- obtain a lock and limit the passed block of code TTL with lock's TTL:
+
+```ruby
+rql.lock("my_lock", ttl: 5_000, timed: true) { sleep(4) }
+# => OK
+
+rql.lock("my_lock", ttl: 5_000, timed: true) { sleep(6) }
+# => fails with RedisQueuedLocks::TimedLockTimeoutError
+```
+
+- infinite lock obtaining (no retry limit, no timeout limit):
+
+```ruby
+rql.lock("my_lock", retry_count: nil, timeout: nil)
+```
+
+- try to obtain with a custom waiting timeout:
+
+```ruby
+# First Ruby Process:
+rql.lock("my_lock", ttl: 5_000) { sleep(4) } # acquire a long living lock
+
+# Another Ruby Process:
+rql.lock("my_lock", timeout: 2) # try to acquire but wait for a 2 seconds maximum
+# =>
+{ ok: false, result: :timeout_reached }
+```
+
+- obtain a lock and immediatly continue working (the lock will live in the background in Redis with the passed ttl)
+
+```ruby
+rql.lock("my_lock", ttl: 6_500) # blocks execution until the lock is obtained
+puts "Let's go" # will be called immediately after the lock is obtained
+```
+
 ---
 
 #### #lock! - exceptional lock obtaining
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - fails when (and with):
   - (`RedisQueuedLocks::LockAlreadyObtainedError`) when `fail_fast` is `true` and lock is already obtained;
   - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
@@ -346,6 +465,8 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 
 #### #lock_info
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - get the lock information;
 - returns `nil` if lock does not exist;
 - lock data (`Hash<String,String|Integer>`):
@@ -391,6 +512,14 @@ rql.lock_info("your_lock_name")
 
 #### #queue_info
 
+<sup>\[[back to top](#usage)\]</sup>
+
+Returns an information about the required lock queue by the lock name. The result
+represnts the ordered lock request queue that is ordered by score (Redis Sets) and shows
+lock acquirers and their position in queue. Async nature with redis communcation can lead
+the situation when the queue becomes empty during the queue data extraction. So sometimes
+you can receive the lock queue info with empty queue value (an empty array).
+
 - get the lock queue information;
 - queue represents the ordered set of lock key reqests:
   - set is ordered by score in ASC manner (inside the Redis Set);
@@ -403,14 +532,6 @@ rql.lock_info("your_lock_name")
     - `"acq_id"` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity by default);
     - `"score"` - `float`/`epoch` - time when the lock request was made (epoch);
 
-```
-| Returns an information about the required lock queue by the lock name. The result
-| represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
-| lock acquirers and their position in queue. Async nature with redis communcation can lead
-| the situation when the queue becomes empty during the queue data extraction. So sometimes
-| you can receive the lock queue info with empty queue value (an empty array).
-```
-
 ```ruby
 rql.queue_info("your_lock_name")
 
@@ -430,6 +551,8 @@ rql.queue_info("your_lock_name")
 
 #### #locked?
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - is the lock obtaied or not?
 
 ```ruby
@@ -450,26 +573,47 @@ rql.queued?("your_lock_name") # => true/false
 
 #### #unlock - release a lock
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - 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.
+- accepts:
+  - `lock_name` - (required) `[String]` - the lock name that should be released.
+  - `:logger` - (optional) `[::Logger,#debug]`
+    - custom logger object;
+    - pre-configured in `config[:logger]`;
+  - `:instrumenter` - (optional) `[#notify]`
+    - custom instrumenter object;
+    - pre-configured in `config[:instrumetner]`;
+  - `:instrument` - (optional) `[NilClass,Any]`;
+    - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
+    - `nil` by default (no additional data);
+- if you try to unlock non-existent lock you will receive `ok: true` result with operation timings
+  and `:nothing_to_release` result factor inside;
 
 Return:
-- `[Hash<Symbol,Numeric|String>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric|String> }`;
+- `[Hash<Symbol,Boolean|Hash<Symbol,Numeric|String|Symbol>>]` (`{ ok: true/false, result: Hasn }`);
+- `:result` format;
+  - `:rel_time` - `Float` - time spent to process redis commands (in seconds);
+  - `:rel_key` - `String` - released lock key (RedisQueudLocks-internal lock key name from Redis);
+  - `:rel_queue` - `String` - released lock queue key (RedisQueuedLocks-internal queue key name from Redis);
+  - `:queue_res` - `Symbol` - `:released` (or `:nothing_to_release` if the required queue does not exist);
+  - `:lock_res` - `Symbol` - `:released` (or `:nothing_to_release` if the required lock does not exist);
+
+Consider that `lock_res` and `queue_res` can have different value because of the async nature of invoked Redis'es commands.
 
 ```ruby
+rql.unlock("your_lock_name")
+
+# =>
 {
   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
+    queue_res: :released, # or :nothing_to_release
+    lock_res: :released # or :nothing_to_release
   }
 }
 ```
@@ -478,25 +622,38 @@ Return:
 
 #### #clear_locks - release all locks and lock queues
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - release all obtained locks and related lock request queues;
 - queues will be released first;
+- accepts:
+  - `:batch_size` - (optional) `[Integer]`
+    - the size of batch of locks and lock queus that should be cleared under the one pipelined redis command at once;
+    - pre-configured in `config[:lock_release_batch_size]`;
+  - `:logger` - (optional) `[::Logger,#debug]`
+    - custom logger object;
+    - has a preconfigured value in `config[:logger]`;
+  - `:instrumenter` - (optional) `[#notify]`
+    - custom instrumenter object;
+    - has a preconfigured value in `config[:isntrumenter]`;
+  - `:instrument` - (optional) `[NilClass,Any]`
+    - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
 
-```ruby
-def clear_locks(batch_size: config[:lock_release_batch_size])
-```
-
-- `batch_size` - `[Integer]`
-  - the size of batch of locks and lock queus that should be cleared under the one pipelined redis command at once;
-
-Return:
-- `[Hash<Symbol,Numeric>]` - Format: `{ ok: true/false, result: Hash<Symbol,Numeric> }`;
+- returns:
+ - `[Hash<Symbol,Numeric>]` - Format: `{ ok: true, result: Hash<Symbol,Numeric> }`;
+ - result data:
+  - `:rel_time` - `Numeric` - time spent to release all locks and related queus;
+  - `:rel_key_cnt` - `Integer` - the number of released Redis keys (queues+locks);
 
 ```ruby
+rql.clear_locks
+
+# =>
 {
   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)
+    rel_time: 3.07,
+    rel_key_cnt: 1234
   }
 }
 ```
@@ -505,7 +662,18 @@ Return:
 
 #### #extend_lock_ttl
 
-- Extend the lock's TTL (in milliseconds);
+<sup>\[[back to top](#usage)\]</sup>
+
+- extends lock ttl by the required number of milliseconds;
+- expects the lock name and the number of milliseconds;
+- accepts:
+  - `lock_name` - (required) `[String]`
+    - the lock name which ttl should be extended;
+  - `milliseconds` - (required) `[Integer]`
+    - how many milliseconds should be added to the lock's TTL;
+  - `:logger` - (optional) `[::Logger,#debug]`
+    - custom logger object;
+    - pre-configured in `config[:logger]`;
 - returns `{ ok: true, result: :ttl_extended }` when ttl is extended;
 - returns `{ ok: false, result: :async_expire_or_no_lock }` when lock not found or lock is expired during
   some steps of invocation (see **Important** section below);
@@ -535,6 +703,8 @@ rql.extend_lock_ttl("my_lock", 5_000) # NOTE: add 5_000 milliseconds
 
 #### #locks - get list of obtained locks
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - uses redis `SCAN` under the hood;
 - accepts:
   - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -565,6 +735,8 @@ rql.locks # or rql.locks(scan_size: 123)
 
 #### #queues - get list of lock request queues
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - uses redis `SCAN` under the hood;
 - accepts
   - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -595,6 +767,8 @@ rql.queues # or rql.queues(scan_size: 123)
 
 #### #keys - get list of taken locks and queues
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - uses redis `SCAN` under the hood;
 - accepts:
   `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -626,6 +800,8 @@ rql.keys # or rql.keys(scan_size: 123)
 
 #### #locks_info - get list of locks with their info
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - uses redis `SCAN` under the hod;
 - accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
 - returns `Set<Hash<Symbol,Any>>` (see [#lock_info](#lock_info) and examples below for details).
@@ -658,6 +834,8 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
 
 #### #queues_info - get list of queues with their info
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - uses redis `SCAN` under the hod;
 - accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
 - returns `Set<Hash<Symbol,Any>>` (see [#queue_info](#queue_info) and examples below for details).
@@ -685,12 +863,91 @@ rql.queues_info # or rql.qeuues_info(scan_size: 123)
 
 #### #clear_dead_requests
 
-- soon
+<sup>\[[back to top](#usage)\]</sup>
+
+In some cases your lock requests may become "dead". It can happen when your processs
+that are enqueeud to the lock queue is failed unexpectedly (for some reason) before the lock acquire moment
+and when no any other process does not need this lock anymore. For this case your lock will be cleared only when any process
+will try to acquire this lock again (cuz lock acquirement triggers the removement of expired requests).
+
+In order to help with these dead requests you may periodically call `#clear_dead_requests`
+with corresponding `dead_ttl` option, that is pre-configured by default via `config[:dead_request_ttl]`.
+
+An option is required because of it is no any **fast** way to understand which request
+is dead now and is it really dead cuz each request queue can host their requests with
+a custom queue ttl for each request differently.
+
+Accepts:
+- `:dead_ttl` - (optional) `[Integer]`
+  - lock request ttl after which a lock request is considered dead;
+  - has a preconfigured value in `config[:dead_request_ttl]` (1 day by default);
+- `:sacn_size` - (optional) `[Integer]`
+  - the batch of scanned keys for Redis'es SCAN command;
+  - has a preconfigured valie in `config[:key_extraction_batch_size]`;
+- `:logger` - (optional) `[::Logger,#debug]`
+  - custom logger object;
+  - pre-configured in `config[:logger]`;
+- `:instrumenter` - (optional) `[#notify]`
+  - custom instrumenter object;
+  - pre-configured in `config[:isntrumenter]`;
+- `:instrument` - (optional) `[NilClass,Any]`
+  - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
+  - `nil` by default (no additional data);
+
+Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
+
+```ruby
+rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
+
+# =>
+{
+  ok: true,
+  processed_queues: [
+    "rql:lock_queue:some-lock-123",
+    "rql:lock_queue:some-lock-456",
+    "rql:lock_queue:your-other-lock",
+    ...
+  ]
+}
+```
+
+---
+
+## Logging
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+- default logs (raised from `#lock`/`#lock!`):
+
+```ruby
+"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.dead_score_reached__reset_acquier_position]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.lock_obtained]" # (logs "lockkey", "queue_ttl", "acq_id", "acq_time");
+"[redis_queued_locks.fail_fast_or_limits_reached__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id");
+```
+
+- additional logs (raised from `#lock`/`#lock!` with `confg[:log_lock_try] == true`):
+
+```ruby
+"[redis_queued_locks.try_lock.start]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.rconn_fetched]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id)";
+"[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "<current_lock_data>");
+"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
+"[redis_queued_locks.try_lock.obtain__free_to_acquire]" # (logs "lock_key", "queue_ttl", "acq_id");
+```
 
 ---
 
 ## Instrumentation
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - [Instrumentation Events](#instrumentation-events)
 
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
@@ -702,8 +959,8 @@ Instrumenter object should provide `notify(event, payload)` method with the foll
 
 `redis_queued_locks` provides two instrumenters:
 
-- `RedisQueuedLocks::Instrument::ActiveSupport` - `ActiveSupport::Notifications` instrumenter
-  that instrument events via `ActiveSupport::Notifications` API;
+- `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").
@@ -712,17 +969,20 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 ### Instrumentation Events
 
+<sup>\[[back to top](#instrumentation-events)\]</sup>
+
 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`
+- `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;
+  - raised from `#lock`/`#lock!`;
   - payload:
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
     - `:acq_id` - `string` - lock acquier identifier;
@@ -730,9 +990,10 @@ Detalized event semantics and payload structure:
     - `:ts` - `integer`/`epoch` - the time when the lock was obtaiend;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
     - `:instrument` - `nil`/`Any` - custom data passed to the `lock`/`lock!` method as `:instrument` attribute;
+
 - `"redis_queued_locks.lock_hold_and_release"`
-  - an event signalizes about the "hold+and+release" process
-    when the lock obtained and hold by the block of logic;
+  - an event signalizes about the "hold+and+release" process is finished;
+  - raised from `#lock`/`#lock!` when invoked with a block of code;
   - payload:
     - `:hold_time` - `float`/`milliseconds` - lock hold time;
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
@@ -741,15 +1002,19 @@ Detalized event semantics and payload structure:
     - `:ts` - `integer`/`epoch` - the time when lock was obtained;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
     - `:instrument` - `nil`/`Any` - custom data passed to the `lock`/`lock!` method as `:instrument` attribute;
+
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
+  - raised from `#unlock`;
   - payload:
     - `:at` - `float`/`epoch` - the time when the lock was released;
     - `:rel_time` - `float`/`milliseconds` - time spent on lock releasing;
     - `:lock_key` - `string` - released lock (lock name);
     - `:lock_key_queue` - `string` - released lock queue (lock queue name);
+
 - `"redis_queued_locks.explicit_all_locks_release"`
   - an event signalizes about the explicit all locks release (invoked via `RedisQueuedLock#clear_locks`);
+  - raised from `#clear_locks`;
   - payload:
     - `:rel_time` - `float`/`milliseconds` - time spent on "realese all locks" operation;
     - `:at` - `float`/`epoch` - the time when the operation has ended;
@@ -759,8 +1024,10 @@ Detalized event semantics and payload structure:
 
 ## Roadmap
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - Semantic Error objects for unexpected Redis errors;
-- better specs :) with 100% test coverage;
+- better specs with 100% test coverage;
 - per-block-holding-the-lock sidecar `Ractor` and `in progress queue` in RedisDB that will extend
   the acquired lock for long-running blocks of code (that invoked "under" the lock
   whose ttl may expire before the block execution completes). It only makes sense for non-`timed` locks;
@@ -769,14 +1036,15 @@ Detalized event semantics and payload structure:
 - structured logging (separated docs);
 - GitHub Actions CI;
 - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
-- better code stylization and interesting refactorings (observers);
-- dead requests cleanup;
+- better code stylization (+ some refactorings);
 - statistics with UI;
 
 ---
 
 ## Contributing
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 - 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'`)
@@ -785,8 +1053,12 @@ Detalized event semantics and payload structure:
 
 ## License
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 Released under MIT License.
 
 ## Authors
 
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
 [Rustam Ibragimov](https://github.com/0exp)

data/lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb

@@ -200,7 +200,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               if log_lock_try
                 run_non_critical do
                   logger.debug do
-                    "[redis_queued_locks.try_lock.obtain_free_to_acquire] " \
+                    "[redis_queued_locks.try_lock.obtain__free_to_acquire] " \
                     "lock_key => '#{lock_key}' " \
                     "queue_ttl => #{queue_ttl} " \
                     "acq_id => '#{acquier_id}'"

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -23,11 +23,11 @@ module RedisQueuedLocks::Acquier::AcquireLock
   # @since 0.1.0
   extend RedisQueuedLocks::Utilities
 
-  # @return [Integer] Redis expiration error (in milliseconds).
+  # @return [Integer] Redis time error (in milliseconds).
   #
   # @api private
   # @since 0.1.0
-  REDIS_EXPIRE_ERROR = 1
+  REDIS_TIMESHIFT_ERROR = 2
 
   class << self
     # @param redis [RedisClient]
@@ -146,9 +146,6 @@ module RedisQueuedLocks::Acquier::AcquireLock
         ractor_id,
         identity
       )
-      # NOTE:
-      #   - think aobut the redis expiration error
-      #   - (ttl - REDIS_EXPIRE_ERROR).yield_self { |val| (val == 0) ? ttl : val }
       lock_ttl = ttl
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
@@ -324,7 +321,11 @@ module RedisQueuedLocks::Acquier::AcquireLock
         if block_given?
           begin
             yield_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
-            ttl_shift = ((yield_time - acq_process[:acq_end_time]) * 1000).ceil(2)
+
+            ttl_shift = (
+              (yield_time - acq_process[:acq_end_time]) * 1000 - REDIS_TIMESHIFT_ERROR
+            ).ceil(2)
+
             yield_with_expire(
               redis,
               logger,

data/lib/redis_queued_locks/acquier/clear_dead_requests.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::ClearDeadRequests
+  class << self
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @param dead_ttl [Integer] In milliseconds
+    # @param logger [::Logger,#debug]
+    # @param instrumenter [#notify]
+    # @param instrument [NilClass,Any]
+    # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
+    #
+    # @api private
+    # @since 0.1.0
+    def clear_dead_requests(redis_client, scan_size, dead_ttl, logger, instrumenter, instrument)
+      dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1000.0)
+
+      result = Set.new.tap do |processed_queues|
+        redis_client.with do |rconn|
+          each_lock_queue(rconn, scan_size) do |lock_queue|
+            rconn.call('ZREMRANGEBYSCORE', lock_queue, '-inf', dead_score)
+            processed_queues << lock_queue
+          end
+        end
+      end
+
+      RedisQueuedLocks::Data[ok: true, result: { processed_queues: result }]
+    end
+
+    private
+
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @yield [lock_queue]
+    # @yieldparam lock_queue [String]
+    # @yieldreturn [void]
+    # @return [Enumerator]
+    #
+    # @api private
+    # @since 0.1.0
+    def each_lock_queue(redis_client, scan_size, &block)
+      redis_client.scan(
+        'MATCH',
+        RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+        count: scan_size,
+        &block
+      )
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -16,14 +16,15 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
     # @param redis_client [RedisClient]
     # @param lock_name [String]
     # @param milliseconds [Integer]
+    # @param logger [::Logger,#debug]
     # @return [Hash<Symbol,Boolean|Symbol>]
     #
     # @api private
     # @since 0.1.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
       lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
 
-      # NOTE: EVAL signature -> <lua script>, (keys number), *(keys), *(arguments)
+      # NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)
       result = redis_client.call('EVAL', EXTEND_LOCK_PTTL, 1, lock_key, milliseconds)
       # TODO: upload scripts to the redis
 

data/lib/redis_queued_locks/acquier/locks.rb

@@ -12,8 +12,10 @@ module RedisQueuedLocks::Acquier::Locks
     # @api private
     # @since 0.1.0
     def locks(redis_client, scan_size:, with_info:)
-      lock_keys = scan_locks(redis_client, scan_size)
-      with_info ? extract_locks_info(redis_client, lock_keys) : lock_keys
+      redis_client.with do |rconn|
+        lock_keys = scan_locks(rconn, scan_size)
+        with_info ? extract_locks_info(rconn, lock_keys) : lock_keys
+      end
     end
 
     private

data/lib/redis_queued_locks/acquier/queues.rb

@@ -12,8 +12,10 @@ module RedisQueuedLocks::Acquier::Queues
     # @api private
     # @since 0.1.0
     def queues(redis_client, scan_size:, with_info:)
-      lock_queues = scan_queues(redis_client, scan_size)
-      with_info ? extract_queues_info(redis_client, lock_queues) : lock_queues
+      redis_client.with do |rconn|
+        lock_queues = scan_queues(rconn, scan_size)
+        with_info ? extract_queues_info(rconn, lock_queues) : lock_queues
+      end
     end
 
     private

data/lib/redis_queued_locks/acquier/release_all_locks.rb

@@ -15,17 +15,20 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #   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.
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @param isntrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @option instrument [NilClass,Any]
+    #    - Custom instrumentation data wich will be passed to the instrumenter's payload
+    #      with :instrument key;
     # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
-    #   Format: { ok: true/false, result: Hash<Symbol,Numeric> }
+    #   Format: { ok: true, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 0.1.0
-    def release_all_locks(redis, batch_size, instrumenter, logger)
+    def release_all_locks(redis, batch_size, logger, instrumenter, instrument)
       rel_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
       fully_release_all_locks(redis, batch_size) => { ok:, result: }
       time_at = Time.now.to_f
@@ -36,13 +39,13 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
         instrumenter.notify('redis_queued_locks.explicit_all_locks_release', {
           at: time_at,
           rel_time: rel_time,
-          rel_keys: result[:rel_keys]
+          rel_key_cnt: result[:rel_key_cnt]
         })
       end
 
       RedisQueuedLocks::Data[
         ok: true,
-        result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time }
+        result: { rel_key_cnt: result[:rel_key_cnt], rel_time: rel_time }
       ]
     end
 
@@ -52,7 +55,8 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
     #
     # @param redis [RedisClient]
     # @param batch_size [Integer]
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Integer>>]
+    #   - Exmaple: { ok: true, result: { rel_key_cnt: 12345 } }
     #
     # @api private
     # @since 0.1.0
@@ -66,8 +70,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
             count: batch_size
           ) do |lock_queue|
             # TODO: reduce unnecessary iterations
-            pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
-            pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
+            pipeline.call('EXPIRE', lock_queue, '0')
           end
 
           # Step B: release all locks
@@ -82,9 +85,7 @@ module RedisQueuedLocks::Acquier::ReleaseAllLocks
         end
       end
 
-      rel_keys = result.count { |red_res| red_res == 0 }
-
-      RedisQueuedLocks::Data[ok: true, result: { rel_keys: rel_keys }]
+      RedisQueuedLocks::Data[ok: true, result: { rel_key_cnt: result.sum }]
     end
   end
 end

data/lib/redis_queued_locks/acquier/release_lock.rb

@@ -23,8 +23,8 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config[:logger]);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
-    #   Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean<Hash<Symbol,Numeric|String|Symbol>>]
+    #   Format: { ok: true/false, result: Hash<Symbol,Numeric|String|Symbol> }
     #
     # @api private
     # @since 0.1.0
@@ -49,7 +49,13 @@ module RedisQueuedLocks::Acquier::ReleaseLock
 
       RedisQueuedLocks::Data[
         ok: true,
-        result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue }
+        result: {
+          rel_time: rel_time,
+          rel_key: lock_key,
+          rel_queue: lock_key_queue,
+          queue_res: result[:queue],
+          lock_res: result[:lock]
+        }
       ]
     end
 
@@ -60,7 +66,14 @@ module RedisQueuedLocks::Acquier::ReleaseLock
     # @param redis [RedisClient]
     # @param lock_key [String]
     # @param lock_key_queue [String]
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Symbol>>]
+    #   Format: {
+    #     ok: true/false,
+    #     result: {
+    #       queue: :released/:nothing_to_release,
+    #       lock: :released/:nothing_to_release
+    #     }
+    #   }
     #
     # @api private
     # @since 0.1.0
@@ -72,7 +85,13 @@ module RedisQueuedLocks::Acquier::ReleaseLock
         end
       end
 
-      RedisQueuedLocks::Data[ok: true, result:]
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: {
+          queue: (result[0] != 0) ? :released : :nothing_to_release,
+          lock: (result[1] != 0) ? :released : :nothing_to_release
+        }
+      ]
     end
   end
 end

data/lib/redis_queued_locks/acquier.rb

@@ -14,4 +14,5 @@ module RedisQueuedLocks::Acquier
   require_relative 'acquier/queues'
   require_relative 'acquier/keys'
   require_relative 'acquier/extend_lock_ttl'
+  require_relative 'acquier/clear_dead_requests'
 end

data/lib/redis_queued_locks/client.rb

@@ -20,6 +20,8 @@ class RedisQueuedLocks::Client
     setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
     setting :logger, RedisQueuedLocks::Logging::VoidLogger
     setting :log_lock_try, false
+    setting :dead_request_ttl, (1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds
+    setting :is_timed_by_default, false
 
     validate('retry_count') { |val| val == nil || (val.is_a?(::Integer) && val >= 0) }
     validate('retry_delay') { |val| val.is_a?(::Integer) && val >= 0 }
@@ -32,6 +34,8 @@ class RedisQueuedLocks::Client
     validate('uniq_identifier', :proc)
     validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
     validate('log_lock_try', :boolean)
+    validate('dead_request_ttl') { |val| val.is_a?(::Integer) && val > 0 }
+    validate('is_timed_by_default', :boolean)
   end
 
   # @return [RedisClient]
@@ -40,15 +44,14 @@ class RedisQueuedLocks::Client
   # @since 0.1.0
   attr_reader :redis_client
 
+  # NOTE: attr_access here is chosen intentionally in order to have an ability to change
+  #  uniq_identity value for debug purposes in runtime;
   # @return [String]
   #
   # @api private
   # @since 0.1.0
   attr_accessor :uniq_identity
 
-  # NOTE: attr_access is chosen intentionally in order to have an ability to change
-  #  uniq_identity values for debug purposes in runtime;
-
   # @param redis_client [RedisClient]
   #   Redis connection manager, which will be used for the lock acquierment and distribution.
   #   It should be an instance of RedisClient.
@@ -119,7 +122,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
-    timed: false,
+    timed: config[:is_timed_by_default],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -167,7 +170,7 @@ class RedisQueuedLocks::Client
     ttl: config[:default_lock_ttl],
     queue_ttl: config[:default_queue_ttl],
     timeout: config[:try_to_lock_timeout],
-    timed: false,
+    timed: config[:is_timed_by_default],
     retry_count: config[:retry_count],
     retry_delay: config[:retry_delay],
     retry_jitter: config[:retry_jitter],
@@ -191,20 +194,38 @@ class RedisQueuedLocks::Client
       raise_errors: true,
       identity:,
       fail_fast:,
+      logger:,
+      log_lock_try:,
       meta:,
       instrument:,
       &block
     )
   end
 
-  # @param lock_name [String]
-  #   The lock name that should be released.
+  # @param lock_name [String] The lock name that should be released.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
   # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  #   Format: {
+  #     ok: true/false,
+  #     result: {
+  #       rel_time: Integer, # <millisecnds>
+  #       rel_key: String, # lock key
+  #       rel_queue: String, # lock queue
+  #       queue_res: Symbol, # :released or :nothing_to_release
+  #       lock_res: Symbol # :released or :nothing_to_release
+  #     }
+  #   }
   #
   # @api public
   # @since 0.1.0
-  def unlock(lock_name)
+  def unlock(
+    lock_name,
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
     RedisQueuedLocks::Acquier::ReleaseLock.release_lock(
       redis_client,
       lock_name,
@@ -268,26 +289,41 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 0.1.0
-  def extend_lock_ttl(lock_name, milliseconds)
+  def extend_lock_ttl(lock_name, milliseconds, logger: config[:logger])
     RedisQueuedLocks::Acquier::ExtendLockTTL.extend_lock_ttl(
       redis_client,
       lock_name,
-      milliseconds
+      milliseconds,
+      logger
     )
   end
 
+  # Releases all queues and locks.
+  # Returns:
+  #   - :rel_time - (milliseconds) - time spent to release all locks and queues;
+  #   - :rel_key_cnt - (integer) - the number of released redis keys (queus+locks);
+  #
   # @option batch_size [Integer]
-  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
-  #   Format: { ok: true/false, result: Symbol/Hash }.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Boolean|Hash<Symbol,Numeric>>]
+  #   Example: { ok: true, result { rel_key_cnt: 100, rel_time: 0.01 } }
   #
   # @api public
   # @since 0.1.0
-  def clear_locks(batch_size: config[:lock_release_batch_size])
+  def clear_locks(
+    batch_size: config[:lock_release_batch_size],
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
     RedisQueuedLocks::Acquier::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
-      config[:instrumenter],
-      config[:logger]
+      logger,
+      instrumenter,
+      instrument
     )
   end
 
@@ -364,5 +400,36 @@ class RedisQueuedLocks::Client
   def keys(scan_size: config[:key_extraction_batch_size])
     RedisQueuedLocks::Acquier::Keys.keys(redis_client, scan_size:)
   end
+
+  # @option dead_ttl [Integer]
+  #  - the time period (in millsiecnds) after whcih the lock request is
+  #    considered as dead;
+  #  - `config[:dead_request_ttl]` is used by default;
+  # @option scan_size [Integer]
+  #   The batch of scanned keys for Redis'es SCAN command.
+  # @option logger [::Logger,#debug]
+  # @option instrumenter [#notify]
+  # @option instrument [NilClass,Any]
+  # @return [Hash<Symbol,Boolean|Hash<Symbol,Set<String>>>]
+  #   Format: { ok: true, result: { processed_queus: Set<String> } }
+  #
+  # @api public
+  # @since 0.1.0
+  def clear_dead_requests(
+    dead_ttl: config[:dead_request_ttl],
+    scan_size: config[:key_extraction_batch_size],
+    logger: config[:logger],
+    instrumenter: config[:instrumenter],
+    instrument: nil
+  )
+    RedisQueuedLocks::Acquier::ClearDeadRequests.clear_dead_requests(
+      redis_client,
+      scan_size,
+      dead_ttl,
+      logger,
+      instrumenter,
+      instrument
+    )
+  end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.39
+  version: 0.0.40
 platform: ruby
 authors:
 - Rustam Ibragimov
@@ -61,6 +61,7 @@ files:
 - lib/redis_queued_locks/acquier/acquire_lock/try_to_lock.rb
 - lib/redis_queued_locks/acquier/acquire_lock/with_acq_timeout.rb
 - lib/redis_queued_locks/acquier/acquire_lock/yield_with_expire.rb
+- lib/redis_queued_locks/acquier/clear_dead_requests.rb
 - lib/redis_queued_locks/acquier/extend_lock_ttl.rb
 - lib/redis_queued_locks/acquier/is_locked.rb
 - lib/redis_queued_locks/acquier/is_queued.rb