redis_queued_locks 1.18.0 → 1.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa1fdae0ce1bb54cce7b2f58a6ef0f172e56aca4d98c3a665b5789c04ca49b49
-  data.tar.gz: b39fac8b2a421081a7a7505401ea23e76485a348cf99dab799179fb3a6eefeac
+  metadata.gz: e33f744b3798258657c7b699b078ff4017f0d21341a1103437734a97cc5a46e8
+  data.tar.gz: dacf22eae42a663ddf9984da0cda311f3b44f06b4a9e22d015eedc941b77ddbb
 SHA512:
-  metadata.gz: a54e76f314b9187dc57fc7b60d7fdd2975b9a9b7010551c60dc37492f6f6804a9e5af2ae757a99d192fcbf94d3c948c881d9a922747951cc2897f980088d3858
-  data.tar.gz: 7a19035979ebe77171273bb7f514575a75244b02fe4c0cc94636f31e22ff93a9332c82014fe0b186df6e9e16ad42043ac8fcf6d5192cc7a6b78e682af5cafe22
+  metadata.gz: f7b7c4b1b38e633f7ee1fd3dbccd8846da716fa6756cf5a8279488cc75ebb93244adbccbd315844ad6a8590250450beb1487fd7b4b7d3c3441833a0f6d6b6d0f
+  data.tar.gz: 34189139e943bdae9e15d8642a8f2d504984547dd08a62efd92d27d786043e74808122c72dc24f25ccacc385862fe65e87249071f6e07e2925a72166ac3b2845

data/.claude/project-overview.md

