redis_queued_locks 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd9e0ee49d4c08d6ba572a825da792468926b2f676e872a2337b1ce2eff60836
-  data.tar.gz: ae635ac450f966539581c4b5a53098b92ba29562bb0641049571ca0ceb1461e7
+  metadata.gz: 7f8dd117ee12f1f598da555d02516bb950a2d9640b075a048612726b7a88a6ad
+  data.tar.gz: c0a5ac4a4dcb6f3b448dc23ffa8d0e0e13a726d50bdd98fc40193704aa6f967d
 SHA512:
-  metadata.gz: b678b3fbccd5273d17d07120c144b0eb1c6be32db73ff1aa2f9fb19f485d30499645f3c4592fad0cb4cdeab1ebcd37f437b62740e01a46dce999eaaa2814f146
-  data.tar.gz: b8cb79c79767cd1d3b831992454c84c8399f6bf7ac313b8a2d0a7527711f555cb2196a172ae435103df2fc4c3e483b0a5b35775fba4baee7b7bad6234103cb0a
+  metadata.gz: b35d0ef98da0e1ec2c2368b36064eb0501b45d26aaa1b7204230692a41025583366ce181b85eec09cff2d6fe4e93ec146280db78e08f8cbb232a559b91f6d489
+  data.tar.gz: 4776dd89a7bf1e27476877465faf3240988929efe398090fa4b8b4f604a976a861558e6f606278b91c2c95530be6c5205f8245c887befe92a75d4efde31820dc

data/CHANGELOG.md

@@ -1,8 +1,24 @@
 ## [Unreleased]
 
+## [1.8.0] - 2024-06-13
+### Added
+- A configurable option that enables the adding additional lock/queue data to "Acquirement Timeout"-related error messages for better debugging;
+  - Configurable option is used beacuse of the extra error data requires some additional Redis requests that can be costly for memory/cpu/etc resources;
+- An ability to get the current acquirer id (`RedisQueuedLocks::Client#current_acquirer_id`);
+### Changed
+- Added additional lock information to some exceptions that does not require extra Redis requests;
+
+## [1.7.0] - 2024-06-12
+### Added
+- New feature: **Lock Access Strategy**: you can obtain a lock in different ways: `queued` (classic queued FIFO), `random` (get the lock immideatly if lock is free):
+  - `:queued` is used by default (classic `redis_queued_locks` behavior);
+  - `:random`: obtain a lock without checking the positions in the queue => if lock is free to obtain - it will be obtained;
+### Changed
+- Some logging refactorings, some instrumentation refactorings: the code that uses them is more readable and supportable;
+
 ## [1.6.0] - 2024-05-25
 ### Added
-- New Feature: **Instrumentation Sampling** - configurable instrumentation sampling based on `weight` algorithm (where the weight is a percentage of RQL cases that should be logged);
+- New Feature: **Instrumentation Sampling**: configurable instrumentation sampling based on `weight` algorithm (where the weight is a percentage of RQL cases that should be logged);
 - Missing instrumenter customization in public `RedisQueuedLocks::Client` methods;
 - Documentation updates;
 

data/README.md

@@ -4,6 +4,8 @@
 
 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.
 
+In addition to the classic `queued` (FIFO) strategy RQL supports `random` (RANDOM) lock obtaining strategy when any acquirer from the lock queue can obtain the lock regardless the position in the queue.
+
 Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), logging and instrumentation.
 
 ---
