redis_queued_locks 1.16.2 → 1.17.0

data/.claude/rules/type-checking.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "sig/**/*.rbs"
+  - "Steepfile"
+  - "rbs_collection.yaml"
+  - "lib/**/*.rb"
+---
+
+# Type-checking rules (`sig/`, Steep, RBS)
+
+## Observed conventions
+- `sig/` mirrors `lib/` one file per file (`lib/redis_queued_locks/acquirer/is_locked.rb` → `sig/redis_queued_locks/acquirer/is_locked.rbs`). Known typo: `sig/redis_queued_locks/acquier.rbs` is the `Acquirer` namespace file.
+- RBS uses fully nested `module RedisQueuedLocks / module Acquirer / ...` blocks (unlike compact Ruby constants).
+- Common aliases at the top: `use RedisQueuedLocks as RQL`, `use RedisClient as RC`; Redis connections typed as `RC::client`.
+- Shared duck types live in `sig/redis_queued_locks.rbs`: `_Loggable`, `_Instrumentable`, `loggerObj`, `instrObj`; samplers as `RQL::Logging::samplerObj` / `RQL::Instrument::samplerObj`.
+- Result shapes are named record aliases inside the module, e.g. `type extendResult = { ok: bool, result: Symbol }`.
+- Module functions are declared `def self.name: (...) -> T`; long signatures put one param per line with names.
+- Instance variables are declared (`@config_setters: configSetters`) and attr readers typed.
+- Third-party types: `sig/vendor/*.rbs` hand-written stubs (redis_client, active_support, semantic_logger) plus `rbs collection` gems (redis-client, securerandom, timeout, logger, monitor) installed into `.gem_rbs_collection/`.
+- `Steepfile`: target `lib`, signatures `sig`, ignores `spec`, libraries timeout/securerandom/logger/monitor, diagnostics `Steep::Diagnostic::Ruby.strict`.
+- In Ruby code: `# @type var x: T` and `x = ... #: T` annotations narrow types; `# steep:ignore` silences spots Steep really reports (nil-narrowed `attr_reader` results, pattern-matching destructures, splats). `Config#[]` returns `untyped`, so `config['...']` defaults in `Client` need no ignore.
+- Steep 2 narrows on `==` with literals (`x == :sym` makes `x` the literal type `:sym`) and rejects `# @type var` annotations that widen a narrowed variable; RBS 4's `Kernel#Array` has a `(nil) -> []` overload that `untyped` arguments resolve to, so `Array(rconn.call(...)).first` needs a `#: T` assertion.
+- Runtime checking: CI runs specs with `RUBYOPT=-rrbs/test/setup RBS_TEST_TARGET='RedisQueuedLocks::*'`, so signatures must match real runtime values, not just Steep's view.
+
+## Claude rules
+1. Every change to a `lib/` file's public or private API (new method, param, return shape, constant, ivar) must be reflected in the mirrored `.rbs` file in the same change.
+2. Create new `.rbs` files at the mirrored path with nested module blocks and `use RedisQueuedLocks as RQL` / `use RedisClient as RC` aliases when needed.
+3. Reuse shared types (`RQL::loggerObj`, `RQL::instrObj`, `samplerObj`, `RC::client`) instead of `untyped`; use `untyped` only for truly dynamic values (e.g. user `meta`, `instrument`).
+4. Name public API result hashes with a `type xxxResult = { ok: bool, result: ... }` alias next to the method. Type internal swarm element replies with plain types (`bool`, `String`, a flat record such as `{ alive: bool, state: String }`, optional `?` for `nil`) instead of `{ ok:, result: }` records.
+5. Prefer fixing types or adding `# @type var` / `#: T` annotations over `# steep:ignore`; add `# steep:ignore` only where Steep reports a diagnostic. Strict mode fails the build on `Ruby::RedundantIgnoreComment`, so never add a speculative ignore and remove ones that become redundant.
+6. Don't loosen `Steep::Diagnostic::Ruby.strict` or add `ignore` entries to the `Steepfile`.
+7. New third-party gem used in `lib/`: add it to `rbs_collection.yaml` (and `sig/manifest.yml` for stdlib) or write a minimal stub in `sig/vendor/`.
+8. Verify with `bundle exec rbs collection install && bundle exec rake steep:check`; for signature/runtime mismatches run the specs under RBS runtime testing (command in `.github/workflows/typecheck-runtime.yml`).
+9. Don't rename `acquier.rbs` unless asked; it is a known quirk.
+
+## Recommendations (proposed, not yet project policy)
+1. Make the runtime type-check CI job blocking (drop `--failure-exit-code=0`) once current violations are fixed.
+2. Type `config['...']` lookups (`Config#[]` returns `untyped`, so `Client` keyword defaults are unchecked) with a typed config accessor (e.g. per-key typed readers or an RBS overload table for `Config#[]`).
+3. Remove duplicate entries in `rbs_collection.yaml` (`redis-client` and `securerandom` are listed twice) and pin the `gem_rbs_collection` revision instead of `main` for reproducible checks.
+4. Rename `sig/redis_queued_locks/acquier.rbs` to `acquirer.rbs` in a dedicated change.
+5. Replace remaining `untyped` in signatures with precise unions or interfaces where the value set is known (e.g. strategy symbols as `:queued | :random`).
+6. Type strategy and mode options as literal unions (`conflict_strategy: :wait_for_lock | :work_through | :extendable_work_through | :dead_locking`) so Steep catches invalid values.