@@ -49,7 +49,7 @@ duplicated on purpose (`Locks` duplicates the `LockInfo` write/read lock formatt
 | `lock` / `lock!` | `acquirer/acquire_lock.rb` + `acquirer/acquire_lock/*` |
 | `lock_series` / `lock_series!` | `acquirer/lock_series_poc.rb` (proof of concept; one `read_write_mode` for the whole series) |
 | `unlock` | `acquirer/release_lock.rb` |
-| `unlock_read` / `release_read_lock` | `acquirer/release_read_lock.rb` (own read lock only) |
+| `unlock_read` / `release_read_lock` | `acquirer/release_read_lock.rb` (own read lock or `acquirer_id:` read lock only) |
 | `extend_lock_ttl` | `acquirer/extend_lock_ttl.rb` (`read_write_mode: :read` extends own read lock, `+ all_read_locks: true` all live read locks) |
 | `locked?` / `queued?` | `acquirer/is_locked.rb` / `acquirer/is_queued.rb` |
 | `lock_info` / `queue_info` | `acquirer/lock_info.rb` / `acquirer/queue_info.rb` |
@@ -128,7 +128,8 @@ duplicated on purpose (`Locks` duplicates the `LockInfo` write/read lock formatt
   after the block and on any failure (exception or `raise_errors: false`), once per failed series.
 - Own read lock operations (current acquirer via `current_acquirer_id(identity:)`): `unlock_read` /
   `release_read_lock` (`ZREM` + `DEL` reader data, event `explicit_read_lock_release`, result
-  `{ rel_time:, rel_key:, rel_acq_id:, lock_res: }`) and `extend_lock_ttl(..., read_write_mode: :read)`
+  `{ rel_time:, rel_key:, rel_acq_id:, lock_res: }`; `acquirer_id:` (default `nil` => current acquirer;
+  when passed, `identity:` is ignored: the acquirer id already contains its identity) releases the read lock of a different acquirer) and `extend_lock_ttl(..., read_write_mode: :read)`
   (`multi(watch: [lock_key])`: extends only a live read lock while no write lock exists, never revives
   an expired one; registry and reader data TTLs via `PEXPIRE NX`+`GT`). `unlock` releases everything.
 - `extend_lock_ttl(..., read_write_mode: :read, all_read_locks: true)` (`false` by default, ignored for

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [1.19.0] - 2026-10-11
+### Added
+- `#unlock_read` (aka `#release_read_lock`): an ability to unlock the read lock of any acquirer
+  - `acquirer_id:` option (`nil` by default: the current acquirer) to release the read lock of a different acquirer
+    (`identity:` is ignored when `acquirer_id:` is passed: the acquirer id already contains its own identity);
+
 ## [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):

data/README.md

@@ -1094,6 +1094,64 @@ rql.lock_info("your_lock_name")
 }
 ```
 
+```ruby
+# <for read/write locks>
+# (see `read_write_mode:` kwarg attribute of #lock/#lock! methods and "Read/Write Locks" documentation section)
+# (lock requests are not included: use #queue_info to see the queued readers and writers)
+
+# -> case 1: the lock is held by readers, writers and readers are waiting in the lock queues;
+
+# process#1 and process#2 (readers, work in parallel):
+rql.lock("your_lock_name", read_write_mode: :read, ttl: 5_000, meta: { "kek" => "pek" }) { ... }
+rql.lock("your_lock_name", read_write_mode: :read, ttl: 3_000) { ... }
+# process#3 (writer, waits for all readers in the write lock queue):
+rql.lock("your_lock_name", read_write_mode: :write) { ... }
+# process#4 (reader, waits for the earlier writer in the read lock queue):
+rql.lock("your_lock_name", read_write_mode: :read) { ... }
+
+rql.lock_info("your_lock_name")
+
+# => (read locks info: process#1 and process#2)
+{
+  "lock_key" => "rql:lock:your_lock_name",
+  "rw_mode" => "read",
+  "rem_ttl" => 4_985, # remaining ttl of the longest read lock
+  "readers" => [
+    {
+      "acq_id" => "rql:acq:123/456/567/678/374dd74324",
+      "hst_id" => "rql:hst:123/456/678/374dd74324",
+      "ts" => 123456789.12345,
+      "ini_ttl" => 5_000,
+      "rem_ttl" => 4_985,
+      "kek" => "pek" # custom metadata of the read lock
+    },
+    {
+      "acq_id" => "rql:acq:124/457/568/679/a83cb4f9d1",
+      "hst_id" => "rql:hst:124/457/679/a83cb4f9d1",
+      "ts" => 123456789.54321,
+      "ini_ttl" => 3_000,
+      "rem_ttl" => 2_412
+    }
+  ]
+}
+
+# -> case 2: (some time later) readers are released, the lock is held by the writer (process#3),
+#    the reader (process#4) is still waiting in the read lock queue;
+
+rql.lock_info("your_lock_name")
+
+# => (write lock info: process#3, read lock requests are not included)
+{
+  "lock_key" => "rql:lock:your_lock_name",
+  "rw_mode" => "write",
+  "acq_id" => "rql:acq:125/458/569/680/c7bfcaf4f9",
+  "hst_id" => "rql:hst:125/458/680/c7bfcaf4f9",
+  "ts" => 123456795.12345,
+  "ini_ttl" => 5_000,
+  "rem_ttl" => 4_870
+}
+```
+
 ---
 
 #### #queue_info
@@ -1253,10 +1311,15 @@ rql.unlock("your_lock_name")
 - suitable for read locks obtained without a block of code (`lock(..., read_write_mode: :read)` without a block);
 - the current acquirer is calculated in the same way as for `#lock` (`#current_acquirer_id`: process, thread, fiber, ractor, identity),
   so call it from the same thread/fiber that obtained the read lock;
+- the read lock of a different acquirer can be released via `:acquirer_id` (for example, extracted from `#lock_info`/`#locks_info`);
+  `:identity` is ignored in this case (the acquirer id already contains its own identity);
 - has an alias: `#release_read_lock`;
 - accepts:
   - `lock_name` - (required) `[String]` - the lock name whose read lock should be released;
+  - `:acquirer_id` - (optional) `[String, NilClass]` - the acquirer whose read lock should be released
+    (`nil` by default: the current acquirer is used);
   - `:identity` - (optional) `[String]` - the same identity as for `#lock` (`uniq_identity` by default);
+    ignored when `:acquirer_id` is passed: the acquirer id already contains its own identity;
   - `:logger`, `:instrumenter`, `:instrument`, `:log_sampling_enabled`, `:log_sampling_percent`, `:log_sampler`, `:log_sample_this`,
     `:instr_sampling_enabled`, `:instr_sampling_percent`, `:instr_sampler`, `:instr_sample_this` - (optional) - the same as for `#unlock`;
 - returns `{ ok: true, result: { rel_time:, rel_key:, rel_acq_id:, lock_res: } }` (`lock_res` - `:released` or `:nothing_to_release`);
@@ -1278,6 +1341,22 @@ rql.unlock_read('report')
 }
 ```
 
+```ruby
+# release the read lock of a different acquirer
+reader = rql.lock_info('report')['readers'].first
+rql.unlock_read('report', acquirer_id: reader['acq_id'])
+# =>
+{
+  ok: true,
+  result: {
+    rel_time: 0.29, # milliseconds
+    rel_key: 'rql:lock:report',
+    rel_acq_id: 'rql:acq:17580/2260/2380/2280/3f16b93973612580', # reader['acq_id']
+    lock_res: :released # or :nothing_to_release
+  }
+}
+```
+
 ---
 
 #### #clear_locks - release all locks and lock queues
@@ -2237,8 +2316,8 @@ rql.lock('report') { rebuild_report } # (write mode is the default mode)
     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;
   - `#unlock` releases the lock entirely: the write lock, all read locks (with their data) and all lock requests;
