redis_queued_locks 1.17.0 → 1.18.0

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 ## [Unreleased]
 
+## [1.18.0] - 2026-10-11
+### Added
+- Brand new feature - **Read/Write locks**: `read_write_mode:` attribute of `#lock`/`#lock!`/`#lock_series`/`#lock_series!` (`:write` by default):
+  - `:write` - 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);
+  - `:queued` access strategy orders read and write lock requests in FIFO between modes (writers are not starved by readers);
+  - `:random` access strategy ignores lock queues (a continuous flow of readers can starve writers);
+  - read locks are stored in `rql:lock_readers:<lock_name>` (`ZSET`: acquirer id => expiration time in Redis time),
+    read lock requests - in `rql:lock_read_queue:<lock_name>`, read lock data - in `rql:lock_reader:<lock_name>:<acquirer_id>`
+    (the same structure as the write lock: acquirer, host, timestamp, ttl, `:meta`, reentrant lock data);
+    write locks and write lock requests use the classic keys;
+  - mutual exclusion is based on optimistic transactions (`WATCH`/`MULTI`, no Lua): readers watch the write lock key,
+    writers watch the write lock key and the read locks key (readers never invalidate transactions of each other);
+  - reentrant locks: read lock request under the obtained lock works as a reentrant lock of the obtained lock;
+    read-to-write lock upgrade fails with `RedisQueuedLocks::ConflictLockObtainError` (`:conflict_lock_upgrade`)
+    for `:work_through`/`:extendable_work_through` conflict strategies;
+  - `#unlock`, `#clear_locks`, `#clear_locks_of`, `#clear_current_locks`, `#clear_dead_requests`, `#flush_zombies`,
+    `#zombie_locks`, `#zombie_acquirers`, `#zombies_info`, `#locked?`, `#queued?`, `#lock_info`, `#queue_info`,
+    `#locks`, `#locks_info`, `#queues`, `#queues_info` support read locks and read lock requests;
+  - logs: `rw_mode` in the lock logs and in the lock series logs (`start_lock_series_obtaining`, `lock_series_obtained`,
+    `expire_lock_series`: the mode of the series); new try-lock log events: `exit__write_request_ahead`, `exit__read_request_ahead`,
+    `exit__read_lock_still_obtained`, `single_process_lock_conflict__lock_upgrade`;
+  - instrumentation: `rw_mode` in `lock_obtained`, `reentrant_lock_obtained`, `extendable_reentrant_lock_obtained`,
+    `lock_hold_and_release`, `reentrant_lock_hold_completes` payloads and in the lock series payloads
+    (`lock_series_obtained`, `lock_series_hold_and_release`: the mode of the series);
+  - `:meta` for read locks (stored in the read lock data of each reader, returned by `#lock_info`/`#locks_info`);
+  - `#lock_series` with `read_write_mode: :read` (PoC): a series of read locks; only read locks obtained by the series
+    are released (reentrant read locks of the outer logic are kept);
+  - `#unlock_read` (aka `#release_read_lock`): releases the read lock of the current acquirer only
+    (new instrumentation event: `redis_queued_locks.explicit_read_lock_release`);
+  - `#extend_lock_ttl`: `read_write_mode:` (`:write` by default) and `identity:` options; `:read` mode extends the read lock
+    of the current acquirer only (an expired read lock or a read lock replaced by a writer is not extended);
+  - `#extend_lock_ttl`: `all_read_locks:` option (`false` by default, `:read` mode only, ignored in `:write` mode):
+    extends all live read locks of the lock (expired read locks are not revived);
+  - RBS: `read_write_mode` is typed as `:read | :write`;
+  - `#queue_info` / `#queues_info`: each lock request has `"rw_mode"` (`"write"` / `"read"`);
+  - `#lock_info` / `#locks_info`: write lock info has `"rw_mode" => "write"` (read locks info - `"rw_mode" => "read"`);
+  - `:meta`: `"rw_mode"` is a reserved lock data key (`RedisQueuedLocks::ArgumentError`), for write and read locks and lock series;
+  - **all processes should use the RQL version with read/write locks** before read locks are used
+    (write locks of older RQL versions do not check read locks);
+### Changed
+- `lock_series_obtained` instrumentation event (`#lock_series`, PoC): `:ts` is an epoch timestamp (`Float`)
+  like in all other instrumentation events (previously a `Time#to_s` string);
+- **Breaking**: `#extend_lock_ttl` success result is `{ ok: true, result: { extended_locks_count: Integer } }`
+  instead of `{ ok: true, result: :ttl_extended }` (the number of locks whose TTL is extended: `1` for the write lock
+  and for the own read lock, the number of extended read locks for `all_read_locks: true`);
+  the failure result is unchanged (`{ ok: false, result: :async_expire_or_no_lock }`);
+- Lock acquirement attempt: the lock state is fetched in one pipelined round trip; lock data for
+  `exit__no_first`/`exit__lock_still_obtained` try-lock logs is extracted only when these logs are enabled
+  (previously `HGETALL` was called on every unsuccessful attempt);
+### Fixed
+- `dequeue_from_lock_queue` log: unclosed quote in the `acs_strat` value;
+- `extendable_reentrant_lock_obtained` log: the host identifier is logged as `hst_id` (was `host_id`), like in all other logs;
+- `start_lock_series_obtaining` log: missing space between the `lock_keys` and `queue_ttl` values;
+- `lock_series` PoC:
+  - locks obtained by the failed series are released when the series fails without an exception
+    (`raise_errors: false`); previously they lived till their TTL;
+  - reentrant locks of the series (already obtained by the outer logic of the same acquirer) are not released
+    by the series anymore (previously the outer logic continued to work without its lock);
+  - the series releases only write locks that are still owned by the current acquirer (compare-and-delete):
+    a lock expired during the block and obtained by another acquirer is not deleted anymore;
+
 ## [1.17.0] - 2026-10-04
 ### Changed
 - [**Breaking**] Minimal Ruby Version - **4.0** (previously - **3.3**):

