redis_queued_locks 1.2.0 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b1c8d60f41d2dc4f3eda798efa02a4764b877e6666e8babd7cf1a7827a4b288
-  data.tar.gz: 983e142251b344055013aa2aac2965ad542d44f5c8f81ac410f97cdef7b216b3
+  metadata.gz: 5cac51b8b6c2a4986c188d7b419e11a282c4a18d6a32689000a2c9127f77eec3
+  data.tar.gz: d159e30574e503a714081dfda22d9085553818573ad968f745e302efe93edfde
 SHA512:
-  metadata.gz: 88b91754923e546767d03999601fb98bd04b00fb426e50691e2fd4ce1bf13e345c19179b534660a639d0a885d1fdad4db94ffda0fa4383d7d9dcf53981ca481b
-  data.tar.gz: f9368018c66eee962a9dd6be1b38efe7bb4359cdfb262956f4e2e43622aaf747b67b4aa6b7a9bcda6c8449e011cb1c2954d5a6e5324afdbfbb8eea0ca96085b0
+  metadata.gz: 6ee000a0470297832a593a8719a192feb5fdf583003d49f8dfb3335dad4c63aff45730cc8d4481a02eb41f629e60d929349fcc1842025117bd5b35304a09c8cd
+  data.tar.gz: c7e52ef09012e29a2ac1495fedc287c7a51c5fee8ceac466f78d5de548e8231b7a5c8fc29626db28ca82629ac0294b4ded991cbf5902f97a76619279bed4e353

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [1.3.1] - 2024-05-10
+### Fixed
+- `:meta` attribute type validation of `#lock`/`#lock!` was incorrect;
+### Added
+- documentation updates and clarifications;
+
+## [1.3.0] - 2024-05-08
+### Added
+- **Major Feature**: support for **Reentrant Locks**;
+- The result of lock obtaining now includes `:process` key that shows the type of logical process that obtains the lock
+  (`:lock_obtaining`, `:extendable_conflict_work_through`, `:conflict_work_through`, `:dead_locking`);
+- Added reentrant lock details to `RedisQueuedLocks::Client#lock_info` and `RedisQueuedLocks::Client#locks` method results;
+- Documentation updates;
+### Changed
+- Logging: `redis_queued_locks.fail_fast_or_limits_reached__dequeue` log is renamed to `redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue`
+  in order to reflect the lock conflict failures too;
+
 ## [1.2.0] - 2024-04-27
 ### Added
 - Documentation updates;

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,6 +150,20 @@ 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)
+  # - Global default conflict strategy mode;
+  # - Can be customized in methods `#lock` and `#lock` via `:conflict_strategy` attribute (see method signatures of #lock and #lock! methods);
+  # - Conflict strategy is a logical behavior 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;
+  # - 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 #clear_locks and in #clear_dead_requests (uses SCAN);
   # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
@@ -185,13 +200,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 +220,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");
@@ -240,10 +263,14 @@ end
 
 <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;
-- If block is not passed the lock information will be returned;
+- `#lock` - obtain a lock;
+- If block is passed:
+  - the obtained lock will be released after the block execution or the lock's ttl (what will happen first);
+    - if you want to timeout (fail with timeout) the block execution with lock's TTL use `timed: true` option;
+  - the block's result will be returned;
+- If block is not passed:
+  - the obtained lock will be released after lock's ttl;
+  - the lock information will be returned (hash with technical info that contains: lock key, acquier identifier, acquirement timestamp, lock's ttl, type of obtaining process, etc);
 
 ```ruby
 def lock(
@@ -257,6 +284,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 +323,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 +331,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
@@ -348,14 +387,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,
@@ -363,10 +409,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:
     {
@@ -375,14 +423,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 }
@@ -498,26 +548,30 @@ rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
 
 <sup>\[[back to top](#usage)\]</sup>
 
+- `#lock!` - exceptional lock obtaining;
 - 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;
   - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
+  - (`RedisQueuedLocks::ConflictLockObtainError`) when `conflict_strategy: :dead_locking` is used and the "same-process-dead-lock" is happened (see [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) for details);
 
 ```ruby
 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
 )
 ```
@@ -535,27 +589,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")
 
@@ -563,14 +626,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
@@ -770,6 +860,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);
@@ -802,6 +893,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);
@@ -834,6 +926,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);
@@ -867,6 +960,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).
@@ -875,7 +969,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)
@@ -901,6 +997,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).
@@ -979,6 +1076,24 @@ 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>
+
+- **this documentation section is in progress**;
+- (little details for a context of the current implementation and feautres):
+  - at this moment we support only **reentrant locks**: they works via customizable conflict strategy behavior
+    (`:wait_for_lock` (default), `:work_through`, `:extendable_work_through`, `:dead_locking`);
+  - by default behavior (`:wait_for_lock`) your lock obtaining process will work in a classic way (limits, retries, etc);
+  - `:work_through`, `:extendable_work_through` works with limits too (timeouts, delays, etc), but the decision of
+    "is your lock are obtained or not" is made as you work with **reentrant locks** (your process continues to use the lock without/without
+    lock's TTL accordingly);
+  - for current implementation details check:
+    - [Configuration](#configuration) documentation: see `config.default_conflict_strategy` config docs;
+    - [#lock](#lock---obtain-a-lock) method documentation: see `conflict_strategy` attribute docs and the method result data;
+
+---
+
 ## Logging
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -989,9 +1104,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`):
@@ -999,6 +1117,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");
@@ -1040,7 +1163,10 @@ By default `RedisQueuedLocks::Client` is configured with the void notifier (whic
 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`;
 
@@ -1053,9 +1179,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;
@@ -1065,9 +1213,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`);
@@ -1092,20 +1253,29 @@ Detalized event semantics and payload structure:
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
-- **strict redlock algorithm support** (support for many `RedisClient` instances);
-- deadlock detection (with some options for auto-resolving);
-- 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;
-- support for Random Access 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;
 
 ---