@@ -32,6 +34,10 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [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)
+  - [current_acquirer_id](#current_acquirer_id)
+- [Lock Access Strategies](#lock-access-strategies)
+  - [queued](#lock-access-strategies)
+  - [random](#lock-access-strategies)
 - [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks)
 - [Logging](#logging)
 - [Instrumentation](#instrumentation)
@@ -69,6 +75,8 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 
 > 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.
 
+> In addition to the classic "queued" (FIFO) strategy RQL supports "random" (RANDOM) lock obtaining strategy when any acquirer from the lock queue can obtain the lock regardless the position in the queue.
+
 **Soon**: detailed explanation.
 
 ---
@@ -150,9 +158,43 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - should be all blocks of code are timed by default;
   config.is_timed_by_default = false
 
+  # (boolean) (default: false)
+  # - When the lock acquirement try reached the acquirement time limit (:timeout option) the
+  #   `RedisQueuedLocks::LockAcquirementTimeoutError` is raised (when `raise_errors` option
+  #   of the #lock method is set to `true`). The error message contains the lock key name and
+  #   the timeout value).
+  # - <true> option adds the additional details to the error message:
+  #   - current lock queue state (you can see which acquirer blocks your request and
+  #     how much acquirers are in queue);
+  #   - current lock data stored inside (for example: you can check the current acquirer and
+  #     the lock meta state if you store some additional data there);
+  # - Realized as an option because of the additional lock data requires two additional Redis
+  #   queries: (1) get the current lock from redis and (2) fetch the lock queue state;
+  # - These two additional Redis queries has async nature so you can receive
+  #   inconsistent data of the lock and of the lock queue in your error emssage because:
+  #   - required lock can be released after the error moment and before the error message build;
+  #   - required lock can be obtained by other process after the error moment and
+  #     before the error message build;
+  #   - required lock queue can reach a state when the blocking acquirer start to obtain the lock
+  #     and moved from the lock queue after the error moment and before the error message build;
+  # - You should consider the async nature of this error message and should use received data
+  #   from error message correspondingly;
+  config.detailed_acq_timeout_error = false
+
+  # (symbol) (default: :queued)
+  # - Defines the way in which the lock should be obitained;
+  # - By default it is configured to obtain a lock in classic `queued` way:
+  #   you should wait your position in queue in order to obtain a lock;
+  # - Can be customized in methods `#lock` and `#lock!` via `:access_strategy` attribute (see method signatures of #lock and #lock! methods);
+  # - Supports different strategies:
+  #   - `:queued` (FIFO): the classic queued behavior (default), your lock will be obitaned if you are first in queue and the required lock is free;
+  #   - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist,
+  #     retries, timeouts and so on). if lock is free to obtain - it will be obtained;
+  config.default_access_strategy = :queued
+
   # (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);
+  # - 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);
@@ -202,15 +244,15 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - 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 "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");
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquier_position]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acq_time", "acs_strat");
+  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "acs_strat");
   # - by default uses VoidLogger that does nothing;
   config.logger = RedisQueuedLocks::Logging::VoidLogger
 
@@ -218,19 +260,19 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - adds additional debug logs;
   # - enables additional logs for each internal try-retry lock acquiring (a lot of logs can be generated depending on your retry configurations);
   # - 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");
-  #   - "[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.start]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_ext_ttl", "last_ext_ts");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", last_spc_ts);
+  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id, "acs_strat")";
+  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "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", "acs_strat");
   config.log_lock_try = false
 
   # (default: false)
@@ -298,6 +340,7 @@ end
 - [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)
+- [current_acquirer_id](#current_acquirer_id)
 
 ---
 
@@ -327,8 +370,10 @@ def lock(
   raise_errors: false,
   fail_fast: false,
   conflict_strategy: config[:default_conflict_strategy],
+  access_strategy: config[:default_access_strategy],
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
   meta: nil,
+  detailed_acq_timeout_error: config[:detailed_acq_timeout_error],
   instrument: nil,
   instrumenter: config[:instrumenter],
   logger: config[:logger],
@@ -378,12 +423,21 @@ def lock(
   - 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
-      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;
-    - `false` by default;
-- `conflict_strategy` - (optional) - `[Symbol]``
+  - 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;
+  - `false` by default;
+- `access_strategy` - (optional) - `[Symbol]`
+  - Defines the way in which the lock should be obitained (in queued way, in random way and so on);
+  - By default it is configured to obtain a lock in classic `:queued` way: you should wait your position in queue in order to obtain a lock;
+  - Supports following strategies:
+    - `:queued` (FIFO): (default) the classic queued behavior, your lock will be obitaned if you are first in queue and the required lock is free;
+    - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist, retries, timeouts and so on).
+      if lock is free to obtain - it will be obtained;
+  - pre-configured in `config[:default_access_strategy]`;
+  - See [Lock Access Strategies](#lock-access-strategies) documentation section for details;
+- `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;
@@ -393,7 +447,7 @@ def lock(
     - `: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;
+  - See [Dead locks and Reentrant locks](#dead-locks-and-reentrant-locks) documentation 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
@@ -405,6 +459,25 @@ def lock(
   - 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`);
   - `nil` by default (means "no metadata");
+- `detailed_acq_timeout_error` - (optional) `[Boolean]`
+  - When the lock acquirement try reached the acquirement time limit (:timeout option) the
+    `RedisQueuedLocks::LockAcquirementTimeoutError` is raised (when `raise_errors` option
+    set to `true`). The error message contains the lock key name and the timeout value).
+  - <true> option adds the additional details to the error message:
+    - current lock queue state (you can see which acquirer blocks your request and how much acquirers are in queue);
+    - current lock data stored inside (for example: you can check the current acquirer and the lock meta state if you store some additional data there);
+  - Realized as an option because of the additional lock data requires two additional Redis
+    queries: (1) get the current lock from redis and (2) fetch the lock queue state;
+  - These two additional Redis queries has async nature so you can receive
+    inconsistent data of the lock and of the lock queue in your error emssage because:
+    - required lock can be released after the error moment and before the error message build;
+    - required lock can be obtained by other process after the error moment and
+      before the error message build;
+    - required lock queue can reach a state when the blocking acquirer start to obtain the lock
+      and moved from the lock queue after the error moment and before the error message build;
+  - You should consider the async nature of this error message and should use received data
+    from error message correspondingly;
+  - pre-configred in `config[:detailed_acq_timeout_error]`;
 - `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`;
@@ -624,7 +697,51 @@ rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
  "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)
 ]
+```
+
+- obtain a lock in `:random` way (with `:random` strategy): in `:random` strategy
+  any acquirer from the lcok queue can obtain the lock regardless of the position in the lock queue;
+
+```ruby
+# Current Process (process#1)
+rql.lock('my_lock', ttl: 2_000, access_strategy: :random)
+# => holds the lock
+
+# Another Process (process#2)
+rql.lock('my_lock', retry_delay: 7000, ttl: 4000, access_strategy: :random)
+# => the lock is not free, stay in a queue and retry...
+
+# Another Process (process#3)
+rql.lock('my_lock', retry_delay: 3000, ttl: 3000, access_strategy: :random)
+# => the lock is not free, stay in a queue and retry...
 
+# lock queue:
+[
+ "rql:acq:123/456/567/677/374dd74322", # process#1 (holds the lock)
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, in retry)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (waiting for the lock, in retry)
+]
+
+# ... some period of time
+# -> process#1 => released the lock;
+# -> process#2 => delayed retry, waiting;
+# -> process#3 => preparing for retry (the delay is over);
+# lock queue:
+[
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, DELAYED)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (trying to obtain the lock, RETRYING now)
+]
+
+# ... some period of time
+# -> process#2 => didn't have time to obtain the lock, delayed retry;
+# -> process#3 => holds the lock;
+# lock queue:
+[
+ "rql:acq:123/456/567/679/374dd74321", # process#2 (waiting for the lock, DELAYED)
+ "rql:acq:123/456/567/683/374dd74322", # process#3 (holds the lock)
+]
+
+# `process#3` is the last in queue, but has acquired the lock because his lock request "randomly" came first;
 ```
 
 ---
@@ -653,10 +770,12 @@ def lock!(
   fail_fast: false,
   identity: uniq_identity,
   meta: nil,
+  detailed_acq_timeout_error: config[:detailed_acq_timeout_error]
   logger: config[:logger],
   log_lock_try: config[:log_lock_try],
   instrument: nil,
   instrumenter: config[:instrumenter],
+  access_strategy: config[:default_access_strategy],
   conflict_strategy: config[:default_conflict_strategy],
   log_sampling_enabled: config[:log_sampling_enabled],
   log_sampling_percent: config[:log_sampling_percent],
@@ -1246,6 +1365,59 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 
 ---
 
+#### #current_acquirer_id
+
+- get the current acquirer identifier in RQL notation that you can use for debugging purposes during the lock analyzation;
+- acquirer identifier format:
+  ```ruby
+    "rql:acq:#{process_id}/#{thread_id}/#{fiber_id}/#{ractor_id}/#{identity}"
+  ```
+- because of the moment that `#lock`/`#lock!` gives you a possibility to customize `process_id`,
+  `fiber_id`, `thread_id`, `ractor_id` and `unique identity` identifiers the `#current_acquirer_id` method provides this possibility too;
+
+Accepts:
+
+- `process_id:` - (optional) `[Integer,Any]`
+  - `::Process.pid` by default;
+- `thread_id:` - (optional) `[Integer,Any]`;
+  - `::Thread.current.object_id` by default;
+- `fiber_id:` - (optional) `[Integer,Any]`;
+  - `::Fiber.current.object_id` by default;
+- `ractor_id:` - (optional) `[Integer,Any]`;
+  - `::Ractor.current.object_id` by default;
+- `identity:` - (optional) `[String,Any]`;
+  - this value is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`;
+  - this value can be accessed from `RedisQueuedLock::Client#uniq_identity`;
+  - [Configuration](#configuration) documentation: see `config[:uniq_identifier]`;
+  - [#lock](#lock---obtain-a-lock) method documentation: see `uniq_identifier`;
+
+```ruby
+rql.current_acquirer_id
+
+# =>
+"rql:acq:38529/4500/4520/4360/66093702f24a3129"
+```
+
+---
+
+## Lock Access Strategies
+
+<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):
+  - defines the way in which the lock should be obitained;
+  - by default it is configured to obtain a lock in classic `queued` way: you should wait your position in queue in order to obtain a lock;
+  - can be customized in methods `#lock` and `#lock!` via `:access_strategy` attribute (see method signatures of #lock and #lock! methods);
+  - supports different strategies:
+    - `:queued` (FIFO): the classic queued behavior (default), your lock will be obitaned if you are first in queue and the required lock is free;
+    - `:random` (RANDOM): obtain a lock without checking the positions in the queue (but with checking the limist, retries, timeouts and so on). if lock is free to obtain - it will be obtained;
+  - for current implementation detalis check:
+    - [Configuration](#configuration) documentation: see `config.default_access_strategy` config docs;
+    - [#lock](#lock---obtain-a-lock) method documentation: see `access_strategy` attribute docs;
+
+---
+
 ## Dead locks and Reentrant locks
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -1271,34 +1443,34 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 - 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.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.dead_score_reached__reset_acquier_position]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
 "[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");
+"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "acq_time");
+"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "acq_time");
+"[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "acs_strat");
 ```
 
 - 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.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");
-"[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.start]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.rconn_fetched]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_detected]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.same_process_conflict_analyzed]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status");
+"[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_ext_ttl", "last_ext_ts");
+"[redis_queued_locks.try_lock.reentrant_lock__work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", last_spc_ts);
+"[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "spc_status", "last_spc_ts");
+"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat");
+"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "first_acq_id_in_queue", "<current_lock_data>");
+"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "acs_strat", "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", "acs_strat");
 ```
 
 ---
@@ -1424,7 +1596,6 @@ Detalized event semantics and payload structure:
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - **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:

data/lib/redis_queued_locks/acquier/acquire_lock/dequeue_from_lock_queue/log_visitor.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.7.0
+module RedisQueuedLocks::Acquier::AcquireLock::DequeueFromLockQueue::LogVisitor
+  extend self
+
+  # @param logger [::Logger,#debug]
+  # @param log_sampled [Boolean]
+  # @param lock_key [String]
+  # @param queue_ttl [Integer]
+  # @param acquier_id [String]
+  # @param access_strategy [Symbol]
+  # @return [void]
+  #
+  # @api private
+  # @since 1.7.0
+  def dequeue_from_lock_queue(
+    logger,
+    log_sampled,
+    lock_key,
+    queue_ttl,
+    acquier_id,
+    access_strategy
+  )
+    return unless log_sampled
+
+    logger.debug do
+      "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue] " \
+      "lock_key => '#{lock_key}' " \
+      "queue_ttl => #{queue_ttl} " \
+      "acq_id => '#{acquier_id}' " \
+      "acs_strat => '#{access_strategy}"
+    end rescue nil
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.7.0
+module RedisQueuedLocks::Acquier::AcquireLock::DequeueFromLockQueue
+  require_relative 'dequeue_from_lock_queue/log_visitor'
+
+  # @param redis [RedisClient]
+  # @param logger [::Logger,#debug]
+  # @param lock_key [String]
+  # @param lock_key_queue [String]
+  # @param queue_ttl [Integer]
+  # @param acquier_id [String]
+  # @param access_strategy [Symbol]
+  # @param log_sampled [Boolean]
+  # @param instr_sampled [Boolean]
+  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  #
+  # @api private
+  # @since 1.7.0
+  def dequeue_from_lock_queue(
+    redis,
+    logger,
+    lock_key,
+    lock_key_queue,
+    queue_ttl,
+    acquier_id,
+    access_strategy,
+    log_sampled,
+    instr_sampled
+  )
+    result = redis.call('ZREM', lock_key_queue, acquier_id)
+    LogVisitor.dequeue_from_lock_queue(
+      logger, log_sampled,
+      lock_key, queue_ttl, acquier_id, access_strategy
+    )
+    RedisQueuedLocks::Data[ok: true, result: result]
+  end
+end