redis_queued_locks 1.21.0 → 1.22.0

data/README.md

@@ -4,11 +4,11 @@
 
 **RedisQueuedLocks** (aka **RQL**, aka **RQL-lock**) - <a href="https://redis.io/docs/latest/develop/clients/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 its 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.
+Each lock request is put into the request queue (each lock is hosted by its own queue separately from other queues) and processed in order of their priority: requests of a higher [priority](#lock-request-prioritization) go first, requests of the same priority are processed in FIFO order. 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.
 
-Supports `Read`/`Write` locks and `Reentrant` locks.
+Supports [lock request prioritization](#lock-request-prioritization), `Read`/`Write` locks and `Reentrant` locks.
 
 Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), **zombie locks elimination**, **[lock indexing](#lock-index)**, logging and instrumentation (and much more).
 
@@ -71,6 +71,7 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 - [Lock Access Strategies](#lock-access-strategies)
   - [queued](#lock-access-strategies)
   - [random](#lock-access-strategies)
+- [Lock Request Prioritization](#lock-request-prioritization)
 - [Read/Write Locks](#readwrite-locks)
 - [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks)
 - [Logging](#logging)
@@ -125,7 +126,7 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
-> Each lock request is put into the request queue (each lock is hosted by its 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.
+> Each lock request is put into the request queue (each lock is hosted by its own queue separately from other queues) and processed in order of their priority: requests of a higher [priority](#lock-request-prioritization) go first, requests of the same priority are processed in FIFO order. 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.
 
@@ -205,7 +206,8 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   config['default_lock_ttl'] = 5_000
 
   # (seconds) (default: 15)
-  # - lock request timeout. after this timeout your lock request in queue will be requeued with new position (at the end of the queue);
+  # - lock request timeout. after this timeout your lock request in queue will be requeued with new position (at the end of the
+  #   lock requests of its priority);
   # - (the enabled lock index) the lock request queue lives as long as its latest lock request (the queue TTL is refreshed with
   #   the queue ttl on each lock request): queues of dead acquirers expire by themselves;
   # - should be a positive Integer
@@ -249,6 +251,30 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   #     retries, timeouts and so on). if lock is free to obtain - it will be obtained;
   config['default_access_strategy'] = :queued
 
+  # (hash) (default: { lowest: -100, low: -50, normal: 0, high: 50, highest: 100 })
+  # - Lock request priority names: a priority name (Symbol) => its priority (Integer from `-100` to `100`);
+  # - The names can be used instead of the Integer priorities in the `:priority` attribute and in
+  #   `config['default_lock_priority']`: `rql.lock('name', priority: :high) { ... }`;
+  # - Define the names of your application (keep the default names with `merge`):
+  #   `config['lock_priorities'] = config['lock_priorities'].merge(payment: 90, email: -10)`;
+  # - The default value is frozen (it is shared by all clients): assign a new hash, don't change it in place;
+  # - See [Lock Request Prioritization](#lock-request-prioritization) documentation section for details;
+  config['lock_priorities'] = { lowest: -100, low: -50, normal: 0, high: 50, highest: 100 }
+
+  # (integer/symbol) (default: 0)
+  # - The default lock request priority: an Integer from `-100` (the lowest) to `100` (the highest)
+  #   or a priority name of `config['lock_priorities']`;
+  # - The priority name should be a key of `config['lock_priorities']` (`RedisQueuedLocks::ConfigValidationError` otherwise):
+  #   it is checked once after the configuration block (`Client.new { ... }`, `#configure { ... }`: the keys can be assigned
+  #   in any order; an inconsistent pair is never applied: both keys keep their previous values, also when the block fails)
+  #   and on a direct `config[...] =` assignment (before the value is applied: change the priority names and the default
+  #   name together in a configuration block);
+  # - Can be customized in methods `#lock`, `#lock!`, `#lock_series` and `#lock_series!` via `:priority` attribute;
+  # - `:queued` access strategy: the lock request is placed in the lock request queue after all requests of the same
+  #   or higher priority and before all requests of the lower priority (FIFO inside the same priority);
+  # - See [Lock Request Prioritization](#lock-request-prioritization) documentation section for details;
+  config['default_lock_priority'] = 0
+
   # (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);
@@ -339,19 +365,19 @@ client = 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", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-  #   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
-  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+  #   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+  #   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+  #   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time", "result");
+  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
   #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
   #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
   #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-  #   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+  #   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+  #   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
   #   - "[redis_queued_locks.explicit_lock_release]" (logs "lock_key", "lock_key_queue", "rel_time", "at");
   #   - "[redis_queued_locks.explicit_read_lock_release]" (logs "lock_key", "acq_id", "lock_res", "rel_time", "at");
   #   - "[redis_queued_locks.explicit_all_locks_release]" (logs "at", "rel_time", "rel_key_cnt");
@@ -376,15 +402,16 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
   #   - "[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
   #   - "[redis_queued_locks.try_lock.single_process_lock_conflict__lock_upgrade]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
-  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
   #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.dead_request_removed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "dead_acq_id", "dead_priority");
+  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
   #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "<current_lock_data>");
-  #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-  #   - "[redis_queued_locks.try_lock.exit__write_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-  #   - "[redis_queued_locks.try_lock.exit__read_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-  #   - "[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "locked_by_acq_id", "<current_lock_data>");
+  #   - "[redis_queued_locks.try_lock.exit__write_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+  #   - "[redis_queued_locks.try_lock.exit__read_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+  #   - "[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
   #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
   #   - "rw_mode" is the requested lock mode ('write'/'read');
   config['log_lock_try'] = false
@@ -503,6 +530,7 @@ def lock(
   conflict_strategy: config['default_conflict_strategy'],
   read_write_mode: :write,
   access_strategy: config['default_access_strategy'],
+  priority: config['default_lock_priority'],
   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'],
@@ -563,7 +591,7 @@ def lock(
 - `instrumenter` - (optional) `[#notify]`
   - See RedisQueuedLocks::Instrument::ActiveSupport for example;
   - See [Instrumentation](#instrumentation) section of docs;
-  - pre-configured in `config['isntrumenter']` with void notifier (`RedisQueuedLocks::Instrumenter::VoidNotifier`);
+  - pre-configured in `config['instrumenter']` with void notifier (`RedisQueuedLocks::Instrument::VoidNotifier`);
 - `instrument` - (optional) `[NilClass,Any]`
   - Custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
   - `nil` by default (means "no custom instrumentation data");
@@ -585,6 +613,19 @@ def lock(
       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;
+- `priority` - (optional) - `[Integer,Symbol]`
+  - The lock request priority: an Integer from `-100` (the lowest) to `100` (the highest), `0` by default,
+    or a priority name of `config['lock_priorities']` (`:lowest`, `:low`, `:normal`, `:high`, `:highest` by default,
+    the names of your application can be configured);
+  - `:queued` access strategy: the lock request is placed in the lock request queue after all requests of the same or
+    higher priority and before all requests of the lower priority (strict priority, FIFO inside the same priority;
+    read and write lock requests too);
+  - `:random` access strategy: the lock request does not wait for its turn (it ignores the order of the lock request queues
+    and the priorities of other requests), but it is queued at the position of its priority like a `:queued` one: `:queued`
+    lock requests wait for it;
+  - the obtained lock is never taken away: the priority orders the waiting lock requests only;
+  - pre-configured in `config['default_lock_priority']`;
+  - See [Lock Request Prioritization](#lock-request-prioritization) 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;
@@ -834,7 +875,7 @@ 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) -
-  its lock request will be moved to the end of queue):
+  its lock request will be moved to the end of queue: the end of the lock requests of its priority):
 
 ```ruby
 rql.lock("my_lock", queue_ttl: 5, timeout: 10_000, retry_count: nil)
@@ -946,6 +987,7 @@ def lock!(
   instrument: nil,
   instrumenter: config['instrumenter'],
   access_strategy: config['default_access_strategy'],
+  priority: config['default_lock_priority'],
   conflict_strategy: config['default_conflict_strategy'],
   read_write_mode: :write,
   log_sampling_enabled: config['log_sampling_enabled'],
@@ -994,6 +1036,7 @@ applied with the same value to the each lock acquirement process (for each lock
   - reentrant locks (already obtained by your outer logic, `conflict_strategy: :work_through`/`:extendable_work_through`) are kept;
   - a lock that is expired during your block and obtained by another acquirer is kept;
 - `read_write_mode:` is the same for all locks of the series (see [Read/Write Locks](#readwrite-locks));
+- `priority:` is the same for all locks of the series (see [Lock Request Prioritization](#lock-request-prioritization));
 - if you did not pass a block - all locks will be released with their forumla-based TTL described above;
   - **HOW WILL THIS CASE WORK IN FUTURE RELESAE**: all locks will have the same TTL (`5 seconds` for our example, not `15/10/5 seconds`);
 
@@ -1074,9 +1117,9 @@ client.lock_seires('c', 'a', 'b') # ... `a` is still obtained
 
 ```shell
 # NEW logs (examples)
-[redis_queued_locks.start_lock_series_obtaining] lock_keys => '["rql:lock:a", "rql:lock:b"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write'
-[redis_queued_locks.lock_series_obtained] lock_keys => '["rql:lock:a", "rql:lock:b"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write' acq_time => 2.55 (ms)
-[redis_queued_locks.expire_lock_series] lock_keys => '["rql:lock:x", "rql:lock:y", "rql:lock:z"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write'
+[redis_queued_locks.start_lock_series_obtaining] lock_keys => '["rql:lock:a", "rql:lock:b"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write' priority => 0
+[redis_queued_locks.lock_series_obtained] lock_keys => '["rql:lock:a", "rql:lock:b"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write' priority => 0 acq_time => 2.55 (ms)
+[redis_queued_locks.expire_lock_series] lock_keys => '["rql:lock:x", "rql:lock:y", "rql:lock:z"]' queue_ttl => 15 acq_id => 'rql:acq:4486/1696/1704/1712/e6fd0da7991e4303' hst_id => 'rql:hst:4486/1696/1712/e6fd0da7991e4303' acs_strat => 'queued' rw_mode => 'write' priority => 0
 ```
 
 ----
@@ -1256,15 +1299,18 @@ lock acquirers and their position in queue. The queue of write lock requests is
 - get the lock queue information;
 - queue represents the ordered set of lock key reqests:
   - set is ordered by score in ASC manner (inside the Redis Set);
-  - score is represented as a timestamp when the lock request was made;
+  - score is represented as a timestamp when the lock request was made shifted by the
+    [priority](#lock-request-prioritization) band (`-priority * 2**32` seconds: the default priority `0` keeps the timestamp);
   - represents the acquirer identifier and their score as an array of hashes;
 - returns `nil` if lock queues (write and read) do not exist;
 - lock queue data (`Hash<String,String|Array<Hash<String|Numeric>>`):
   - `"lock_queue"` - `string` - lock queue key in redis (write lock requests);
   - `"queue"` - `array` - an array of lock requests (array of hashes):
     - `"acq_id"` - `string` - acquirer identifier (process_id/thread_id/fiber_id/ractor_id/identity by default);
-    - `"score"` - `float`/`epoch` - time when the lock request was made (epoch);
+    - `"score"` - `float`/`epoch` - the position of the lock request: time when the lock request was made (epoch) shifted by
+      `-priority * 2**32` seconds (the time itself for the default priority `0`);
     - `"rw_mode"` - `string` - the requested lock mode (`"write"`);
+    - `"priority"` - `integer` - the lock request priority (from `-100` to `100`, see [Lock Request Prioritization](#lock-request-prioritization));
   - `"read_lock_queue"`, `"read_queue"` - (only when read lock requests exist) the read lock queue key and read lock requests
     with the same structure (`"rw_mode"` - `"read"`), see [Read/Write Locks](#readwrite-locks);
 
@@ -1275,15 +1321,16 @@ 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" => 1711606640.540842, "rw_mode" => "write" },
-    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 1711606640.540906, "rw_mode" => "write" },
-    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 1711606640.540963, "rw_mode" => "write" },
+    # (a lock request of the high priority: ahead of the requests of the default priority)
+    { "acq_id" => "rql:acq:123/456/567/678/fa76df9cc2", "score" => -2583360655.459158, "rw_mode" => "write", "priority" => 1 },
+    { "acq_id" => "rql:acq:123/567/456/679/c7bfcaf4f9", "score" => 1711606640.540906, "rw_mode" => "write", "priority" => 0 },
+    { "acq_id" => "rql:acq:555/329/523/127/7329553b11", "score" => 1711606640.540963, "rw_mode" => "write", "priority" => 0 },
     # ...etc
   ],
   # (when read lock requests exist)
   "read_lock_queue" => "rql:lock_read_queue:your_lock_name",
   "read_queue" => [
-    { "acq_id" => "rql:acq:123/456/567/700/fa76df9cc2", "score" => 1711606640.541011, "rw_mode" => "read" },
+    { "acq_id" => "rql:acq:123/456/567/700/fa76df9cc2", "score" => 1711606640.541011, "rw_mode" => "read", "priority" => 0 },
     # ...etc
   ]
 }
@@ -1471,7 +1518,7 @@ rql.unlock_read('report', acquirer_id: reader['acq_id'])
     - pre-configured value in `config['logger']`;
   - `:instrumenter` - (optional) `[#notify]`
     - custom instrumenter object;
-    - pre-configured value in `config['isntrumenter']`;
+    - pre-configured value in `config['instrumenter']`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
   - `:log_sampling_enabled` - (optional) `[Boolean]`
@@ -1554,7 +1601,7 @@ rql.clear_locks
     - pre-configured value in `config['logger']`;
   - `:instrumenter` - (optional) `[#notify]`
     - custom instrumenter object;
-    - pre-configured value in `config['isntrumenter']`;
+    - pre-configured value in `config['instrumenter']`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
   - `:log_sampling_enabled` - (optional) `[Boolean]`
@@ -1662,7 +1709,7 @@ rql.clear_current_locks
     - pre-configured value in `config['logger']`;
   - `:instrumenter` - (optional) `[#notify]`
     - custom instrumenter object;
-    - pre-configured value in `config['isntrumenter']`;
+    - pre-configured value in `config['instrumenter']`;
   - `:instrument` - (optional) `[NilClass,Any]`
     - custom instrumentation data wich will be passed to the instrumenter's payload with `:instrument` key;
   - `:log_sampling_enabled` - (optional) `[Boolean]`
@@ -1972,8 +2019,8 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
 - returns `Set<Hash<Symbol,Any>>` (see [#queue_info](#queue_info) and examples below for details).
   - contained data: `{ queue: String, requests: Array<Hash<String,Any>> }`
   - `:queue` - `String` - lock key queue in Redis;
-  - `:requests` - `Array<Hash<String,Any>>` - lock requests in the que with their acquirer id, score and requested lock mode
-    (`"rw_mode"` - `"write"` for `rql:lock_queue:*`, `"read"` for read lock queues `rql:lock_read_queue:*`).
+  - `:requests` - `Array<Hash<String,Any>>` - lock requests in the que with their acquirer id, score, requested lock mode
+    (`"rw_mode"` - `"write"` for `rql:lock_queue:*`, `"read"` for read lock queues `rql:lock_read_queue:*`) and priority.
 
 ```ruby
 rql.queues_info # or rql.qeuues_info(scan_size: 123)
@@ -1981,13 +2028,13 @@ rql.queues_info # or rql.qeuues_info(scan_size: 123)
 => #<Set:
  {{:queue=>"rql:lock_queue:some-lock-123",
    :requests=>
-    [{"acq_id"=>"rql:acq:38529/4500/4520/4360/66093702f24a3129", "score"=>1711606640.540842, "rw_mode"=>"write"},
-     {"acq_id"=>"rql:acq:38529/4580/4600/4360/66093702f24a3129", "score"=>1711606640.540906, "rw_mode"=>"write"},
-     {"acq_id"=>"rql:acq:38529/4620/4640/4360/66093702f24a3129", "score"=>1711606640.5409632, "rw_mode"=>"write"}]},
+    [{"acq_id"=>"rql:acq:38529/4500/4520/4360/66093702f24a3129", "score"=>1711606640.540842, "rw_mode"=>"write", "priority"=>0},
+     {"acq_id"=>"rql:acq:38529/4580/4600/4360/66093702f24a3129", "score"=>1711606640.540906, "rw_mode"=>"write", "priority"=>0},
+     {"acq_id"=>"rql:acq:38529/4620/4640/4360/66093702f24a3129", "score"=>1711606640.5409632, "rw_mode"=>"write", "priority"=>0}]},
   {:queue=>"rql:lock_read_queue:some-lock-456",
    :requests=>
-    [{"acq_id"=>"rql:acq:38529/4380/4400/4360/66093702f24a3129", "score"=>1711606640.540722, "rw_mode"=>"read"},
-     {"acq_id"=>"rql:acq:38529/4420/4440/4360/66093702f24a3129", "score"=>1711606640.5407748, "rw_mode"=>"read"}]},
+    [{"acq_id"=>"rql:acq:38529/4380/4400/4360/66093702f24a3129", "score"=>1711606640.540722, "rw_mode"=>"read", "priority"=>0},
+     {"acq_id"=>"rql:acq:38529/4420/4440/4360/66093702f24a3129", "score"=>1711606640.5407748, "rw_mode"=>"read", "priority"=>0}]},
   ...}>
 ```
 ---
@@ -1999,8 +2046,10 @@ rql.queues_info # or rql.qeuues_info(scan_size: 123)
 In some cases your lock requests may become "dead". It means that your lock request lives in lock queue in Redis without
 any processing. It can happen when your processs that are enqueeud to the lock queue is failed unexpectedly (for some reason)
 before the lock acquire moment occurs and when no any other process does not need this lock anymore.
-For this case your lock reuquest will be cleared only when any process will try
-to acquire this lock again (cuz lock acquirement triggers the removement of expired requests).
+For this case your lock request will be cleared only when another lock request meets it: a lock request of the same
+[priority](#lock-request-prioritization) (lock acquirement drops the expired requests of its priority) or a `:queued` lock request
+it blocks (the head of the queue, an earlier request of the other read/write mode); the dead requests of other priorities stay
+in the queue.
 
 NOTE: with the enabled [Lock Index](#lock-index) the lock request queue lives as long as its latest lock request (the queue TTL
 is refreshed with the request `queue_ttl` on each lock request), so the queue of dead requests expires by itself (queues of older
@@ -2009,7 +2058,12 @@ RQL versions and queues created with the disabled lock index have no TTL: see [#
 In order to help with these dead requests you may periodically call `#clear_dead_requests`
 with corresponding `:dead_ttl` option, that is pre-configured by default via `config['dead_request_ttl']`.
 Lock queues are found via the redis `SCAN` (one pass) or via the [Lock Index](#lock-index) (one `ZSCAN` pass, the keyspace is
-never scanned: the enabled lock index).
+never scanned: the enabled lock index). Each batch of lock queues takes two round trips: the lock requests are read, then the dead
+requests of each [priority](#lock-request-prioritization) found in the queues are dropped (no second round trip without dead requests).
+With `by_priority: true` the lock requests are not read: only the first lock request of each priority is read (the dead requests
+of a priority are found by its first lock request): a batch takes one round trip per priority of its lock queue with the most
+priorities + 1 (the dead requests of a priority are dropped in the round trip that reads the next priority), so the transfer does not
+depend on the length of the lock queues: use it for long lock queues with few priorities.
 
 `:dead_ttl` option is required because of it is no any **fast** and **resource-free** way to understand which request
 is dead now and is it really dead cuz each request queue can host their requests with
@@ -2022,14 +2076,20 @@ Accepts:
 - `:scan_size` - (optional) `[Integer]`
   - the batch of scanned keys for Redis'es SCAN command;
   - (the enabled lock index) the `ZSCAN` count of the [Lock Index](#lock-index) pass and the number of locks (both lock queues
-    of each lock) processed in one round trip;
+    of each lock) processed in one batch;
   - has a preconfigured valie in `config['lock_release_batch_size']`;
+- `:by_priority` - (optional) `[Boolean]`
+  - read only the first lock request of each [priority](#lock-request-prioritization) in the lock queues instead of all lock
+    requests: a batch of lock queues takes one round trip per priority of its lock queue with the most priorities + 1 (instead
+    of two round trips), the transfer does not depend on the length of the lock queues (for long lock queues with few
+    priorities);
+  - `false` by default (all lock requests are read);
 - `:logger` - (optional) `[::Logger,#debug]`
   - custom logger object;
   - pre-configured in `config['logger']`;
 - `:instrumenter` - (optional) `[#notify]`
   - custom instrumenter object;
-  - pre-configured in `config['isntrumenter']`;
+  - pre-configured in `config['instrumenter']`;
 - `:instrument` - (optional) `[NilClass,Any]`
   - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
   - `nil` by default (no additional data);
@@ -2079,6 +2139,9 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
     }>
   }
 }
+
+# long lock queues with few priorities: only the first lock request of each priority is read
+rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000, by_priority: true)
 ```
 
 ---
@@ -2598,13 +2661,115 @@ rql.possible_host_ids
   - 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;
+      the queue is ordered by the [lock request priorities](#lock-request-prioritization) (FIFO inside the same priority);
     - `: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;
+      (the priorities of other lock requests are ignored too; the lock request itself is queued at the position of its
+      [priority](#lock-request-prioritization) like a `:queued` one: `:queued` lock requests wait for it);
   - 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;
 
 ---
 
+## Lock Request Prioritization
+
+<sup>\[[back to top](#table-of-contents)\]</sup>
+
+- `priority:` attribute of `#lock`, `#lock!`, `#lock_series` and `#lock_series!` (`config['default_lock_priority']` by default):
+  an Integer from `-100` (the lowest priority) to `100` (the highest priority), `0` - (**default**) normal priority,
+  or a priority name (Symbol) of `config['lock_priorities']`;
+- priority names (`config['lock_priorities']`, a priority name => its Integer priority):
+  - default names: `:lowest` (`-100`), `:low` (`-50`), `:normal` (`0`), `:high` (`50`), `:highest` (`100`);
+  - name the priorities of your application (keep the default names with `merge`; the default value is frozen: assign
+    a new hash);
+  - a name is resolved to its Integer priority on each lock acquirement: the lock request queues, `#queue_info`/`#queues_info`,
+    logs and instrumentation have the Integer priority; an unknown name fails with `RedisQueuedLocks::ArgumentError`;
+  - `config['default_lock_priority']` can be a priority name too: an unknown one fails the configuration with
+    `RedisQueuedLocks::ConfigValidationError` (checked after the configuration block, the keys can be assigned in any order,
+    and on a direct `config[...] =` assignment);
+- `:queued` access strategy (default): the lock request is placed in the lock request queue after all requests of the same
+  or higher priority and before all requests of the lower priority: strict priority between priorities, FIFO inside the same
+  priority (read and write lock requests too, see [Read/Write Locks](#readwrite-locks));
+
+```ruby
+# a balance operation goes ahead of the email notifications that are already waiting for the lock
+rql.lock("user_#{user.id}", priority: 50) { process_balance }
+
+# a payment goes ahead of the balance operations
+rql.lock("user_#{user.id}", priority: 90) { process_payment }
+
+# email notifications wait for all lock requests of higher priorities
+rql.lock("user_#{user.id}", priority: -10) { send_email }
+
+# normal priority by default
+rql.lock("user_#{user.id}") { update_profile } # priority: 0
+
+# the default priority of the client (for example, in background workers)
+rql.configure { |config| config['default_lock_priority'] = -10 }
+
+# priority names: the default ones (:lowest, :low, :normal, :high, :highest) and the names of your application
+rql.configure do |config|
+  config['lock_priorities'] = config['lock_priorities'].merge(payment: 90, balance: 50, email: -10)
+end
+rql.lock("user_#{user.id}", priority: :payment) { process_payment } # priority: 90
+rql.lock("user_#{user.id}", priority: :email) { send_email } # priority: -10
+rql.lock("user_#{user.id}", priority: :high) { update_profile } # priority: 50
+```
+
+- how it works:
+  - the position of the lock request in the queue (the score) is the request time shifted by the priority band:
+    `request time - priority * 2**32 seconds` (each priority has its own range of positions; the default priority `0` keeps
+    the request time: the positions of RQL versions without priorities);
+  - every lock request drops dead requests (older than `queue_ttl`) of its own priority in both lock queues (in the same round
+    trip as before priorities); dead requests of other priorities that block it (the head of the queue and the earlier request
+    of the other read/write mode: the priority and the request time are decoded from the position) are dropped with all dead
+    requests of their priorities in one more round trip of the same attempt, so a dead request of any priority never blocks the
+    queue and the cost of an attempt does not depend on the number of priorities in use;
+  - dead requests of lower priorities never block: they are dropped by the lock requests of their priority (or lower ones)
+    and by `#clear_dead_requests` (it drops the dead requests of every priority found in the queues);
+  - lock requests at infinite positions (`-inf`/`+inf`: manual writes of the lock queues, RQL never writes them) have the
+    bound priorities (`100`/`-100`) in `#queue_info`/`#queues_info` and logs; a request at `-inf` is a dead one (like before
+    priorities): it is dropped when it blocks a lock request and by `#clear_dead_requests`; a request at `+inf` is behind all
+    requests and is never dropped as a dead one;
+  - `#queue_info`/`#queues_info` return the priority of each lock request (`"priority"`); the lock acquirement logs and
+    instrumentation events (classic, reentrant and lock series ones) have the `priority` of the lock request, the `log_lock_try`
+    logs also have the priorities of the requests ahead (`first_priority_in_queue`, `ahead_priority`, `dead_priority`;
+    `first_priority_in_queue => nil` when the lock queue has no requests);
+- limitations and recommendations:
+  - the priority orders the waiting lock requests only: the obtained lock is never taken away (no preemption);
+  - strict priority: a continuous flow of requests of a higher priority can starve the requests of lower priorities (they
+    reach their `timeout`/`retry_count` limits): give them longer limits;
+  - the released lock is passed by polling: the next lock request notices the released lock on its next attempt
+    (`retry_delay`): use a shorter `retry_delay` for the important logic;
+  - the default `retry_count` (`3`) gives a short waiting time: the priority matters for the requests that wait longer
+    (`retry_count: nil` with `timeout`);
+  - requests of the same priority made within ~61 µs of each other are ordered by their acquirer ids (the precision of
+    the shifted positions);
+  - each lock request drops dead requests with its own `queue_ttl` (the requests of its priority and the requests that block it):
+    a request that waits longer than the shorter `queue_ttl` of such requests is dropped by their attempts and comes back at its
+    old position on its own attempts (its own `queue_ttl` is not reached yet), so the requests behind it with a shorter
+    `queue_ttl` don't wait for it: it loses its place (and the advantage of its priority) to them, the lock goes to the request
+    whose attempt finds the lock free first; use the same `queue_ttl` for the lock requests of a lock (a longer `queue_ttl` does
+    not keep a request in the queue);
+  - `:random` access strategy: the lock request does not wait for its turn (the order of the queues and the priorities of other
+    requests are ignored), but it is queued at the position of its priority: `:queued` lock requests wait for it (a `:random`
+    request of a high priority holds back the waiting `:queued` requests of lower priorities until it obtains the lock or
+    leaves the queue);
+  - dead lock requests are dropped by the lock requests that meet them (the requests of their priority and the requests they
+    block): the dead requests of the priorities that no lock request uses any more (and the dead requests met only by `:random`
+    lock requests) stay in the queues; they never block (an accepted trade-off of the head-driven cleanup: the cost of an
+    attempt does not depend on the number of priorities); without the [Lock Index](#lock-index) (its queues expire) and the
+    [swarm](#swarm-mode-and-zombie-locks) (it drops the requests of dead processes) call `#clear_dead_requests` periodically
+    (e.g. from a scheduled job) to drop them (`by_priority: true` for long lock queues: only the first lock request of each
+    priority is read);
+  - all processes that share locks should use RQL versions with priorities before positive priorities are used (`:high`,
+    `:highest`, any priority above `0`): older versions drop such lock requests as dead ones (the order is broken; the mutual
+    exclusion is not affected: lock queues never take part in it); the default priority (`0`) and negative priorities
+    (`:low`, `:lowest`) work with older versions too: older versions keep such requests behind their own ones and never drop
+    them as dead ones (the dead ones are dropped by the upgraded processes);
+
+---
+
 ## Read/Write Locks
 
 <sup>\[[back to top](#table-of-contents)\]</sup>
@@ -2627,8 +2792,11 @@ rql.lock('report') { rebuild_report } # read_write_mode: :write by default
 - lock request ordering (`access_strategy`):
   - `:queued` (default) - FIFO between modes: read lock request waits for every earlier write lock request,
     write lock request waits for every earlier read and write lock request (so writers are not starved by a
-    continuous flow of readers and consecutive readers obtain the lock together);
-  - `:random` - lock queues are ignored: any free lock is obtained (a continuous flow of readers can starve writers);
+    continuous flow of readers and consecutive readers obtain the lock together); with
+    [lock request priorities](#lock-request-prioritization) "earlier" means "ahead in the queue": a request of a higher
+    priority is ahead of all requests of lower priorities in both modes (FIFO inside the same priority);
+  - `:random` - the order of the lock queues is ignored: any free lock is obtained (a continuous flow of readers can starve
+    writers); the lock request itself is queued like any lock request (`:queued` lock requests wait for it);
 - read locks:
   - each read lock has its own `ttl` and is released (after the block execution) or expired independently of other read locks;
   - `ttl` should be a positive `Integer`;
@@ -2727,13 +2895,13 @@ rql.lock('report') { rebuild_report } # read_write_mode: :write by default
 - default logs (raised from `#lock`/`#lock!`):
 
 ```ruby
-"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.dead_score_reached__reset_acquirer_position]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-"[redis_queued_locks.lock_obtaining_failed]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
-"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+"[redis_queued_locks.start_lock_obtaining]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+"[redis_queued_locks.start_try_to_lock_cycle]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+"[redis_queued_locks.dead_score_reached__reset_acquirer_position]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+"[redis_queued_locks.lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+"[redis_queued_locks.lock_obtaining_failed]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time", "result");
+"[redis_queued_locks.extendable_reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+"[redis_queued_locks.reentrant_lock_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
 "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 "[redis_queued_locks.expire_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 "[redis_queued_locks.decrease_lock]" # (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
@@ -2750,24 +2918,25 @@ rql.lock('report') { rebuild_report } # read_write_mode: :write by default
 "[redis_queued_locks.try_lock.reentrant_lock__work_through]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
 "[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
 "[redis_queued_locks.try_lock.single_process_lock_conflict__lock_upgrade]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
-"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+"[redis_queued_locks.try_lock.acq_added_to_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
 "[redis_queued_locks.try_lock.remove_expired_acqs]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.dead_request_removed]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "dead_acq_id", "dead_priority");
+"[redis_queued_locks.try_lock.get_first_from_queue]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
 "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "<current_lock_data>");
-"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-"[redis_queued_locks.try_lock.exit__write_request_ahead]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-"[redis_queued_locks.try_lock.exit__read_request_ahead]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-"[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+"[redis_queued_locks.try_lock.exit__no_first]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "<current_lock_data>");
+"[redis_queued_locks.try_lock.exit__lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "locked_by_acq_id", "<current_lock_data>");
+"[redis_queued_locks.try_lock.exit__write_request_ahead]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+"[redis_queued_locks.try_lock.exit__read_request_ahead]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+"[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
 "[redis_queued_locks.try_lock.obtain__free_to_acquire]" # (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 ```
 
 - lock series logs (raised from `#lock_series`/`#lock_series!`, PoC; `rw_mode` is the mode of the series):
 
 ```ruby
-"[redis_queued_locks.start_lock_series_obtaining]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-"[redis_queued_locks.lock_series_obtained]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-"[redis_queued_locks.expire_lock_series]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+"[redis_queued_locks.start_lock_series_obtaining]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+"[redis_queued_locks.lock_series_obtained]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+"[redis_queued_locks.expire_lock_series]" # (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
 ```
 
 - operation logs (one log line per operation that changes Redis keys, with the time of the whole operation; the same data as
@@ -2808,19 +2977,19 @@ rql.lock('report') { rebuild_report } # read_write_mode: :write by default
 # - 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", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-#   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time", "result");
-#   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-#   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
+#   - "[redis_queued_locks.start_lock_obtaining]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+#   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+#   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+#   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+#   - "[redis_queued_locks.lock_obtaining_failed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time", "result");
+#   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+#   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
 #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "acq_time");
-#   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+#   - "[redis_queued_locks.start_lock_series_obtaining]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
+#   - "[redis_queued_locks.lock_series_obtained]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority", "acq_time");
+#   - "[redis_queued_locks.expire_lock_series]" (logs "lock_keys", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
 #   - "[redis_queued_locks.explicit_lock_release]" (logs "lock_key", "lock_key_queue", "rel_time", "at");
 #   - "[redis_queued_locks.explicit_read_lock_release]" (logs "lock_key", "acq_id", "lock_res", "rel_time", "at");
 #   - "[redis_queued_locks.explicit_all_locks_release]" (logs "at", "rel_time", "rel_key_cnt");
@@ -2845,15 +3014,16 @@ config['logger'] = RedisQueuedLocks::Logging::VoidLogger
 #   - "[redis_queued_locks.try_lock.reentrant_lock__work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
 #   - "[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
 #   - "[redis_queued_locks.try_lock.single_process_lock_conflict__lock_upgrade]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_spc_ts");
-#   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+#   - "[redis_queued_locks.try_lock.acq_added_to_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "priority");
 #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+#   - "[redis_queued_locks.try_lock.dead_request_removed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "dead_acq_id", "dead_priority");
+#   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
 #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
-#   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "<current_lock_data>");
-#   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "locked_by_acq_id", "<current_lock_data>");
-#   - "[redis_queued_locks.try_lock.exit__write_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-#   - "[redis_queued_locks.try_lock.exit__read_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id");
-#   - "[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue");
+#   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "<current_lock_data>");
+#   - "[redis_queued_locks.try_lock.exit__lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue", "locked_by_acq_id", "<current_lock_data>");
+#   - "[redis_queued_locks.try_lock.exit__write_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+#   - "[redis_queued_locks.try_lock.exit__read_request_ahead]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "ahead_acq_id", "ahead_priority");
+#   - "[redis_queued_locks.try_lock.exit__read_lock_still_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "first_acq_id_in_queue", "first_priority_in_queue");
 #   - "[redis_queued_locks.try_lock.obtain__free_to_acquire]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
 #   - "rw_mode" is the requested lock mode ('write'/'read');
 config['log_lock_try'] = false
@@ -2991,6 +3161,7 @@ Detalized event semantics and payload structure:
   - `:hst_id` - `string` - lock's host identifier;
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:priority` - `integer` - lock request priority: from `-100` to `100` (a priority name is reported as its integer priority, see [Lock Request Prioritization](#lock-request-prioritization));
   - `: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;
@@ -3003,6 +3174,7 @@ Detalized event semantics and payload structure:
 - payload:
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:priority` - `integer` - lock request priority: from `-100` to `100` (a priority name is reported as its integer priority, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:ttl` - `integer`/`milliseconds` - requested lock ttl;
   - `:acq_id` - `string` - lock acquirer identifier;
   - `:hst_id` - `string` - lock's host identifier;
@@ -3020,6 +3192,7 @@ Detalized event semantics and payload structure:
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
     a read lock request under the write lock of the same acquirer works through the write lock (`:rw_mode` is `:read`);
+  - `:priority` - `integer` - requested lock request priority: from `-100` to `100` (a priority name is reported as its integer priority; a reentrant lock request is not queued, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
   - `:acq_id` - `string` - lock acquirer identifier;
   - `:hst_id` - `string` - lock's host identifier;
@@ -3035,6 +3208,7 @@ Detalized event semantics and payload structure:
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
     a read lock request under the write lock of the same acquirer works through the write lock (`:rw_mode` is `:read`);
+  - `:priority` - `integer` - requested lock request priority: from `-100` to `100` (a priority name is reported as its integer priority; a reentrant lock request is not queued, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:ttl` - `integer`/`milliseconds` - last lock ttl by reentrant locking;
   - `:acq_id` - `string` - lock acquirer identifier;
   - `:hst_id` - `string` - lock's host identifier;
@@ -3053,6 +3227,7 @@ Detalized event semantics and payload structure:
   - `:hst_id` - `string` - lock's host identifier;
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:priority` - `integer` - lock request priority: from `-100` to `100` (a priority name is reported as its integer priority, see [Lock Request Prioritization](#lock-request-prioritization));
   - `: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;
@@ -3071,6 +3246,7 @@ Detalized event semantics and payload structure:
   - `:lock_key` - `string` - lock name;
   - `:rw_mode` - `symbol` - requested lock mode: `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
     a read lock request under the write lock of the same acquirer works through the write lock (`:rw_mode` is `:read`);
+  - `:priority` - `integer` - requested lock request priority: from `-100` to `100` (a priority name is reported as its integer priority; a reentrant lock request is not queued, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
   - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
 
@@ -3081,6 +3257,7 @@ Detalized event semantics and payload structure:
 - payload:
   - `:lock_keys` - `array<string>` - lock names of the series;
   - `:rw_mode` - `symbol` - the mode of the series (`read_write_mode`): `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:priority` - `integer` - the lock request priority of the series (`priority`): from `-100` to `100` (a priority name is reported as its integer priority, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:ttl` - `integer`/`milliseconds` - the `ttl` option of the series (each lock of the series gets its own ttl,
     see [lock_series](#lock_series---poc-acquire-a-series-of-locks));
   - `:acq_id` - `string` - lock acquirer identifier;
@@ -3096,6 +3273,7 @@ Detalized event semantics and payload structure:
 - payload:
   - `:lock_keys` - `array<string>` - lock names of the series;
   - `:rw_mode` - `symbol` - the mode of the series (`read_write_mode`): `:write` or `:read` (see [Read/Write Locks](#readwrite-locks));
+  - `:priority` - `integer` - the lock request priority of the series (`priority`): from `-100` to `100` (a priority name is reported as its integer priority, see [Lock Request Prioritization](#lock-request-prioritization));
   - `:hold_time` - `float`/`milliseconds` - the series hold time;
   - `:ttl` - `integer`/`milliseconds` - the `ttl` option of the series;
   - `:acq_id` - `string` - lock acquirer identifier;
@@ -3203,7 +3381,6 @@ Detalized event semantics and payload structure:
   - isolated timeouts which are independent of internal Ruby's timeout implementation (where all timeouts are hostend inside
     the global "timeout request" queue and managed by a single global "timeout wathcer" thread). it should prevent any logic and timeout intersections,
     some GVL-related things and problem situations when the global watcher thread is "dead";
-  - lock request prioritization;
   - **strict redlock algorithm support** (support for many `RedisClient` instances that are fully independent (distributed redis instances));
   - #lock_series` - acquire a series of locks:
     - (NOTE: "Proof of Concept" implementation is ready to use);
@@ -3221,6 +3398,7 @@ Detalized event semantics and payload structure:
         Mutex (instantiated inside the main Ractor) from the our non-main Ractor (swar-mode works under the non-main ractor) and this process fails\
         on non-sharable memory error);
 - **Minor**:
+  - `*_status` aliases for `*_info` methods;
   - an ability to return all insturmentation metrics from the `lock` invocation (and after block `yield`ing);
   - think about a PG-like `stats`-data/table, that should be helpful for lock history acquirement analyzation :thinking: (suitable for cases when we want
     to check if the lock was acquired by some different parallel process durign the some period of time in the past or not);
@@ -3269,6 +3447,17 @@ Detalized event semantics and payload structure:
 bundle exec rake rspec
 ```
 
+- Tests in parallel processes (`RSpec`, ~6x faster): each process (worker) works with its own pair of Redis databases
+  (the specs use db 0 and db 1), so `WORKERS=n` flushes db `0..2n-1` of the local Redis (the default number of workers:
+  the Redis `databases` / 2, up to the CPU count); the examples are distributed by their durations of the previous runs
+  (`tmp/rspec_parallel/durations.json`), the output of each worker is in `tmp/rspec_parallel/worker-<n>.log`, the coverage
+  report of the whole run is collated into `coverage/` after all workers:
+```shell
+bundle exec rake rspec:parallel
+WORKERS=4 bundle exec rake rspec:parallel
+bundle exec rake "rspec:parallel[spec/redis_queued_locks_spec.rb]" # spec files/filters
+```
+
 - Linting (`Rubocop`+`RBS`):
 ```shell
 bundle exec rake rubocop
@@ -3281,7 +3470,8 @@ bundle exec rake steep:check
 
 - `Runtime` TypeChecking (`RBS`):
 ```shell
-bundle exec rbs collection install && RBS_TEST_RAISE=true RUBYOPT='-rrbs/test/setup' RBS_TEST_OPT='-I sig' RBS_TEST_LOGLEVEL=error RBS_TEST_TARGET='RedisQueuedLocks::*' bundle exec rspec --failure-exit-code=0
+bundle exec rbs collection install && RBS_TEST_RAISE=true RUBYOPT='-rbundler/setup -rrbs/test/setup' RBS_TEST_OPT='-I sig' RBS_TEST_LOGLEVEL=error RBS_TEST_TARGET='RedisQueuedLocks::*' RBS_TEST_SKIP='::RedisQueuedLocks::Swarm::FlushZombies,::RedisQueuedLocks::Swarm::SwarmElement::Isolated,::RedisQueuedLocks::Swarm::RedisClientBuilder' bundle exec rspec
+# or in parallel processes: the same environment with `bundle exec rake rspec:parallel` instead of `bundle exec rspec`
 ```
 
 ---