data/.claude/rules/visitors.md

@@ -0,0 +1,64 @@
+---
+paths:
+  - "lib/redis_queued_locks/acquirer/**/*.rb"
+  - "lib/redis_queued_locks/logging.rb"
+  - "lib/redis_queued_locks/logging/**/*.rb"
+  - "lib/redis_queued_locks/instrument.rb"
+  - "lib/redis_queued_locks/instrument/**/*.rb"
+---
+
+# Log & instrumentation visitors
+
+## What it is
+The project calls these modules "visitors", but they are not GoF Visitor (no `accept`/double dispatch). They are **stateless event-hook modules**: one module per algorithm component, one method per lifecycle event. They take the observability "port" (`logger` or `instrumenter`) plus event data, and emit exactly one log line or one notification. The algorithm code only says *what happened* (`LogVisitor.lock_obtained(...)`); the visitor decides *how it is reported*.
+
+**Why**: keeps the lock algorithm readable (one call per event instead of inline string building), centralizes event names and payload shapes, makes sampling and error-swallowing uniform, and gives RBS a typed contract for every event.
+
+## Where they live
+| Visitor | File | Events |
+|---|---|---|
+| `AcquireLock::LogVisitor` | `acquire_lock/log_visitor.rb` | 6: `start_lock_obtaining`, `start_try_to_lock_cycle`, `dead_score_reached__reset_acquirer_position`, `extendable_reentrant_lock_obtained`, `reentrant_lock_obtained`, `lock_obtained` |
+| `AcquireLock::InstrVisitor` | `acquire_lock/instr_visitor.rb` | 5: `extendable_reentrant_lock_obtained`, `reentrant_lock_obtained`, `lock_obtained`, `reentrant_lock_hold_completes`, `lock_hold_and_release` |
+| `AcquireLock::TryToLock::LogVisitor` | `acquire_lock/try_to_lock/log_visitor.rb` | 14 step-level events (`start`, `rconn_fetched`, `acq_added_to_queue`, `exit__no_first`, `obtain__free_to_acquire`, ...) |
+| `AcquireLock::YieldExpire::LogVisitor` | `acquire_lock/yield_expire/log_visitor.rb` | `expire_lock`, `decrease_lock` |
+| `AcquireLock::DequeueFromLockQueue::LogVisitor` | `acquire_lock/dequeue_from_lock_queue/log_visitor.rb` | `dequeue_from_lock_queue` |
+| `LockSeriesPoC::LogVisitor` / `InstrVisitor` | `lock_series_poc/*_visitor.rb` | lock series events (no RBS, `# steep:ignore`) |
+
+Not covered by visitors: `release_lock`, `release_all_locks`, `release_locks_of` call `instrumenter.notify` inline inside `run_non_critical`, and do not log at all (their `logger` param is unused).
+
+## Observed conventions
+- **Placement**: a visitor sits in a subdirectory named after the component it reports on (`<component>/log_visitor.rb`, `<component>/instr_visitor.rb`) and is loaded by that component with `require_relative` at the top of the module body.
+- **Shape**: `module <Component>::LogVisitor` / `::InstrVisitor`, `# @api private`, all methods inside `class << self`, full YARD block per method; return `void`.
+- **Method name = event name**: snake_case; double underscore separates phase and detail (`exit__queue_ttl_reached`, `reentrant_lock__work_through`). The LogVisitor and InstrVisitor use the same method name for the same event.
+- **Parameter order**: `(port, sampled_flag, [extra gate], lock_key, ...event data..., [instrument])`:
+  - LogVisitor: `(logger, log_sampled, ...)`; `TryToLock::LogVisitor` adds `log_lock_try` as the third arg (fine-grained step logs are opt-in through `config['log_lock_try']`).
+  - InstrVisitor: `(instrumenter, instr_sampled, lock_key, ttl, acq_id, hst_id, ts, acq_time, [hold_time], instrument)`; the user's `instrument` value is always last.
+- **Guard first**: `return unless log_sampled` (`&& log_lock_try` for try-lock steps) / `return unless instr_sampled`. The sampling decision is computed **once per operation** in the caller via `Logging.should_log?` / `Instrument.should_instrument?` and passed down as a boolean.
+- **Log format**: one `logger.debug { ... }` block (lazy string), message = `"[redis_queued_locks.<event>] "` (`[redis_queued_locks.try_lock.<event>]` for TryToLock steps) followed by `key => value` pairs; string values in single quotes (`lock_key => '...'`), numbers bare; abbreviated keys `acq_id`, `hst_id`, `acs_strat`. Built with `\` line continuations.
+- **Instrumentation format**: `instrumenter.notify('redis_queued_locks.<event>', { lock_key:, ttl:, acq_id:, hst_id:, ts:, acq_time:, instrument: })` using shorthand hash syntax and Symbol keys.
+- **Never raise**: every emit ends with `rescue nil` (modifier), so a broken logger/instrumenter can't affect lock correctness.
+- **Call sites**: plain module calls with positional args, usually grouped on 2-3 lines (`LogVisitor.lock_obtained(logger, log_sampled, lock_key, ...)`); data comes from local vars or the `result` hash of the step.
+- **Typing**: each visitor (except lock_series_poc) has an RBS file with `def self.<event>: (RQL::loggerObj logger, bool log_sampled, ...) -> void` / `RQL::instrObj instrumenter`.
+
+## Claude rules
+**When to use**
+1. Any new log line or instrumentation event inside `AcquireLock` (and its mixins) or `LockSeriesPoC` must go through a visitor method; never call `logger.*` or `instrumenter.notify` directly in algorithm code.
+2. Add a LogVisitor event for each new meaningful step or branch of the algorithm (start, decision, exit, success). Add an InstrVisitor event only for outcomes users would want to measure (obtained, held/released, completed); not for internal steps.
+3. Fine-grained per-attempt logging belongs in `TryToLock::LogVisitor` and must be gated by `log_lock_try`.
+4. For a new algorithm component (new mixin under `acquire_lock/`), create its own `<component>/log_visitor.rb` (and `instr_visitor.rb` if needed) and `require_relative` it from the component.
+
+**How to write one**
+5. Method: inside `class << self`, named exactly after the event (snake_case, `__` for phase/detail), full YARD with `@return [void]`, `@api private`, `@since <next version>`.
+6. Parameters: port first, sampled flag second, extra gates next, then `lock_key`, then event data; for instrumentation keep the user `instrument` value last. Keep the list explicit (see `arguments.md`).
+7. First line: `return unless <sampled>` (plus gate). Don't compute sampling inside the visitor and don't recompute it at the call site per event; reuse the operation's `log_sampled` / `instr_sampled`.
+8. Logs: `logger.debug do ... end rescue nil` with message `"[redis_queued_locks.<event>] "` (`try_lock.` prefix for TryToLock steps) and `key => value` pairs, quoting strings, using the existing abbreviations (`acq_id`, `hst_id`, `acs_strat`, `queue_ttl`).
+9. Instrumentation: `instrumenter.notify('redis_queued_locks.<event>', { ... }) rescue nil` with shorthand Symbol keys; reuse the standard payload keys (`lock_key`, `ttl`, `acq_id`, `hst_id`, `ts`, `acq_time`, `hold_time`, `instrument`). Event names are public API: never rename or remove one without being asked, and document new ones in the README/CHANGELOG.
+10. Use the same method name in LogVisitor and InstrVisitor when both report the same event.
+11. Add the method to the mirrored RBS visitor file (`RQL::loggerObj` / `RQL::instrObj`, `bool` sampled flag, `-> void`) and cover the new event in specs via the fake logger/notifier (assert on the `[redis_queued_locks.<event>]` prefix or event name).
+
+## Recommendations (proposed, not yet project policy)
+Apply to new or touched code; don't refactor existing code for these unless asked.
+1. Give the release operations (`release_lock`, `release_all_locks`, `release_locks_of`) their own `InstrVisitor`/`LogVisitor` instead of inline `instrumenter.notify`, and either use or drop their currently unused `logger` param.
+2. Use one error-swallowing style consistently (visitors use modifier `rescue nil`, release modules use `run_non_critical`). Both silently hide bugs such as a `NoMethodError` inside the log block, so consider reporting swallowed errors when the debugger is enabled.
+3. Keep log and instrumentation event names in one registry constant (e.g. `RedisQueuedLocks::Instrument::EVENTS`) so README, specs and RBS can be checked against it.
+4. Fix the RBS path mismatch: `sig/.../acquire_lock/yield_with_expire/log_visitor.rbs` mirrors `lib/.../acquire_lock/yield_expire/log_visitor.rb`; add RBS for `lock_series_poc` visitors when the PoC stabilizes.

data/.rubocop.rbs.yml

@@ -0,0 +1,31 @@
+# NOTE: RBS cops only: RBS signatures (sig/**/*.rbs) and inline RBS annotations in Ruby sources
+#   (lib/**/*.rb, RBSInline/* cops). Ruby cops are disabled here: Ruby sources are linted with .rubocop.yml;
+inherit_gem:
+  armitage-rubocop:
+    - lib/rubocop.rbs.yml
+
+AllCops:
+  TargetRubyVersion: 4.0
+  NewCops: enable
+  DisabledByDefault: true
+  UseProjectIndex: false
+  Include:
+    - sig/**/*.rbs
+    - lib/**/*.rb
+  # NOTE: files with a ruby shebang are picked up implicitly;
+  Exclude:
+    - bin/**/*
+  SuggestExtensions: false
+
+# NOTE: `DisabledByDefault` is not enough for Ruby sources: inline `# rubocop:enable <Cop>`
+#   (and `# rubocop:enable all`) directives in lib/ re-enable Ruby cops for the rest of the file;
+#   so Ruby cop departments are excluded explicitly (they are covered by .rubocop.yml);
+Bundler: { Exclude: ['**/*'] }
+Gemspec: { Exclude: ['**/*'] }
+Layout: { Exclude: ['**/*'] }
+Lint: { Exclude: ['**/*'] }
+Metrics: { Exclude: ['**/*'] }
+Migration: { Exclude: ['**/*'] }
+Naming: { Exclude: ['**/*'] }
+Security: { Exclude: ['**/*'] }
+Style: { Exclude: ['**/*'] }