data/CLAUDE.md

@@ -12,7 +12,8 @@ Full details (config keys, key layout, events, errors, stack, CI): `.claude/proj
 - `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.
+- Locking: `ZADD NX` into the request queue, then WATCH/MULTI; Lua only for write TTL extension/decrease.
+- Read/Write locks (`read_write_mode: :write|:read`): write lock `rql:lock:<name>` + queue `rql:lock_queue:<name>`; readers registry `rql:lock_readers:<name>` (ZSET acq_id => Redis-time expiry), read queue `rql:lock_read_queue:<name>`, per-reader data `rql:lock_reader:<name>:<acq_id>`. Readers WATCH the write key only, writers WATCH the write key + registry; queues give ordering only. Details: overview "Read/Write locks".
 - 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.
@@ -20,12 +21,16 @@ Full details (config keys, key layout, events, errors, stack, CI): `.claude/proj
 - `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).
+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), `git.md` (commit messages and commit flow, always loaded).
 - 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.
+- Operation modules behind `Client` methods (all `Acquirer::*` except the `AcquireLock` acquisition core and PoC modules such as `LockSeriesPoC`, which may reuse other modules) are independent: they never call each other or reference each other's RBS types, share logic only via `Resource`/`Utilities`, and duplicate similar logic on purpose (independence over DRY; e.g. `Locks` duplicates the `LockInfo` formatting). Details: `acquirer.md`.
 - New option: `setting` (+ `validate`) in `config.rb`.
 - Dev gems go in `Gemfile`, not the gemspec.
+- Commits (`git.md`): subject only `[<scope>] <summary>` (several features: 1-2 words each, comma-separated), no body; when a step is complete (requirement fully implemented, specs/rubocop/steep green) ask before committing, with the proposed subject and a recap of the changes; an explicit "commit" request needs no extra question; never on `master`, never push.
+- Before implementing, read the relevant sections of `.claude/project-overview.md` (key layout, lock flow, "Read/Write locks", events) and keep their invariants. In the same change, update the overview and the affected `.claude/rules/*.md` for every new/changed key, option, result shape, event, algorithm step or limitation (and README/CHANGELOG `[Unreleased]` for user-visible behavior). New or changed log keys / instrumentation payload keys (visitors or inline `notify`) also go to README `## Logging` / `### Instrumentation Events` (see `visitors.md`).
+- Lock-touching code is read/write-aware: any operation over locks, queues, zombies or lock info must cover the read family (`rql:lock_readers:*`, `rql:lock_read_queue:*`, `rql:lock_reader:*`) next to `rql:lock:*`/`rql:lock_queue:*`. Mutual exclusion comes only from WATCH/MULTI on lock state (no Lua in the RW acquisition path unless asked); queues never guarantee safety.
 - Known debt: rspec-retry, disabled coverage minimum, runtime type-check CI uses `--failure-exit-code=0`.