-  - `#unlock_read` (aka `#release_read_lock`) releases the read lock of the current acquirer only
-    (suitable for read locks obtained without a block);
+  - `#unlock_read` (aka `#release_read_lock`) releases the read lock of the current acquirer
+    (suitable for read locks obtained without a block), or the read lock of the acquirer passed via `acquirer_id:`;
   - `#extend_lock_ttl(lock_name, milliseconds, read_write_mode: :read)` extends the read lock of the current acquirer only;
     `all_read_locks: true` extends all live read locks of the lock;
 - `#lock_series` with `read_write_mode: :read` obtains a series of read locks (the mode is the same for all locks of the series):

data/lib/redis_queued_locks/client.rb

@@ -677,14 +677,20 @@ class RedisQueuedLocks::Client
   end
   alias_method :release_lock, :unlock
 
-  # Releases the read lock of the current acquirer only: other read locks, the write lock and
-  # lock requests are not affected (`#unlock` releases the lock entirely). It is suitable for
-  # read locks obtained without a block of code.
+  # Releases the read lock of the current acquirer (or of the custom acquirer passed via
+  # `acquirer_id:`) only: other read locks, the write lock and lock requests are not affected
+  # (`#unlock` releases the lock entirely). It is suitable for read locks obtained without
+  # a block of code.
   #
   # @param lock_name [String] The lock name whose read lock should be released.
+  # @option acquirer_id [String,NilClass]
+  #   - The acquirer whose read lock should be released (`nil` by default);
+  #   - `nil` => the current acquirer is used (calculated from `identity:`, see `#current_acquirer_id`);
+  #   - can be extracted from the lock data (`#lock_info`, `#locks_info`, `#queue_info`, `#queues_info`);
   # @option identity [String]
   #   Unique acquirer identity (the same as for `#lock`) that is used to calculate the current
-  #   acquirer id (see `#current_acquirer_id`).
+  #   acquirer id (see `#current_acquirer_id`). Ignored when `acquirer_id:` is passed: the acquirer id
+  #   already contains its own identity.
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
@@ -707,10 +713,18 @@ class RedisQueuedLocks::Client
   #     }
   #   }
   #
+  # @example Release the read lock of the current acquirer:
+  #   client.unlock_read('report')
+  #
+  # @example Release the read lock of a different acquirer:
+  #   client.unlock_read('report', acquirer_id: "rql:acq:62681/2016/2024/2032/b30ec5e4bea10512")
+  #
   # @api public
   # @since 1.18.0
+  # @version 1.19.0
   def unlock_read(
     lock_name,
+    acquirer_id: nil,
     identity: uniq_identity,
     logger: config['logger'],
     instrumenter: config['instrumenter'],
@@ -727,7 +741,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseReadLock.release_read_lock(
       redis_client,
       lock_name,
-      current_acquirer_id(identity:),
+      acquirer_id || current_acquirer_id(identity:),
       instrumenter,
       logger,
       instrument,

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 1.17.0
-  VERSION = '1.18.0'
+  # @version 1.19.0
+  VERSION = '1.19.0'
 end

data/sig/redis_queued_locks/client.rbs

@@ -111,6 +111,7 @@ module RedisQueuedLocks
 
     def unlock_read: (
       String lock_name,
+      ?acquirer_id: String?,
       ?identity: String,
       ?logger: RQL::loggerObj,
       ?instrumenter: RQL::instrObj,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Rustam Ibragimov