data/.rubocop.yml

@@ -3,15 +3,15 @@ inherit_gem:
     - lib/rubocop.general.yml
     - lib/rubocop.rake.yml
     - lib/rubocop.rspec.yml
-    - lib/rubocop.rbs.yml
 
+# NOTE: Ruby sources only. RBS signatures (sig/**/*.rbs) are linted separately with
+#   .rubocop.rbs.yml: the Ruby cops (and the project index they use) must not see them;
 AllCops:
-  TargetRubyVersion: 3.3
+  TargetRubyVersion: 4.0
   NewCops: enable
   Include:
     - lib/**/*.rb
     - spec/**/*.rb
-    - sig/**/*.rbs
     - Gemfile
     - Rakefile
     - redis_queued_locks.gemspec

data/.ruby-version

@@ -1 +1 @@
-3.4.5
+4.0.7

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [1.17.0] - 2026-10-04
+### Changed
+- [**Breaking**] Minimal Ruby Version - **4.0** (previously - **3.3**):
+  - removed `3.3` and `3.4` from `CI`;
+- Swarm: isolated swarm elements (`RedisQueuedLocks::Swarm::SwarmElement::Isolated`, `FlushZombies`) are reworked
+  to the Ruby 4 Ractor API: `Ractor.yield`/`Ractor#take` are replaced with `Ractor::Port`s (each element owns
+  its own pair of ports: the results port is created in the main ractor where the swarm supervisor lives and the
+  command port is created inside the element ractor), element ractor termination is tracked via `Ractor#monitor`;
+- Swarm: isolated element ractor is terminated deterministically on `#try_kill!` / `#deswarm!`
+  (all ractor threads are killed and joined);
+- Swarm: `RedisQueuedLocks::Swarm::SwarmElement::Isolated` subclasses implement `#spawn_swarm_element!(results_port)`
+  instead of `#swarm!`;
+- Swarm: internal swarm element protocol (`Threaded` and `Isolated` command replies, isolated element handshake)
+  uses bare scalars/primitives instead of `{ ok:, result: }` wrappers (the wrapper is kept for the public API only);
+### Fixed
+- `RedisQueuedLocks::Client#zombies_info`: default `lock_scan_size` was taken from the
+  `swarm.flush_zombies.zombie_ttl` config instead of `swarm.flush_zombies.zombie_lock_scan_size`;
+
 ## [1.16.2] - 2026-02-06
 ### Fixed
 - `lock_series` PoC:

