redis_queued_locks 1.1.0 → 1.3.0

data/README.md

@@ -1,11 +1,11 @@
 # RedisQueuedLocks · ![Gem Version](https://img.shields.io/gem/v/redis_queued_locks) ![build](https://github.com/0exp/redis_queued_locks/actions/workflows/build.yml/badge.svg??branch=master)
 
-<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.
+<a href="https://redis.io/docs/manual/patterns/distributed-locks/">Distributed locks</a> with "prioritized lock acquisition queue" capabilities based on the Redis Database.
 
 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) (with requeue capabilities) which guarantees the request queue will never be stacked.
 
+Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttls, queue ttls, lock attempts limit, fast failing, etc), logging and instrumentation.
+
 ---
 
 ## Table of Contents
@@ -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)
+- [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks)
 - [Logging](#logging)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
@@ -57,7 +58,7 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 <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;
+- Battle-tested on huge ruby projects in production: `~3000` 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);
 
 ---
@@ -149,9 +150,22 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - should be all blocks of code are timed by default;
   config.is_timed_by_default = false
 
+  # (symbol) (default: :wait_for_lock)
+  # - The conflict strategy mode for cases when the process that obtained the lock want to acquire this lock again;
+  # - Realizes "reentrant locks" abstraction (same process conflict / same process deadlock);
+  # - By default uses `:wait_for_lock` strategy (classic way);
+  # - Strategies:
+  #   - `:work_through` - continue working under the lock <without> lock's TTL extension;
+  #   - `:extendable_work_through` - continue working under the lock <with> lock's TTL extension;
+  #   - `:wait_for_lock` - (default) - work in classic way (with timeouts, retry delays, retry limits, etc - in classic way :));
+  #   - `:dead_locking` - fail with deadlock exception;
+  # - Can be customized in methods via `:conflict_strategy` attribute (see method signatures of #lock and #lock! methods);
+  # - See "Dead locks and Reentrant Locks" documentation section in REDME.md for details;
+  config.default_conflict_strategy = :wait_for_lock
+
   # (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);
+  # - how many items will be released at a time in #clear_locks and in #clear_dead_requests (uses SCAN);
+  # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
   config.lock_release_batch_size = 100
 
   # (default: 500)
@@ -185,13 +199,17 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # (default: RedisQueuedLocks::Logging::VoidLogger)
   # - the logger object;
   # - should implement `debug(progname = nil, &block)` (minimal requirement) or be an instance of Ruby's `::Logger` class/subclass;
+  # - supports `SemanticLogger::Logger` (see "semantic_logger" gem)
   # - at this moment the only debug logs are realised in following cases:
   #   - "[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");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
@@ -201,6 +219,10 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - it adds following logs in addition to the existing:
   #   - "[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.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_ext_ttl", "last_ext_ts");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "spc_status", last_spc_ts);
   #   - "[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");
