redis_queued_locks 1.20.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).
 
@@ -47,6 +47,7 @@ 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)
+  - [reindex_locks](#reindex_locks)
   - [current_acquirer_id](#current_acquirer_id)
   - [current_host_id](#current_host_id)
   - [possible_host_ids](#possible_host_ids)
@@ -70,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)
@@ -78,6 +80,7 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
   - [Instrumentation Configuration](#instrumentation-configuration)
   - [Instrumentation Events](#instrumentation-events)
     - ["redis_queued_locks.lock_obtained"](#redis_queued_lockslock_obtained)
+    - ["redis_queued_locks.lock_obtaining_failed"](#redis_queued_lockslock_obtaining_failed)
     - ["redis_queued_locks.extendable_reentrant_lock_obtained"](#redis_queued_locksextendable_reentrant_lock_obtained)
     - ["redis_queued_locks.reentrant_lock_obtained"](#redis_queued_locksreentrant_lock_obtained)
     - ["redis_queued_locks.lock_hold_and_release"](#redis_queued_lockslock_hold_and_release)
@@ -88,6 +91,9 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
     - ["redis_queued_locks.explicit_read_lock_release"](#redis_queued_locksexplicit_read_lock_release)
     - ["redis_queued_locks.explicit_all_locks_release"](#redis_queued_locksexplicit_all_locks_release)
     - ["redis_queued_locks.release_locks_of"](#redis_queued_locksrelease_locks_of)
+    - ["redis_queued_locks.extend_lock_ttl"](#redis_queued_locksextend_lock_ttl)
+    - ["redis_queued_locks.clear_dead_requests"](#redis_queued_locksclear_dead_requests)
+    - ["redis_queued_locks.reindex_locks"](#redis_queued_locksreindex_locks)
 - [Roadmap](#roadmap)
 - [Build and Develop](#build-and-develop)
 - [Contributing](#contributing)
@@ -120,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.
 
@@ -191,16 +197,20 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (seconds) (supports nil)
   # - nil means "no timeout" and you are only limited by "retry_count" config;
+  # - 0 is the same as nil (no timeout);
   config['try_to_lock_timeout'] = 10
 
   # (milliseconds) (default: 5_000)
   # - lock's time to live
+  # - should be a positive Integer
   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
   config['default_queue_ttl'] = 15
 
   # (boolean) (default: false)
@@ -241,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);
@@ -260,6 +294,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - (the enabled lock index) how many locks (lock names of the lock index) will be processed at a time
   #   (the ZSCAN count of the lock index pass);
   # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
+  # - should be a positive Integer
   config['lock_release_batch_size'] = 100
 
   # (default: 300)
@@ -268,12 +303,14 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   (the ZSCAN count of the lock index pass, DEL for batch deletion);
   # - affects the ruby's memory (cuz this batch will be stored in Set object in first, and then will be splatted to the DEL redis method invocation) (configure thoughtfully);
   # - affects the performance of your Redis (configure thoughtfully);
+  # - should be a positive Integer
   config['clear_locks_of__lock_scan_size'] = 300
 
   # (default: 300)
   # - how many lock queues will be processed in one round trip in #clear_locks_of and in #clear_current_locks methods
   #   (lock queues are found by the same SCAN pass as locks or derived from the lock names of the same lock index pass);
   # - affects the performance of your Redis (configure thoughtfully);
+  # - should be a positive Integer
   config['clear_locks_of__queue_scan_size'] = 300
 
   # (default: 500)
@@ -282,6 +319,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - (the enabled lock index) how many locks (lock names of the lock index) should be processed at a time
   #   (the ZSCAN count of the lock index pass);
   # - affects the performance of your Redis and Ruby Application (configure thoughtfully);
+  # - should be a positive Integer
   config['key_extraction_batch_size'] = 500
 
   # (default: 1 day)
@@ -327,15 +365,28 @@ 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");
-  #   - "[redis_queued_locks.start_try_to_lock_cycle]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.dead_score_reached__reset_acquirer_position]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
-  #   - "[redis_queued_locks.extendable_reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
-  #   - "[redis_queued_locks.reentrant_lock_obtained]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acq_time", "acs_strat");
-  #   - "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.expire_lock]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.decrease_lock]" (logs "lock_key", "decreased_ttl", "queue_ttl", "acq_id", "hst_id", "acs_strat");
+  #   - "[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", "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");
+  #   - "[redis_queued_locks.release_locks_of]" (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+  #   - "[redis_queued_locks.extend_lock_ttl]" (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+  #   - "[redis_queued_locks.clear_dead_requests]" (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+  #   - "[redis_queued_locks.reindex_locks]" (logs "idx_key_cnt", "idx_time", "at");
+  #   - "rw_mode" is the requested lock mode ('write'/'read'), the held lock mode for "expire_lock" and "decrease_lock",
+  #     the mode of the series for lock series logs;
   # - by default uses VoidLogger that does nothing;
   config['logger'] = RedisQueuedLocks::Logging::VoidLogger
 
@@ -343,19 +394,26 @@ client = 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 debug logs in addition to the existing:
-  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "spc_status");
-  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_id", "acs_strat", "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")";
-  #   - "[redis_queued_locks.try_lock.remove_expired_acqs]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.try_lock.get_first_from_queue]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "first_acq_id_in_queue");
-  #   - "[redis_queued_locks.try_lock.exit__queue_ttl_reached]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat");
-  #   - "[redis_queued_locks.try_lock.exit__no_first]" (logs "lock_key", "queue_ttl", "acq_id", "hst_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", "hst_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", "hst_id", "acs_strat");
+  #   - "[redis_queued_locks.try_lock.start]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.rconn_fetched]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_detected]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode");
+  #   - "[redis_queued_locks.try_lock.same_process_conflict_analyzed]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status");
+  #   - "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through]" (logs "lock_key", "queue_ttl", "acq_id", "hst_id", "acs_strat", "rw_mode", "spc_status", "last_ext_ttl", "last_ext_ts");
+  #   - "[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", "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.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", "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
 
   # (default: false)
@@ -366,7 +424,7 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
 
   # (default: 15)
   # - the percent of cases that should be logged;
-  # - take an effect when <config['log_sampling_enalbed']> is true;
+  # - take an effect when <config['log_sampling_enabled']> is true;
   # - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
   config['log_sampling_percent'] = 15
 
@@ -383,11 +441,11 @@ client = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - enables <instrumentaion sampling>: only the configured percent of RQL cases will be instrumented;
   # - disabled by default;
   # - works in tandem with <config['instr_sampling_percent'] and <config['instr_sampler']>;
-  config['nstr_sampling_enabled'] = false
+  config['instr_sampling_enabled'] = false
 
   # (default: 15)
   # - the percent of cases that should be instrumented;
-  # - take an effect when <config['instr_sampling_enalbed']> is true;
+  # - take an effect when <config['instr_sampling_enabled']> is true;
   # - works in tandem with <config['instr_sampling_enabled']> and <config['instr_sampler']> configs;
   config['instr_sampling_percent'] = 15
 
@@ -409,15 +467,18 @@ end
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 - [lock](#lock---obtain-a-lock)
-- [lock!](#lock---exeptional-lock-obtaining)
+- [lock!](#lock---exceptional-lock-obtaining)
 - [lock_series](#lock_series---poc-acquire-a-series-of-locks) (PoC)
 - [lock_series!](#lock_series---poc-exceptional-lock_series) (PoC)
 - [lock_info](#lock_info)
 - [queue_info](#queue_info)
 - [locked?](#locked)
 - [queued?](#queued)
-- [unlock](#unlock---release-a-lock)
-- [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+- [unlock](#unlock---release-a-lock) (aka `release_lock`)
+- [unlock_read](#unlock_read---release-the-read-lock-of-the-current-acquirer) (aka `release_read_lock`)
+- [clear_locks](#clear_locks---release-all-locks-and-lock-queues) (aka `release_locks`)
+- [clear_locks_of](#clear_locks_of) (aka `release_locks_of`)
+- [clear_current_locks](#clear_current_locks) (aka `release_current_locks`)
 - [extend_lock_ttl](#extend_lock_ttl)
 - [locks](#locks---get-list-of-obtained-locks)
 - [queues](#queues---get-list-of-lock-request-queues)
@@ -430,6 +491,10 @@ end
 - [current_host_id](#current_host_id)
 - [possible_host_ids](#possible_host_ids)
 
+The numeric options of the methods (ttls, timeouts, retries, scan and batch sizes, zombie ttl) are validated with the same
+types and ranges as their `config` keys: `Integer` values only (`timeout: 0.5` is rejected), `RedisQueuedLocks::ArgumentError`
+(`RedisQueuedLocks::SwarmArgumentError` for the swarm methods) otherwise.
+
 ---
 
 #### #lock - obtain a lock
@@ -465,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'],
@@ -488,6 +554,7 @@ def lock(
   - Lock name to be obtained.
 - `ttl` - (optional) - [Integer]
   - Lock's time to live (in milliseconds);
+  - should be a positive `Integer` (write and read locks);
   - pre-configured in `config['default_lock_ttl']`;
 - `queue_ttl` - (optional) `[Integer]`
   - Lifetime of the acuier's lock request. In seconds.
@@ -502,9 +569,14 @@ def lock(
   - pre-configured in `config['lock_index_grace_period']`;
 - `timeout` - (optional) `[Integer,NilClass]`
   - Time period a client should try to acquire the lock (in seconds). Nil means "without timeout".
+  - `0` is the same as `nil` (without timeout);
   - pre-configured in `config['try_to_lock_timeout']`;
+  - the timeout can not be swallowed by `rescue` of your logger/instrumenter (see `timed` below);
 - `timed` - (optiona) `[Boolean]`
   - Limit the invocation time period of the passed block of code by the lock's TTL.
+  - the block is interrupted by an internal `RedisQueuedLocks::Exception` (an `::Exception`, like `Timeout::ExitException` of Ruby's `Timeout`): `rescue => e`,
+    `rescue StandardError`, `rescue Timeout::Error` and `rescue nil` inside the block can not swallow it (only `rescue Exception`),
+    `ensure` of the block still runs;
   - pre-configured in `config['is_timed_by_default']`;
   - `false` by default;
 - `retry_count` - (optional) `[Integer,NilClass]`
@@ -519,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");
@@ -541,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;
@@ -603,7 +688,7 @@ def lock(
   - pre-configured in `config['log_sampling_enabled']`;
 - `log_sampling_percent` - (optional) `[Integer]`
   - the percent of cases that should be logged;
-  - take an effect when `log_sampling_enalbed` is true;
+  - take an effect when `log_sampling_enabled` is true;
   - works in tandem with `log_sampling_enabled` and `log_sampler` options;
   - pre-configured in `config['log_sampling_percent']`;
 - `log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
@@ -625,7 +710,7 @@ def lock(
   - pre-configured in `config['instr_sampling_enabled']`;
 - `instr_sampling_percent` - (optional) `[Integer]`
   - the percent of cases that should be instrumented;
-  - take an effect when `instr_sampling_enalbed` is true;
+  - take an effect when `instr_sampling_enabled` is true;
   - works in tandem with `instr_sampling_enabled` and `instr_sampler` options;
   - pre-configured in `config['instr_sampling_percent']`;
 - `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
@@ -663,6 +748,7 @@ Return value:
     result: {
       lock_key: "rql:lock:my_lock",
       acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
+      hst_id: "rql:hst:26672/2280/2320/70ea5dbf10ea1056",
       ts: 1711909612.653696,
       ttl: 10000,
       process: :lock_obtaining
@@ -676,7 +762,8 @@ Return value:
     - `:lock_obtaining` - classic lock obtaining proces. Default behavior (`conflict_strategy: :wait_for_lock`);
     - `:extendable_conflict_work_through` - reentrant lock acquiring process with lock's TTL extension. Suitable for `conflict_strategy: :extendable_work_through`;
     - `:conflict_work_through` - reentrant lock acquiring process without lock's TTL extension. Suitable for `conflict_strategy: :work_through`;
-    - `:dead_locking` - current process tries to acquire a lock that is already acquired by them. Suitalbe for `conflict_startegy: :dead_locking`;
+    - (`conflict_strategy: :dead_locking` does not obtain the lock already obtained by the current acquirer:
+      it fails with `{ ok: false, result: :conflict_dead_lock }`);
     - For more details see [Deadlocks and Reentrant locks](#deadlocks-and-reentrant-locks) readme section;
   - For successful lock obtaining:
     ```ruby
@@ -688,7 +775,7 @@ Return value:
         hst_id: String, # host identifier ("process_id/thread_id/ractor_id/identity")
         ts: Float, # time (epoch) when lock was obtained (float, Time#to_f)
         ttl: Integer, # lock's time to live in milliseconds (integer)
-        process: Symbol # which logical process has acquired the lock (:lock_obtaining, :extendable_conflict_work_through, :conflict_work_through, :conflict_dead_lock)
+        process: Symbol # which logical process has acquired the lock (:lock_obtaining, :extendable_conflict_work_through, :conflict_work_through)
       }
     }
     ```
@@ -700,21 +787,21 @@ Return value:
       result: {
         lock_key: "rql:lock:my_lock",
         acq_id: "rql:acq:26672/2280/2300/2320/70ea5dbf10ea1056",
-        acq_id: "rql:acq:26672/2280/2320/70ea5dbf10ea1056",
+        hst_id: "rql:hst:26672/2280/2320/70ea5dbf10ea1056",
         ts: 1711909612.653696,
         ttl: 10000,
-        process: :lock_obtaining # for custom conflict strategies may be: :conflict_dead_lock, :conflict_work_through, :extendable_conflict_work_through
+        process: :lock_obtaining # for reentrant locks (conflict strategies): :conflict_work_through, :extendable_conflict_work_through
       }
     }
     ```
   - For failed lock obtaining:
     ```ruby
-    { ok: false, result: :timeout_reached }
-    { ok: false, result: :retry_count_reached }
+    { ok: false, result: :timeout_reached } # see <timeout> option
+    { ok: false, result: :retry_limit_reached } # see <retry_count> option
     { ok: false, result: :conflict_dead_lock } # see <conflict_strategy> option for details (:dead_locking strategy)
+    { ok: false, result: :conflict_lock_upgrade } # read-to-write lock upgrade (see <read_write_mode> and <conflict_strategy> options)
     { ok: false, result: :fail_fast_no_try } # see <fail_fast> option
     { ok: false, result: :fail_fast_after_try } # see <fail_fast> option
-    { ok: false, result: :unknown }
     ```
 
 Examples:
@@ -775,8 +862,9 @@ rql.lock_info("my_lock")
 # =>
 {
   "lock_key" => "rql:lock:my_lock",
+  "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789,
   "ini_ttl" => 123456,
   "rem_ttl" => 123440,
@@ -787,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)
@@ -899,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'],
@@ -947,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`);
 
@@ -1027,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
 ```
 
 ----
@@ -1060,9 +1150,9 @@ client.lock_series!("x", "y", "z") { ...some_code... }
   - `"acq_id"` - `string` - acquirer identifier (process_id/thread_id/fiber_id/ractor_id/identity);
   - `"hst_id"` - `string` - host identifier (process_id/thread_id/ractor_id/identity);
   - `"ts"` - `numeric`/`epoch` - the time when lock was obtained;
-  - `"init_ttl"` - `integer` - (milliseconds) initial lock key ttl;
+  - `"ini_ttl"` - `integer` - (milliseconds) initial lock key ttl;
   - `"rem_ttl"` - `integer` - (milliseconds) remaining lock key ttl;
-  - `<custom metadata>`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock]((#lock---obtain-a-lock)) method documentation);
+  - `<custom metadata>`- `string`/`integer` - custom metadata passed to the `lock`/`lock!` methods via `meta:` keyword argument (see [lock](#lock---obtain-a-lock) method documentation);
   - additional keys for **reentrant locks** and **extendable reentrant locks**:
     - for any type of reentrant locks:
       - `"spc_cnt"` - `integer` - how many times the lock was obtained as reentrant lock;
@@ -1082,7 +1172,7 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999
@@ -1099,7 +1189,7 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 4_999,
@@ -1122,12 +1212,12 @@ rql.lock_info("your_lock_name")
   "lock_key" => "rql:lock:your_lock_name",
   "rw_mode" => "write",
   "acq_id" => "rql:acq:123/456/567/678/374dd74324",
-  "hst_id" => "rql:acq:123/456/678/374dd74324",
+  "hst_id" => "rql:hst:123/456/678/374dd74324",
   "ts" => 123456789.12345,
   "ini_ttl" => 5_000,
   "rem_ttl" => 9_444,
   # ==> keys for any type of reentrant lock:
-  "spc_count" => 2, # how many times the lock was obtained as reentrant lock
+  "spc_cnt" => 2, # how many times the lock was obtained as reentrant lock
   # ==> keys for extendable reentarnt locks with `:extendable_work_through` strategy:
   "spc_ext_ttl" => 5_000, # sum of TTL of the each <extendable> reentrant lock (3_000 + 2_000)
   "l_spc_ext_ini_ttl" => 2_000, # TTL of the last <extendable> reentrant lock
@@ -1209,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);
 
@@ -1228,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
   ]
 }
@@ -1319,7 +1413,7 @@ rql.queued?("your_lock_name") # => true/false
 Return:
 - `[Hash<Symbol,Boolean|Hash<Symbol,Numeric|String|Symbol>>]` (`{ ok: true/false, result: Hasn }`);
 - `:result` format;
-  - `:rel_time` - `Float` - time spent to process redis commands (in seconds);
+  - `:rel_time` - `Float` - time spent to process redis commands (in milliseconds);
   - `:rel_key` - `String` - released lock key (RedisQueudLocks-internal lock key name from Redis);
   - `:rel_queue` - `String` - released lock queue key (RedisQueuedLocks-internal queue key name from Redis);
   - `:queue_res` - `Symbol` - `:released` (or `:nothing_to_release` if the required queue does not exist);
@@ -1334,7 +1428,7 @@ rql.unlock("your_lock_name")
 {
   ok: true,
   result: {
-    rel_time: 0.02, # time spent to lock release (in seconds)
+    rel_time: 0.02, # time spent to lock release (in milliseconds)
     rel_key: "rql:lock:your_lock_name", # released lock key
     rel_queue: "rql:lock_queue:your_lock_name", # released lock key queue
     queue_res: :released, # or :nothing_to_release
@@ -1424,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]`
@@ -1507,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]`
@@ -1615,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]`
@@ -1684,6 +1778,7 @@ rql.release_locks_of(host_id: rql.current_host_id, acquirer_id: rql.current_acqu
     - the lock name which ttl should be extended;
   - `milliseconds` - (required) `[Integer]`
     - how many milliseconds should be added to the lock's TTL;
+    - should be a positive `Integer`;
   - `:read_write_mode` - (optional) `[Symbol]`
     - `:write` (default) - extends the write lock (the behavior described below);
     - `:read` - extends the read lock of the current acquirer only (see [Read/Write Locks](#readwrite-locks)):
@@ -1743,17 +1838,10 @@ rql.release_locks_of(host_id: rql.current_host_id, acquirer_id: rql.current_acqu
     and for the read lock of the current acquirer, the number of extended read locks for `all_read_locks: true`;
 - returns `{ ok: false, result: :async_expire_or_no_lock }` when a lock not found or a lock is already expired during
   some steps of invocation (see **Important** section below);
-- **Important**:
-  - the method is non-atomic cuz redis does not provide an atomic function for TTL/PTTL extension;
-  - the method consists of two commands:
-    - (1) read current pttl;
-    - (2) set new ttl that is calculated as "current pttl + additional milliseconds";
-  - the method uses Redis'es **CAS** (check-and-set) behavior;
-  - what can happen during these steps:
-    - lock is expired between commands or before the first command;
-    - lock is expired before the second command;
-    - lock is expired AND newly acquired by another process (so you will extend the
-      totally new lock with fresh PTTL);
+- **Important** (`:write` mode):
+  - the write lock TTL is extended atomically by one Lua script (`PTTL` + `PEXPIRE` with "current pttl + additional milliseconds");
+  - the lock owner is not checked: the current write lock is extended, so when your lock is expired and newly obtained
+    by another acquirer, the lock of that acquirer is extended;
   - use it at your own risk and consider the async nature when calling this method;
 
 ```ruby
@@ -1909,6 +1997,8 @@ rql.locks_info # or rql.locks_info(scan_size: 123)
     "hst_id"=>"rql:hst:41478/4320/4360/848818f09d8c3420",
     "ts"=>1711607112.670343,
     "ini_ttl"=>15000,
+    "lock_key"=>"rql:lock:some-lock-123",
+    "rw_mode"=>"write",
     "rem_ttl"=>13998}},
   {:lock=>"rql:lock:some-lock-456",
    :status=>:released,
@@ -1929,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)
@@ -1938,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}]},
   ...}>
 ```
 ---
@@ -1956,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
@@ -1966,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
@@ -1979,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);
@@ -2017,7 +2120,8 @@ Accepts:
   - makes sense when instrumentation sampling is enabled;
   - `false` by default;
 
-Returns: `{ ok: true, processed_queues: Set<String> }` returns the list of processed lock queues;
+Returns: `{ ok: true, result: { processed_queues: Set<String> } }` returns the set of processed lock request queues
+(write and read lock request queues);
 
 ```ruby
 rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
@@ -2025,13 +2129,19 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
 # =>
 {
   ok: true,
-  processed_queues: [
-    "rql:lock_queue:some-lock-123",
-    "rql:lock_queue:some-lock-456",
-    "rql:lock_queue:your-other-lock",
-    ...
-  ]
+  result: {
+    processed_queues: #<Set: {
+      "rql:lock_queue:some-lock-123",
+      "rql:lock_queue:some-lock-456",
+      "rql:lock_read_queue:some-lock-456",
+      "rql:lock_queue:your-other-lock",
+      ...
+    }>
+  }
 }
+
+# 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)
 ```
 
 ---
@@ -2061,6 +2171,41 @@ rql.clear_dead_requests(dead_ttl: 60 * 60 * 1000) # 1 hour in milliseconds
   - `:lock_index_grace_period` - (optional) `[Integer]`
     - the lock index grace period (in milliseconds);
     - pre-configured in `config['lock_index_grace_period']`;
+  - `:logger` - (optional) `[::Logger,#debug]`
+    - custom logger object;
+    - pre-configured in `config['logger']`;
+  - `:instrumenter` - (optional) `[#notify]`
+    - custom instrumenter object;
+    - pre-configured in `config['instrumetner']`;
+  - `:instrument` - (optional) `[NilClass,Any]`;
+    - custom instrumentation data wich will be passed to the instrumenter's payload with :instrument key;
+    - `nil` by default (no additional data);
+  - `:log_sampling_enabled` - (optional) `[Boolean]`
+    - enables **log sampling**;
+    - pre-configured in `config['log_sampling_enabled']`;
+  - `:log_sampling_percent` - (optional) `[Integer]`
+    - **log sampling**:the percent of cases that should be logged;
+    - pre-configured in `config['log_sampling_percent']`;
+  - `:log_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]`
+    - **log sampling**: percent-based log sampler that decides should be RQL case logged or not;
+    - pre-configured in `config['log_sampler']`;
+  - `log_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be logged despite the enabled log sampling;
+    - makes sense when log sampling is enabled;
+    - `false` by default;
+  - `:instr_sampling_enabled` - (optional) `[Boolean]`
+    - enables **instrumentaion sampling**;
+    - pre-configured in `config['instr_sampling_enabled']`;
+  - `instr_sampling_percent` - (optional) `[Integer]`
+    - the percent of cases that should be instrumented;
+    - pre-configured in `config['instr_sampling_percent']`;
+  - `instr_sampler` - (optional) `[#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]`
+    - percent-based log sampler that decides should be RQL case instrumented or not;
+    - pre-configured in `config['instr_sampler']`;
+  - `instr_sample_this` - (optional) `[Boolean]`
+    - marks the method that everything should be instrumneted despite the enabled instrumentation sampling;
+    - makes sense when instrumentation sampling is enabled;
+    - `false` by default;
 - returns `{ ok: true, result: { idx_key_cnt: Integer } }` (the number of indexed keys);
 
 ```ruby
@@ -2235,6 +2380,8 @@ rql.possible_host_ids
     # NOTE: auto-swarm your RQL client after initalization (run swarm elements and their supervisor)
     config['swarm.auto_swarm'] = false
 
+    # NOTE: the periods, the zombie ttl and the scan sizes should be positive Integers
+
     # supervisor configs
     config['swarm.supervisor.liveness_probing_period'] = 2 # NOTE: in seconds
 
@@ -2514,19 +2661,121 @@ 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>
 
 - `read_write_mode:` attribute of `#lock` and `#lock!`:
-  - `:write` (default) - exclusive lock (the classic RQL lock): waits for the write lock and for all read locks;
+  - `:write` (**default**) - exclusive lock (the classic RQL lock): waits for the write lock and for all read locks;
   - `:read` - shared lock: waits for the write lock only (read locks of different acquirers work in parallel);
 
 ```ruby
@@ -2535,17 +2784,22 @@ rql.lock('report', read_write_mode: :read) { read_report }
 
 # writer waits for all readers (and readers wait for the writer)
 rql.lock('report', read_write_mode: :write) { rebuild_report }
-rql.lock('report') { rebuild_report } # (write mode is the default mode)
+
+# write mode is default:
+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` (`RedisQueuedLocks::ArgumentError`);
+  - `ttl` should be a positive `Integer`;
   - each read lock has its own data with the same structure as the write lock data: acquirer, host, timestamp,
     initial ttl, `:meta` (with the same reserved keys) and reentrant lock data (`spc_cnt`, `spc_ext_ttl`, ...);
     the read lock data lives as long as the read lock and is returned by `#lock_info`/`#locks_info` for each reader
@@ -2641,12 +2895,13 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 - 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.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");
@@ -2663,24 +2918,38 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 "[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
+  the instrumentation event of the operation without `instrument`):
+
+```ruby
+"[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");
+"[redis_queued_locks.release_locks_of]" # (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+"[redis_queued_locks.extend_lock_ttl]" # (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+"[redis_queued_locks.clear_dead_requests]" # (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+"[redis_queued_locks.reindex_locks]" # (logs "idx_key_cnt", "idx_time", "at");
 ```
 
 - read/write try-lock logs (see [Read/Write Locks](#readwrite-locks)):
@@ -2698,7 +2967,7 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 <sup>\[[back to top](#table-of-contents)\]</sup>
 
 **NOTICE**: logging can be sampled via:
-- `config['log_samplign_enabled'] = true` (**false** by default);
+- `config['log_sampling_enabled'] = true` (**false** by default);
 - `config['log_sampler'] = RedisQueuedLocks::Logging::Sampler` (used by default);
 - see **RedisQueuedLocks::Logging::Sampler** implementation in source code for customization details;
 
@@ -2708,18 +2977,26 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
 # - 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.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");
+#   - "[redis_queued_locks.release_locks_of]" (logs "at", "hst_id", "acq_id", "rel_time", "rel_key_cnt", "tch_queue_cnt");
+#   - "[redis_queued_locks.extend_lock_ttl]" (logs "lock_key", "rw_mode", "all_read_locks", "ext_ttl", "extended_locks_count", "ext_time", "at");
+#   - "[redis_queued_locks.clear_dead_requests]" (logs "dead_ttl", "prc_queue_cnt", "rel_time", "at");
+#   - "[redis_queued_locks.reindex_locks]" (logs "idx_key_cnt", "idx_time", "at");
 #   - "rw_mode" is the requested lock mode ('write'/'read'), the held lock mode for "expire_lock" and "decrease_lock",
 #     the mode of the series for lock series logs;
 # - by default uses VoidLogger that does nothing;
@@ -2737,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
@@ -2758,7 +3036,7 @@ config['log_sampling_enabled'] = false
 
 # (default: 15)
 # - the percent of cases that should be logged;
-# - take an effect when <config['log_sampling_enalbed']> is true;
+# - take an effect when <config['log_sampling_enabled']> is true;
 # - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
 config['log_sampling_percent'] = 15
 
@@ -2825,7 +3103,7 @@ config['instr_sampling_enabled'] = false
 
 # (default: 15)
 # - the percent of cases that should be instrumented;
-# - take an effect when <config['instr_sampling_enalbed']> is true;
+# - take an effect when <config['instr_sampling_enabled']> is true;
 # - works in tandem with <config['instr_sampling_enabled']> and <config['instr_sampler']> configs;
 config['instr_sampling_percent'] = 15
 
@@ -2848,6 +3126,7 @@ config['instr_sampler'] = RedisQueuedLocks::Instrument::Sampler
 List of instrumentation events
 
 - ["redis_queued_locks.lock_obtained"](#redis_queued_lockslock_obtained)
+- ["redis_queued_locks.lock_obtaining_failed"](#redis_queued_lockslock_obtaining_failed)
 - ["redis_queued_locks.extendable_reentrant_lock_obtained"](#redis_queued_locksextendable_reentrant_lock_obtained)
 - ["redis_queued_locks.reentrant_lock_obtained"](#redis_queued_locksreentrant_lock_obtained)
 - ["redis_queued_locks.lock_hold_and_release"](#redis_queued_lockslock_hold_and_release)
@@ -2858,6 +3137,17 @@ List of instrumentation events
 - ["redis_queued_locks.explicit_read_lock_release"](#redis_queued_locksexplicit_read_lock_release)
 - ["redis_queued_locks.explicit_all_locks_release"](#redis_queued_locksexplicit_all_locks_release)
 - ["redis_queued_locks.release_locks_of"](#redis_queued_locksrelease_locks_of)
+- ["redis_queued_locks.extend_lock_ttl"](#redis_queued_locksextend_lock_ttl)
+- ["redis_queued_locks.clear_dead_requests"](#redis_queued_locksclear_dead_requests)
+- ["redis_queued_locks.reindex_locks"](#redis_queued_locksreindex_locks)
+
+What is instrumented (each event has a log line with the same name, see [Logging](#logging)):
+- the lock acquirement (`#lock`/`#lock!`, `#lock_series`/`#lock_series!`): each meaningful outcome (the lock is obtained,
+  not obtained, held and released);
+- each operation that changes Redis keys (`#unlock`, `#unlock_read`, `#clear_locks`, `#clear_locks_of`/`#clear_current_locks`,
+  `#extend_lock_ttl`, `#clear_dead_requests`, `#reindex_locks`): one event with the time of the whole operation;
+- lock information queries (`#lock_info`, `#locks`, `#queues`, `#keys`, ...) are not instrumented;
+- the swarm (`#probe_hosts`, `#flush_zombies` and the swarm elements) is not instrumented yet;
 
 Detalized event semantics and payload structure:
 
@@ -2871,10 +3161,29 @@ 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;
 
+##### `"redis_queued_locks.lock_obtaining_failed"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- a moment when the lock acquirement is failed (the lock is not obtained);
+- raised from `#lock`/`#lock!` (with `raise_errors: true` - before the error is raised) and from `#lock_series`/`#lock_series!`
+  (for the lock of the series that is not obtained);
+- 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;
+  - `:ts` - `numeric`/`epoch` - the time when the lock acquirement is failed;
+  - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
+  - `:result` - `symbol` - the failure result: `:timeout_reached`, `:retry_limit_reached`, `:fail_fast_no_try`,
+    `:fail_fast_after_try`, `:conflict_dead_lock`, `:conflict_lock_upgrade` (see [lock](#lock---obtain-a-lock));
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#lock`/`#lock!` method as `:instrument` attribute;
+
 ##### `"redis_queued_locks.extendable_reentrant_lock_obtained"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
 - an event signalizes about the "extendable reentrant lock" obtaining is happened;
@@ -2883,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;
@@ -2898,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;
@@ -2916,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;
@@ -2934,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;
 
@@ -2944,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;
@@ -2959,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;
@@ -2977,6 +3292,7 @@ Detalized event semantics and payload structure:
   - `:rel_time` - `float`/`milliseconds` - time spent on lock releasing;
   - `:lock_key` - `string` - released lock (lock name);
   - `:lock_key_queue` - `string` - released lock queue (the queue of write lock requests);
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#unlock` method as `:instrument` attribute;
 
 ##### `"redis_queued_locks.explicit_read_lock_release"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
@@ -2999,6 +3315,7 @@ Detalized event semantics and payload structure:
   - `:at` - `float`/`epoch` - the time when the operation has ended;
   - `:rel_key_cnt` - `integer` - released redis keys count (write locks, readers registries, read lock data,
     write and read lock request queues);
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_locks` method as `:instrument` attribute;
 
 ##### `"redis_queued_locks.release_locks_of"`
 - <sup>\[[back to the list](#instrumentation-events)\]</sup>
@@ -3011,6 +3328,42 @@ Detalized event semantics and payload structure:
   - `:hst_id` - `string` - refused host identifier;
   - `:rel_key_cnt` - `integer` - released locks count (write locks and read locks);
   - `:tch_queue_cnt` - `:integer` - the number of queues (write and read lock request queues) from which the concrete host/acquirer was removed;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_locks_of`/`#clear_current_locks` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.extend_lock_ttl"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the lock TTL extension (successful or not);
+- raised from `#extend_lock_ttl`;
+- payload:
+  - `:lock_key` - `string` - lock key (`rql:lock:<lock_name>`);
+  - `:rw_mode` - `symbol` - `:write` (the write lock) or `:read` (the read lock of the acquirer or all read locks);
+  - `:all_read_locks` - `boolean` - all read locks of the lock are extended (`:read` mode);
+  - `:ext_ttl` - `integer`/`milliseconds` - the extension (`milliseconds` argument);
+  - `:extended_locks_count` - `integer` - the number of extended locks (`0` when nothing is extended);
+  - `:ext_time` - `float`/`milliseconds` - time spent on the extension;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#extend_lock_ttl` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.clear_dead_requests"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the dropped dead lock requests;
+- raised from `#clear_dead_requests`;
+- payload:
+  - `:dead_ttl` - `integer`/`milliseconds` - lock requests older than `dead_ttl` are dropped;
+  - `:prc_queue_cnt` - `integer` - the number of processed lock request queues (write and read);
+  - `:rel_time` - `float`/`milliseconds` - time spent on the operation;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#clear_dead_requests` method as `:instrument` attribute;
+
+##### `"redis_queued_locks.reindex_locks"`
+- <sup>\[[back to the list](#instrumentation-events)\]</sup>
+- an event signalizes about the lock keys added to the [Lock Index](#lock-index);
+- raised from `#reindex_locks`;
+- payload:
+  - `:idx_key_cnt` - `integer` - the number of indexed keys;
+  - `:idx_time` - `float`/`milliseconds` - time spent on the operation;
+  - `:at` - `float`/`epoch` - the time when the operation has ended;
+  - `:instrument` - `nil`/`Any` - custom data passed to the `#reindex_locks` method as `:instrument` attribute;
 
 ---
 
@@ -3028,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);
@@ -3046,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);
@@ -3094,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
@@ -3106,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`
 ```
 
 ---