data/CLAUDE.md

@@ -0,0 +1,31 @@
+# CLAUDE.md
+
+Ruby gem: distributed Redis locks with a per-lock FIFO acquisition queue. Ruby >= 4.0; only runtime dep is `redis-client ~> 0.20`.
+Full details (config keys, key layout, events, errors, stack, CI): `.claude/project-overview.md`.
+
+## Commands
+- Tests (need a running local Redis): `bundle exec rake rspec`
+- Lint: `bundle exec rake rubocop`
+- Static types: `bundle exec rbs collection install && bundle exec rake steep:check`
+
+## Architecture
+- `client.rb`: public API facade; fills defaults from `config[...]`, delegates to `Acquirer::*`.
+- `acquirer/*.rb`: one stateless module per operation (`class << self`), returns `{ ok:, result: }`; `!` client methods raise.
+- `acquirer/acquire_lock.rb`: composed via `extend` mixins in `acquire_lock/` (try_to_lock, with_acq_timeout, delay_execution, dequeue_from_lock_queue, yield_expire) + `LogVisitor`/`InstrVisitor` event hooks.
+- Locking: `ZADD NX` into `rql:lock_queue:<name>`, then WATCH/MULTI on `rql:lock:<name>`; Lua for TTL extension.
+- Strategies: `access_strategy` `:queued`|`:random`; `conflict_strategy` `:wait_for_lock`|`:work_through`|`:extendable_work_through`|`:dead_locking`.
+- `resource.rb`: all key names and acquirer/host IDs. `config.rb`: `setting`/`validate` DSL, read as `config['a.b']`.
+- `swarm/`: zombie-lock cleanup. `Supervisor` thread revives `ProbeHosts` (`SwarmElement::Threaded`) and `FlushZombies` (`SwarmElement::Isolated`, Ractor talking via `Ractor::Port`s); each element runs a main-loop thread with its own Redis connection.
+- `logging/`, `instrument/`: Void null-object defaults, percent samplers, ActiveSupport adapter.
+- `sig/`: RBS mirror of `lib/`. `spec/redis_queued_locks_spec.rb`: single integration spec.
+
+## Rules
+Detailed, path-scoped rules in `.claude/rules/`: `logic.md` (lib, general), `acquirer.md` (acquirer modules, Redis access), `visitors.md` (log/instrumentation visitors), `arguments.md` (long keyword lists), `swarm.md` (swarm supervisor/elements, Ractor/Thread rules), `tests.md` (spec), `type-checking.md` (sig/Steep).
+- Long explicit keyword/parameter lists are intentional (minimal allocations, signature-as-DSL): never introduce parameter objects, option structs or `**opts`; add new options as explicit keywords to every `Client` variant and forward them by name.
+- Update the matching `sig/*.rbs` for every `lib/` change; keep Steep green.
+- Keep `# frozen_string_literal: true` and YARD `@api`/`@since`/`@version` tags.
+- `{ ok:, result: }` is for the public API only (`Client`, `Acquirer::*`, `Swarm` facade actions). Internal swarm element APIs (commands, replies, helpers) use bare scalars/primitives (see `swarm.md`).
+- New operation: `Acquirer::*` module, thin `Client` method (+ `!` variant), RBS, spec.
+- New option: `setting` (+ `validate`) in `config.rb`.
+- Dev gems go in `Gemfile`, not the gemspec.
+- Known debt: rspec-retry, disabled coverage minimum, runtime type-check CI uses `--failure-exit-code=0`.