@@ -257,6 +279,7 @@ def lock(
   retry_jitter: config[:retry_jitter],
   raise_errors: false,
   fail_fast: false,
+  conflict_strategy: config[:default_conflict_strategy],
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   meta: nil,
   instrument: nil,
@@ -295,7 +318,7 @@ def lock(
   - 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;
+  - Raise errors on library-related limits (such as timeout or retry count limit) and on lock conflicts (such as same-process dead locks);
   - `false` by default;
 - `fail_fast` - (optional) `[Boolean]`
     - Should the required lock to be checked before the try and exit immidietly if lock is
@@ -303,6 +326,17 @@ def lock(
     - 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;
     - `false` by default;
+- `conflict_strategy` - (optional) - `[Symbol]``
+  - The conflict strategy mode for cases when the process that obtained the lock
+    want to acquire this lock again;
+  - By default uses `:wait_for_lock` strategy;
+  - pre-confured in `config[:default_conflict_strategy]`;
+  - Strategies:
+    - `:work_through` - continue working under the lock **without** lock's TTL extension;
+    - `:extendable_work_through` - continue working under the lock **with** lock's TTL extension;
+    - `:wait_for_lock` - (default) - work in classic way (with timeouts, retry delays, retry limits, etc - in classic way :));
+    - `:dead_locking` - fail with deadlock exception;
+  - See [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) readme section for details;
 - `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
@@ -324,10 +358,12 @@ def lock(
   - should be logged the each try of lock acquiring (a lot of logs can be generated depending on your retry configurations);
   - pre-configured in `config[:log_lock_try]`;
   - `false` by default;
-- `block` - `[Block]`
+- `block` - (optional) `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
   - If block is **not passed** the obtained lock will be released after it's ttl;
+  - If you want the block to have a TTL too and this TTL to be the same as TTL of the lock
+    use `timed: true` option (`rql.lock("my_lock", timed: true, ttl: 5_000) { ... }`)
 
 Return value:
 
@@ -346,14 +382,21 @@ Return value:
       lock_key: "rql:lock:my_lock",
       acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
       ts: 1711909612.653696,
-      ttl: 10000
+      ttl: 10000,
+      process: :lock_obtaining
     }
   }
   ```
 - Lock information result:
   - Signature: `[yield, Hash<Symbol,Boolean|Hash<Symbol,Numeric|String>>]`
   - Format: `{ ok: true/false, result: <Symbol|Hash<Symbol,Hash>> }`;
-  - for successful lock obtaining:
+  - Includes the `:process` key that describes a logical type of the lock obtaining process. Possible values:
+    - `:lock_obtaining` - classic lock obtaining proces. Default behavior (`conflict_strategy: :wait_for_lock`);
+    - `:extendable_conflict_work_through` - reentrant lock acquiring process with lock's TTL extension. Suitable for `conflict_strategy: :extendable_work_through`;
+    - `:conflict_work_through` - reentrant lock acquiring process without lock's TTL extension. Suitable for `conflict_strategy: :work_through`;
+    - `:dead_locking` - current process tries to acquire a lock that is already acquired by them. Suitalbe for `conflict_startegy: :dead_locking`;
+    - For more details see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) readme section;
+  - For successful lock obtaining:
     ```ruby
     {
       ok: true,
@@ -361,10 +404,12 @@ Return value:
         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: Float, # time (epoch) when lock was obtained (float, Time#to_f)
-        ttl: Integer # lock's time to live in milliseconds (integer)
+        ttl: Integer, # lock's time to live in milliseconds (integer)
+        process: Symbol # which logical process has acquired the lock (:lock_obtaining, :extendable_conflict_work_through, :conflict_work_through, :conflict_dead_lock)
       }
     }
     ```
+
     ```ruby
     # example:
     {
@@ -373,14 +418,16 @@ Return value:
         lock_key: "rql:lock:my_lock",
         acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
         ts: 1711909612.653696,
-        ttl: 10000
+        ttl: 10000,
+        process: :lock_obtaining # for custom conflict strategies may be: :conflict_dead_lock, :conflict_work_through, :extendable_conflict_work_through
       }
     }
     ```
-  - for failed lock obtaining:
+  - For failed lock obtaining:
     ```ruby
     { ok: false, result: :timeout_reached }
     { ok: false, result: :retry_count_reached }
+    { ok: false, result: :conflict_dead_lock } # see <conflict_strategy> option for details (:dead_locking strategy)
     { ok: false, result: :fail_fast_no_try } # see <fail_fast> option
     { ok: false, result: :fail_fast_after_try } # see <fail_fast> option
     { ok: false, result: :unknown }
@@ -453,6 +500,43 @@ rql.lock_info("my_lock")
 }
 ```
 
+- (`:queue_ttl`) setting a short limit of time to the lock request queue position (if a process fails to acquire
+  the lock within this period of time (and before timeout/retry_count limits occurs of course) -
+  it's lock request will be moved to the end of queue):
+
+```ruby
+rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
+# "queue_ttl: 5": 5 seconds time slot before the lock request moves to the end of queue;
+# "timeout" and "retry_count" is used as "endless lock try attempts" example to show the lock queue behavior;
+
+# lock queue: =>
+[
+ "rql:acq:123/456/567/676/374dd74324", 
+ "rql:acq:123/456/567/677/374dd74322", # <- long living lock
+ "rql:acq:123/456/567/679/374dd74321",
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+]
+
+# ... some period of time (2 seconds later)
+# lock queue: =>
+[
+ "rql:acq:123/456/567/677/374dd74322", # <- long living lock
+ "rql:acq:123/456/567/679/374dd74321",
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+]
+
+# ... some period of time (3 seconds later)
+# ... queue_ttl time limit is reached
+# lock queue: =>
+[
+ "rql:acq:123/456/567/685/374dd74329", # some other waiting process
+ "rql:acq:123/456/567/683/374dd74322", # <== we are here (moved to the end of the queue)
+]
+
+```
+
 ---
 
 #### #lock! - exceptional lock obtaining
@@ -469,16 +553,18 @@ def lock!(
   lock_name,
   ttl: config[:default_lock_ttl],
   queue_ttl: config[:default_queue_ttl],
-  timeout: config[:default_timeout],
+  timeout: config[:try_to_lock_timeout],
+  timed: config[:is_timed_by_default],
   retry_count: config[:retry_count],
   retry_delay: config[:retry_delay],
   retry_jitter: config[:retry_jitter],
-  identity: uniq_identity,
   fail_fast: false,
+  identity: uniq_identity,
   meta: nil,
-  instrument: nil,
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
+  instrument: nil,
+  conflict_strategy: config[:default_conflict_strategy],
   &block
 )
 ```
@@ -496,27 +582,36 @@ See `#lock` method [documentation](#lock---obtain-a-lock).
 - lock data (`Hash<String,String|Integer>`):
   - `"lock_key"` - `string` - lock key in redis;
   - `"acq_id"` - `string` - acquier identifier (process_id/thread_id/fiber_id/ractor_id/identity);
-  - `"ts"` - `integer`/`epoch` - the time lock was obtained;
+  - `"ts"` - `numeric`/`epoch` - the time when lock was obtained;
   - `"init_ttl"` - `integer` - (milliseconds) initial lock key ttl;
   - `"rem_ttl"` - `integer` - (milliseconds) remaining lock key ttl;
-  - `custom metadata`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock]((#lock---obtain-a-lock)) method documentation);
+  - `<custom metadata>`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock]((#lock---obtain-a-lock)) method documentation);
+  - additional keys for **reentrant locks** and **extendable reentrant locks**:
+    - for any type of reentrant locks:
+      - `"spc_cnt"` - `integer` - how many times the lock was obtained as reentrant lock;
+    - for non-extendable reentrant locks:
+      - `"l_spc_ts"` - `numeric`/`epoch` - timestamp of the last **non-extendable** reentrant lock obtaining;
+    - for extendalbe reentrant locks:
+      - `"spc_ext_ttl"` - `integer` - (milliseconds) sum of TTL of the each **extendable** reentrant lock (the total TTL extension time);
+      - `"l_spc_ext_ini_ttl"` - `integer` - (milliseconds) TTL of the last reentrant lock;
+      - `"l_spc_ext_ts"` - `numeric`/`epoch` - timestamp of the last extendable reentrant lock obtaining;
 
 ```ruby
-# without custom metadata
+# <without custom metadata>
 rql.lock_info("your_lock_name")
 
 # =>
 {
   "lock_key" => "rql:lock:your_lock_name",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "ts" => 123456789,
-  "ini_ttl" => 123456789,
-  "rem_ttl" => 123456789
+  "ts" => 123456789.12345,
+  "ini_ttl" => 5_000,
+  "rem_ttl" => 4_999
 }
 ```
 
 ```ruby
-# with custom metadata
+# <with custom metadata>
 rql.lock("your_lock_name", meta: { "kek" => "pek", "bum" => 123 })
 rql.lock_info("your_lock_name")
 
@@ -524,14 +619,41 @@ rql.lock_info("your_lock_name")
 {
   "lock_key" => "rql:lock:your_lock_name",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "ts" => 123456789,
-  "ini_ttl" => 123456789,
-  "rem_ttl" => 123456789,
+  "ts" => 123456789.12345,
+  "ini_ttl" => 5_000,
+  "rem_ttl" => 4_999,
   "kek" => "pek",
   "bum" => "123" # NOTE: returned as a raw string directly from Redis
 }
 ```
 
+```ruby
+# <for reentrant locks>
+# (see `conflict_strategy:` kwarg attribute of #lock/#lock! methods and `config.default_conflict_strategy` config)
+
+rql.lock("your_lock_name", ttl: 5_000)
+rql.lock("your_lock_name", ttl: 3_000)
+rql.lock("your_lock_name", ttl: 2_000)
+rql.lock_info("your_lock_name")
+
+# =>
+{
+  "lock_key" => "rql:lock:your_lock_name",
+  "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+  "ts" => 123456789.12345,
+  "ini_ttl" => 5_000,
+  "rem_ttl" => 9_444,
+  # ==> keys for any type of reentrant lock:
+  "spc_count" => 2, # how many times the lock was obtained as reentrant lock
+  # ==> keys for extendable reentarnt locks with `:extendable_work_through` strategy:
+  "spc_ext_ttl" => 5_000, # sum of TTL of the each <extendable> reentrant lock (3_000 + 2_000)
+  "l_spc_ext_ini_ttl" => 2_000, # TTL of the last <extendable> reentrant lock
+  "l_spc_ext_ts" =>  123456792.12345 # timestamp of the last <extendable> reentrant lock obtaining
+  # ==> keys for non-extendable locks with `:work_through` strategy:
+  "l_spc_ts" => 123456.789 # timestamp of the last <non-extendable> reentrant lock obtaining
+}
+```
+
 ---
 
 #### #queue_info
@@ -563,9 +685,9 @@ rql.queue_info("your_lock_name")
 {
   "lock_queue" => "rql:lock_queue:your_lock_name",
   "queue" => [
-    { "acq_id" => "rql:acq:123/456/567/678/fa76df9cc2", "score" => 1},
-    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 2},
-    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 3},
+    { "acq_id" => "rql:acq:123/456/567/678/fa76df9cc2", "score" => 1711606640.540842},
+    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 1711606640.540906},
+    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 1711606640.540963},
     # ...etc
   ]
 }
@@ -587,6 +709,8 @@ rql.locked?("your_lock_name") # => true/false
 
 #### #queued?
 
+<sup>\[[back to top](#usage)\]</sup>
+
 - is the lock queued for obtain / has requests for obtain?
 
 ```ruby
@@ -635,7 +759,7 @@ rql.unlock("your_lock_name")
   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
+    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
   }
@@ -662,12 +786,11 @@ rql.unlock("your_lock_name")
     - pre-configured value in `config[:isntrumenter]`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
-
 - 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);
+  - `[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
@@ -699,13 +822,14 @@ rql.clear_locks
     - 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
+- returns `{ ok: false, result: :async_expire_or_no_lock }` when a lock not found or a lock is already expired during
   some steps of invocation (see **Important** section below);
 - **Important**:
   - the method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension;
   - the method consists of two commands:
     - (1) read current pttl;
     - (2) set new ttl that is calculated as "current pttl + additional milliseconds";
+  - the method uses Redis'es **CAS** (check-and-set) behavior;
   - what can happen during these steps:
     - lock is expired between commands or before the first command;
     - lock is expired before the second command;
@@ -729,6 +853,7 @@ rql.extend_lock_ttl("my_lock", 5_000) # NOTE: add 5_000 milliseconds
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- get list of obtained locks;
 - uses redis `SCAN` under the hood;
 - accepts:
   - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -761,6 +886,7 @@ rql.locks # or rql.locks(scan_size: 123)
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- get list of lock request queues;
 - uses redis `SCAN` under the hood;
 - accepts
   - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -793,6 +919,7 @@ rql.queues # or rql.queues(scan_size: 123)
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- get list of taken locks and queues;
 - uses redis `SCAN` under the hood;
 - accepts:
   `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
@@ -826,6 +953,7 @@ rql.keys # or rql.keys(scan_size: 123)
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- get list of locks with their info;
 - 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).
@@ -834,7 +962,9 @@ rql.keys # or rql.keys(scan_size: 123)
   - `:status` - `Symbol`- `:released` or `:alive`
     - the lock may become relased durign the lock info extraction process;
     - `:info` for `:released` keys is empty (`{}`);
-  - `:info` - `Hash<String,Any>` - lock data stored in the lock key in Redis. See [#lock_info](#lock_info) for details;
+  - `:info` - `Hash<String,Any>`
+      - lock data stored in the lock key in Redis;
+      - See [#lock_info](#lock_info) for details;
 
 ```ruby
 rql.locks_info # or rql.locks_info(scan_size: 123)
@@ -860,6 +990,7 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- get list of queues with their info;
 - 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).
@@ -908,7 +1039,7 @@ Accepts:
   - 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]`;
+  - has a preconfigured valie in `config[:lock_release_batch_size]`;
 - `:logger` - (optional) `[::Logger,#debug]`
   - custom logger object;
   - pre-configured in `config[:logger]`;
@@ -938,6 +1069,20 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 
 ---
 
+## Dead locks and Reentrant locks
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+- **documentation is in progress**
+- (little details for a context of current implementation and feautres):
+  - at this moment we support only **reentrant locks**: they works via customizable conflict strategy behavior;
+  - in non-reentrant conflict cases your lock obtaining process will work in a classic way (some dead lock conflict => work in "wait for lock" style);
+  - for current implementation details check:
+    - (Configuration)[#configuration] documentation: see `config.default_conflict_strategy` config docs;
+    - (#lock)[#lock] method documentation: see `conflict_strategy` attribute docs;
+
+---
+
 ## Logging
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -948,9 +1093,12 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 "[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.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acq_time");
+"[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id");
 "[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id");
 ```
 
 - additional logs (raised from `#lock`/`#lock!` with `confg[:log_lock_try] == true`):
@@ -958,6 +1106,11 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 ```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.same_process_conflict_detected]" # (logs "lock_key", "queue_ttl", "acq_id");
+"[redis_queued_locks.try_lock.same_process_conflict_analyzed]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status");
+"[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_ext_ttl", "last_ext_ts");
+"[redis_queued_locks.try_lock.reentrant_lock__work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", last_spc_ts);
+"[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "spc_status", "last_spc_ts");
 "[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");
@@ -994,12 +1147,15 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 
 ### Instrumentation Events
 
-<sup>\[[back to top](#instrumentation-events)\]</sup>
+<sup>\[[back to top](#instrumentation)\]</sup>
 
 List of instrumentation events
 
 - `redis_queued_locks.lock_obtained`;
+- `redis_queued_locks.extendable_reentrant_lock_obtained`;
+- `redis_queued_locks.reentrant_lock_obtained`;
 - `redis_queued_locks.lock_hold_and_release`;
+- `redis_queued_locks.reentrant_lock_hold_completes`;
 - `redis_queued_locks.explicit_lock_release`;
 - `redis_queued_locks.explicit_all_locks_release`;
 
@@ -1012,9 +1168,31 @@ Detalized event semantics and payload structure:
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
     - `:acq_id` - `string` - lock acquier identifier;
     - `:lock_key` - `string` - lock name;
-    - `:ts` - `integer`/`epoch` - the time when the lock was obtaiend;
+    - `:ts` - `numeric`/`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.extendable_reentrant_lock_obtained"`
+  - an event signalizes about the "extendable reentrant lock" obtaining is happened;
+  - raised from `#lock`/`#lock!` when the lock was obtained as reentrant lock;
+  - payload:
+    - `:lock_key` - `string` - lock name;
+    - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
+    - `:acq_id` - `string` - lock acquier identifier;
+    - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as extendable reentrant lock;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
-    - `:instrument` - `nil`/`Any` - custom data passed to the `lock`/`lock!` method as `:instrument` attribute;
+    - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
+
+- `"redis_queued_locks.reentrant_lock_obtained"`
+  - an event signalizes about the "reentrant lock" obtaining is happened (without TTL extension);
+  - raised from `#lock`/`#lock!` when the lock was obtained as reentrant lock;
+  - payload:
+    - `:lock_key` - `string` - lock name;
+    - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
+    - `:acq_id` - `string` - lock acquier identifier;
+    - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as reentrant lock;
+    - `: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 is finished;
@@ -1024,9 +1202,22 @@ Detalized event semantics and payload structure:
     - `:ttl` - `integer`/`milliseconds` - lock ttl;
     - `:acq_id` - `string` - lock acquier identifier;
     - `:lock_key` - `string` - lock name;
-    - `:ts` - `integer`/`epoch` - the time when lock was obtained;
+    - `:ts` - `numeric`/`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;
+    - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
+
+- `"redis_queued_locks.reentrant_lock_hold_completes"`
+  - an event signalizes about the "reentrant lock hold" is complete (both extendable and non-extendable);
+  - lock re-entering can happen many times and this event happens for each of them separately;
+  - raised from `#lock`/`#lock!` when the lock was obtained as reentrant lock;
+  - payload:
+    - `:hold_time` - `float`/`milliseconds` - lock hold time;
+    - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
+    - `:acq_id` - `string` - lock acquier identifier;
+    - `:ts` - `numeric`/`epoch` - the time when the lock was obtaiend as reentrant lock;
+    - `:lock_key` - `string` - lock name;
+    - `: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`);
@@ -1051,18 +1242,29 @@ Detalized event semantics and payload structure:
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
-- **strict redlock algorithm support** (support for many `RedisClient` instances);
-- Semantic Error objects for unexpected Redis errors;
-- better specs with 100% test coverage (total rework);
-- (non-`timed` locks): per-ruby-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 makes sense for non-`timed` locks *only*;
-- lock request prioritization;
-- support for LIFO strategy;
-- more structured logging (separated docs);
-- `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
-- better code stylization (+ some refactorings);
-- statistics with UI;
+- **Major**:
+  - support for Random Access strategy (non-queued behavior);
+  - lock request prioritization;
+  - **strict redlock algorithm support** (support for many `RedisClient` instances);
+  - `#lock_series` - acquire a series of locks:
+    ```ruby
+    rql.lock_series('lock_a', 'lock_b', 'lock_c') { puts 'locked' }
+    ```
+  - support for `Dragonfly` database backend (https://github.com/dragonflydb/dragonfly) (https://www.dragonflydb.io/);
+- **Minor**:
+  - Semantic error objects for unexpected Redis errors;
+  - change all `::Process.clock_gettime(::Process::CLOCK_MONOTONIC)` milliseconds-related invocations to
+    `::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)` in order to reduce time-related math operations count;
+  - **Experimental feature**: (non-`timed` locks): per-ruby-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 makes sense for non-`timed` locks *only*;
+  - better code stylization (+ some refactorings);
+  - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
+  - Support for LIFO strategy;
+  - better specs with 100% test coverage (total specs rework);
+  - statistics with UI;
+  - JSON log formatter;
+  - `go`-lang implementation;
 
 ---
 

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::AcquireLock::DelayExecution
   # Sleep with random time-shifting (it is necessary for empty lock-acquirement time slots).
   #
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::DelayExecution
   # @return [void]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def delay_execution(retry_delay, retry_jitter)
     delay = (retry_delay + rand(retry_jitter)).to_f / 1_000
     sleep(delay)