data/README.md

@@ -2,7 +2,7 @@
 
 [![Tests (RSpec)](https://github.com/0exp/redis_queued_locks/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/0exp/redis_queued_locks/actions) [![Lint (Rubocop)](https://github.com/0exp/redis_queued_locks/actions/workflows/lint.yml/badge.svg?branch=master)](https://github.com/0exp/redis_queued_locks/actions) [![TypeCheck (Runtime/RBS)](https://github.com/0exp/redis_queued_locks/actions/workflows/typecheck-runtime.yml/badge.svg?branch=master)](https://github.com/0exp/redis_queued_locks/actions) [![TypeCheck (Static/Steep)](https://github.com/0exp/redis_queued_locks/actions/workflows/typecheck-static.yml/badge.svg?branch=master)](https://github.com/0exp/redis_queued_locks/actions)
 
-<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.
+**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.
 
@@ -12,6 +12,10 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 
 ---
 
+#### For future features and updates check the [ROADMAP](#roadmap) section.
+
+---
+
 ## Table of Contents
 
 - [Requirements](#requirements)
@@ -89,7 +93,7 @@ Provides flexible invocation flow, parametrized limits (lock request ttl, lock t
 - Redis Version: `>= 7`, `~> 8.x`;
 - Redis Protocol: `RESP3`;
 - gem `redis-client`: `~> 0.20`;
-- Ruby: `>= 3.3`;
+- Ruby: `>= 4.0`;
 
 ---
 
@@ -371,6 +375,8 @@ end
 
 - [lock](#lock---obtain-a-lock)
 - [lock!](#lock---exeptional-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)
@@ -2449,8 +2455,17 @@ Detalized event semantics and payload structure:
     - `write` - waits - `read`;
     - `write` - waits - `write`;
     - **write** mode is a default behavior for all RQL locks;
+  - `README`-section `Issues with other Libs` about issues in other libraries that can broke RQL features:
+    - `Sentry`'s' bugs with Ractors:
+      - `Sentry`-OpenTelemetry problems with its global mutexes and non-sharable objects that is not accessible from the ractors (sentry tyies to
+        intercept all `redis-client` invocations managing their logic via global Mutex instance that brokes `swarm-mode` with `non-sharable` memory
+        access errors, cuz RQL's swarm works using its own RedisClient-instnace, that fails isnide the `Sentry`'s patch: Sentry tries to use the same
+        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**:
   - 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);
   - think about "thread priority" configuration :thinking:;
   - add `hst_id` to all methods that works with queues info;
   - try to return the `fiber object id` to the lock host identifier (we cant use fiber object id cuz `ObjectSpace` has no access to the fiber object space after the any ractor object initialization)
@@ -2472,7 +2487,7 @@ Detalized event semantics and payload structure:
   - better code stylization (+ some refactorings);
   - `RedisQueuedLocks::Acquirer::Try.try_to_lock` - detailed successful result analization;
   - Support for LIFO strategy;
-  - better specs with 100% test coverage (total specs rework);
+  - specs refactoring with 100% test coverage (total specs rework);
   - statistics with UI;
   - JSON log formatter;
   - **automatic** deadlock detection;
@@ -2485,6 +2500,7 @@ Detalized event semantics and payload structure:
   - yardoc docs with CI check (full doc coverage check);
   - split *exception* inheritance to the groups: `lock obtaining errors`, `block invocation errors`, `swarm errors`, and other groups (research possible groups):
     - in some cases we need to intercept "Lock Obtaining Process Erros", in other cases: "Block Invocation Errors", and so on (in `Lock Serirs PoC` for example);
+  - think about `#debounce` and `#throttle` mechanisms;
 
 ---
 

data/Rakefile

@@ -11,18 +11,47 @@ require 'rubocop-rake'
 require 'rubocop-on-rbs'
 require 'rubocop-thread_safety'
 
-RuboCop::RakeTask.new(:rubocop) do |t|
+# NOTE: Ruby sources and RBS signatures are linted by separate runs with separate configs:
+#   Ruby cops (and the project index they use) must not see RBS signatures;
+desc 'Run RuboCop for Ruby sources'
+RuboCop::RakeTask.new('rubocop:ruby') do |t|
+  # NOTE: replace the default "Running RuboCop..." message (printed when verbose);
+  t.verbose = false
+  puts 'Running RuboCop (Ruby sources)...'
   config_path = File.expand_path(File.join('.rubocop.yml'), __dir__)
   t.options = [
     '--config', config_path,
     '--plugin', 'rubocop-rspec',
     '--plugin', 'rubocop-performance',
     '--plugin', 'rubocop-rake',
-    '--plugin', 'rubocop-on-rbs',
     '--plugin', 'rubocop-thread_safety'
   ]
 end
 
+desc 'Run RuboCop for RBS signatures and inline RBS annotations'
+RuboCop::RakeTask.new('rubocop:rbs') do |t|
+  # NOTE: replace the default "Running RuboCop..." message (printed when verbose);
+  t.verbose = false
+  puts 'Running RuboCop (RBS signatures and inline RBS annotations)...'
+  config_path = File.expand_path(File.join('.rubocop.rbs.yml'), __dir__)
+  t.options = [
+    '--config', config_path,
+    '--plugin', 'rubocop-on-rbs'
+  ]
+end
+
+desc 'Run RuboCop for Ruby sources and RBS signatures'
+task :rubocop do
+  # NOTE: run both linters even if the first one fails (a failed RuboCop task aborts);
+  failed = %w[rubocop:ruby rubocop:rbs].reject do |task_name|
+    Rake::Task[task_name].invoke
+    true
+  rescue SystemExit
+    false
+  end
+  abort("RuboCop failed: #{failed.join(', ')}") if failed.any?
+end
+
 RSpec::Core::RakeTask.new(:rspec)
 Steep::RakeTask.new(:steep)
 

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

@@ -12,7 +12,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::DelayExecution
   # @api private
   # @since 1.0.0
   def delay_execution(retry_delay, retry_jitter)
-    delay = (retry_delay + ::Kernel.rand(retry_jitter)).to_f / 1_000
-    ::Kernel.sleep(delay)
+    delay = (retry_delay + Kernel.rand(retry_jitter)).to_f / 1_000
+    Kernel.sleep(delay)
   end
 end

data/lib/redis_queued_locks/acquirer/acquire_lock/try_to_lock.rb

@@ -161,7 +161,6 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
           )
           inter_result = :extendable_conflict_work_through
 
-          # @type var sp_conflict_status: Symbol
           # @type var spc_processed_timestamp: Float
           LogVisitor.reentrant_lock__extend_and_work_through(
             logger, log_sampled, log_lock_try, lock_key,
@@ -188,7 +187,6 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
             'l_spc_ts', spc_processed_timestamp = Time.now.to_f
           )
 
-          # @type var sp_conflict_status: Symbol
           # @type var spc_processed_timestamp: Float
           LogVisitor.reentrant_lock__work_through(
             logger, log_sampled, log_lock_try, lock_key,
@@ -200,7 +198,6 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
           inter_result = :conflict_dead_lock
           spc_processed_timestamp = Time.now.to_f
 
-          # @type var sp_conflict_status: Symbol
           # @type var spc_processed_timestamp: Float
           LogVisitor.single_process_lock_conflict__dead_lock(
             logger, log_sampled, log_lock_try, lock_key,
@@ -242,7 +239,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::TryToLock
           )
 
           # Step 3: get the actual acquirer waiting in the queue
-          waiting_acquirer = Array(rconn.call('ZRANGE', lock_key_queue, '0', '0')).first
+          waiting_acquirer = Array(rconn.call('ZRANGE', lock_key_queue, '0', '0')).first #: String?
 
           LogVisitor.get_first_from_queue(
             logger, log_sampled, log_lock_try, lock_key,

data/lib/redis_queued_locks/acquirer/acquire_lock/yield_expire.rb

@@ -87,7 +87,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
           acquirer_id,
           host_id,
           meta,
-          &block # steep:ignore
+          &block
         )
       else
         yield

data/lib/redis_queued_locks/acquirer/acquire_lock.rb

@@ -7,7 +7,6 @@
 # rubocop:disable Metrics/MethodLength
 # rubocop:disable Metrics/ClassLength
 # rubocop:disable Metrics/BlockNesting
-# rubocop:disable Style/IfInsideElse
 module RedisQueuedLocks::Acquirer::AcquireLock
   require_relative 'acquire_lock/log_visitor'
   require_relative 'acquire_lock/instr_visitor'
@@ -563,9 +562,7 @@ module RedisQueuedLocks::Acquirer::AcquireLock
             end
           end
         else
-          # rubocop:disable Layout/LineLength
           { ok: true, result: acq_process[:lock_info] } #: { ok: bool, result: Hash[Symbol,untyped] }
-          # rubocop:enable Layout/LineLength
         end
       else
         if acq_process[:result] != :retry_limit_reached &&
@@ -588,4 +585,3 @@ end
 # rubocop:enable Metrics/MethodLength
 # rubocop:enable Metrics/ClassLength
 # rubocop:enable Metrics/BlockNesting
-# rubocop:enable Style/IfInsideElse

data/lib/redis_queued_locks/acquirer/lock_series_poc/instr_visitor.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 # NOTE: Lock Series PoC
-# steep:ignore
 # @api private
 # @since 1.16.1
 module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
@@ -48,4 +47,3 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC::InstrVisitor # steep:ignore
     end
   end
 end
-# steep:ignore

data/lib/redis_queued_locks/acquirer/lock_series_poc/log_visitor.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 # NOTE: Lock Series PoC
-# steep:ignore
 # @api private
 # @since 1.16.1
 module RedisQueuedLocks::Acquirer::LockSeriesPoC::LogVisitor # steep:ignore

data/lib/redis_queued_locks/acquirer/lock_series_poc.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 # NOTE: Lock Series PoC
-# steep:ignore
 # rubocop:disable all
 # @api private
 # @since 1.16.0
@@ -324,5 +323,4 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     end
   end
 end
-# steep:ignore
 # rubocop:enable all