redis_queued_locks 0.0.35 → 0.0.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e16184437150045fd98daf2ab2aaa328e0e7b0bae2a3bb513db25ea7eb535d6
-  data.tar.gz: 1965028261e953591dc707baea43801ed0ec506a85bd4de67c0a4e17cda52820
+  metadata.gz: e6417546d24eb5f2c7bbfffeebb506054fd96fc65ec0464ebbfdcf05db5b2972
+  data.tar.gz: e6ddf10eeb79dbdb9f2ed05480fa57423851cdd1ab9864a56b0d917c3c1aa533
 SHA512:
-  metadata.gz: e0cff23e13e47de8bd207597c65e0e036bbf971caad6dbd062628ca8e1975467d52834cc83787a5b4f41b3b88310eb88fe17aba93b2776687d0e5af9913d44b4
-  data.tar.gz: a963e804304ff4884669244f07a41061c7cc7ed56ad72f702bc41a42e7e4f8985d4f8b27d330a62afdce652123343cddae390a75d8bd8cdbab354ac54f4dd118
+  metadata.gz: ebeb82df02afcc0a9cc9838769a20e027ab54704bb91ab84942ba71b04175554888cbd9448abc2fb5abf5343a43dfb7905f0d1e831a5566614fd67b6a8f5391b
+  data.tar.gz: 9052a8ed7a3a056787184e100e06a98920f4d758e169515e47021b6fdafadf69056304e0177070bd050d9586bff990f2bae394d9a27490df9bd3fe949d509ea0

data/CHANGELOG.md

@@ -1,12 +1,25 @@
 ## [Unreleased]
 
+## [0.0.37] - 2024-03-28
+### Changed
+- `#queues_info`: `:contains` is renamed to `:reqeusts` in order to reflect it's domain area;
+
+## [0.0.36] - 2024-03-28
+### Added
+- Requirements:
+  - redis version: `>= 7.x`;
+  - redis protocol: `RESP3`;
+- Additional debugging methods:
+  - `#locks_info` (or `#locks(with_info: true)`) - get obtained locks with their info;
+  - `#queus_info` (or `#queues(with_info: true`) - get active lock queues with their info;
+
 ## [0.0.35] - 2024-03-26
 ### Changed
-- The random unique client instance identifier now uses 16-byte strings instead of 10-btes in order to prevent potential collisions;
+- The random unique client instance identifier now uses 16-byte strings instead of 10-bytes in order to prevent potential collisions;
 
 ## [0.0.34] - 2024-03-26
 ### Changed
-- Removing the acquirer from the request queue during a lock obtaining logic now using more proper and accurate `ZREM` instead of `ZPOPMIN` for this;
+- Removing the acquirer from the request queue during the lock obtaining logic is using more proper and accurate `ZREM` now instead of `ZPOPMIN`;
 
 ## [0.0.33] - 2024-03-26
 ### Added

data/README.md

@@ -10,6 +10,7 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 ## Table of Contents
 
+- [Requirements](#requirements)
 - [Algorithm](#algorithm)
 - [Installation](#installation)
 - [Setup](#setup)
@@ -27,6 +28,8 @@ Each lock request is put into the request queue (each lock is hosted by it's own
   - [locks](#locks---get-list-of-obtained-locks)
   - [queues](#queues---get-list-of-lock-request-queues)
   - [keys](#keys---get-list-of-taken-locks-and-queues)
+  - [locks_info](#locks_info---get-list-of-locks-with-their-info)
+  - [queues_info](#queues_info---get-list-of-queues-with-their-info)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
@@ -36,6 +39,13 @@ Each lock request is put into the request queue (each lock is hosted by it's own
 
 ---
 
+### Requirements
+
+- Redis Version: `~> 7.x`;
+- Redis Protocol: `RESP3`;
+
+---
+
 ### Algorithm
 
 > Each lock request is put into the request queue (each lock is hosted by it's 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.
@@ -135,6 +145,7 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   #   that have identical process_id/thread_id/fiber_id/ractor_id (identivcal acquier ids);
   # - it is calculated once per `RedisQueudLocks::Client` instance;
   # - expects the proc object;
+  # - `SecureRandom.hex(8)` by default;
   config.uniq_identifier = -> { RedisQueuedLocks::Resource.calc_uniq_identity }
 
   # (default: RedisQueuedLocks::Logging::VoidLogger)
@@ -181,6 +192,8 @@ end
 - [locks](#locks---get-list-of-obtained-locks)
 - [queues](#queues---get-list-of-lock-request-queues)
 - [keys](#keys---get-list-of-taken-locks-and-queues)
+- [locks_info](#locks_info---get-list-of-locks-with-their-info)
+- [queues_info](#queues_info---get-list-of-queues-with-their-info)
 
 ---
 
@@ -487,8 +500,12 @@ Return:
 #### #locks - get list of obtained locks
 
 - uses redis `SCAN` under the hood;
-- accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
-- returns `Set<String>`
+- accepts:
+  - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
+  - `:with_info` - `Boolean` - `false` by default (for details see [#locks_info](#locks_info---get-list-of-locks-with-their-info));
+- returns:
+  - `Set<String>` (for `with_info: false`);
+  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See `#locks_info` for details;
 
 ```ruby
 rql.locks # or rql.locks(scan_size: 123)
@@ -513,8 +530,12 @@ rql.locks # or rql.locks(scan_size: 123)
 #### #queues - get list of lock request queues
 
 - uses redis `SCAN` under the hood;
-- accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
-- returns `Set<String>`
+- accepts
+  - `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
+  - `:with_info` - `Boolean` - `false` by default (for details see [queues_info](#queues_info---get-list-of-queues-with-their-info));
+- returns:
+  - `Set<String>` (for `with_info: false`);
+  - `Set<Hash<Symbol,Any>>` (for `with_info: true`). See `#locks_info` for details;
 
 ```ruby
 rql.queues # or rql.queues(scan_size: 123)
@@ -539,8 +560,9 @@ rql.queues # or rql.queues(scan_size: 123)
 #### #keys - get list of taken locks and queues
 
 - uses redis `SCAN` under the hood;
-- accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
-- returns `Set<String>`
+- accepts:
+  `:scan_size` - `Integer` - (`config[:key_extraction_batch_size]` by default);
+- returns: `Set<String>`
 
 ```ruby
 rql.keys # or rql.keys(scan_size: 123)
@@ -566,6 +588,66 @@ rql.keys # or rql.keys(scan_size: 123)
 
 ---
 
+#### #locks_info - get list of locks with their info
+
+- uses redis `SCAN` under the hod;
+- accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
+- returns `Set<Hash<Symbol,Any>>` (see [#lock_info](#lock_info) and examples below for details).
+  - contained data: `{ lock: String, status: Symbol, info: Hash<String,Any> }`;
+  - `:lock` - `String` - lock key in Redis;
+  - `:status` - `Symbol`- `:released` or `:alive`
+    - the lock may become relased durign the lock info extraction process;
+    - `:info` for `:released` keys is empty (`{}`);
+  - `:info` - `Hash<String,Any>` - lock data stored in the lock key in Redis. See [#lock_info](#lock_info) for details;
+
+```ruby
+rql.locks_info # or rql.locks_info(scan_size: 123)
+
+# =>
+=> #<Set:
+ {{:lock=>"rql:lock:some-lock-123",
+   :status=>:alive,
+   :info=>{
+    "acq_id"=>"rql:acq:41478/4320/4340/4360/848818f09d8c3420",
+    "ts"=>1711607112.670343,
+    "ini_ttl"=>15000,
+    "rem_ttl"=>13998}},
+  {:lock=>"rql:lock:some-lock-456",
+   :status=>:released,
+   :info=>{},
+  ...}>
+```
+
+---
+
+#### #queues_info - get list of queues with their info
+
+- uses redis `SCAN` under the hod;
+- accepts `scan_size:`/`Integer` option (`config[:key_extraction_batch_size]` by default);
+- 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 acquier id and score.
+
+```ruby
+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},
+     {"acq_id"=>"rql:acq:38529/4580/4600/4360/66093702f24a3129", "score"=>1711606640.540906},
+     {"acq_id"=>"rql:acq:38529/4620/4640/4360/66093702f24a3129", "score"=>1711606640.5409632}]},
+  {:queue=>"rql:lock_queue:some-lock-456",
+   :requests=>
+    [{"acq_id"=>"rql:acq:38529/4380/4400/4360/66093702f24a3129", "score"=>1711606640.540722},
+     {"acq_id"=>"rql:acq:38529/4420/4440/4360/66093702f24a3129", "score"=>1711606640.5407748},
+     {"acq_id"=>"rql:acq:38529/4460/4480/4360/66093702f24a3129", "score"=>1711606640.540808}]},
+  ...}>
+```
+
+---
+
 ## Instrumentation
 
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).
@@ -604,7 +686,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ts` - `integer`/`epoch` - the time when the lock was obtaiend;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
-    - `:meta` - `nil`/`Any` - custom metadata passed to the `lock`/`lock!` method;
+    - `:instrument` - `nil`/`Any` - custom data passed to the `lock`/`lock!` method as `:instrument` attribute;
 - `"redis_queued_locks.lock_hold_and_release"`
   - an event signalizes about the "hold+and+release" process
     when the lock obtained and hold by the block of logic;
@@ -615,7 +697,7 @@ Detalized event semantics and payload structure:
     - `:lock_key` - `string` - lock name;
     - `:ts` - `integer`/`epoch` - the time when lock was obtained;
     - `:acq_time` - `float`/`milliseconds` - time spent on lock acquiring;
-    - `:meta` - `nil`/`Any` - custom metadata passed to the `lock`/`lock!` method;
+    - `:instrument` - `nil`/`Any` - custom data passed to the `lock`/`lock!` method as `:instrument` attribute;
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
   - payload:
@@ -647,8 +729,6 @@ Detalized event semantics and payload structure:
 - better code stylization and interesting refactorings;
 - dead queue keys cleanup (empty queues);
 - statistics with UI;
-- support for `Dragonfly` DB backend;
-- support for `Garnet` DB backend;
 
 ---
 

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

@@ -221,7 +221,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
               transact.call('ZREM', lock_key_queue, acquier_id)
 
               RedisQueuedLocks.debug(
-                'Step №4: Забираем наш текущий процесс из очереди. [ZPOPMIN]'
+                'Step №4: Забираем наш текущий процесс из очереди. [ZREM]'
               )
 
               # rubocop:disable Layout/LineLength
@@ -278,8 +278,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       #   => (!) analyze the command result and do actions with the depending on it;
       #   => (*) at this moment we accept that all comamnds are completed successfully;
       #   => (!) need to analyze:
-      #   1. zpopmin should return our process (array with <acq_id> and <score>)
-      #   2. hset should return 2 (lock key is added to the redis as a hashmap with 2 fields)
+      #   1. zrem shoud return ? (?)
+      #   2. hset should return 3 as minimum (lock key is added to the redis as a hashmap with 3 fields as minimum)
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.d: locked! :) let's go! => successfully acquired

data/lib/redis_queued_locks/acquier/locks.rb

@@ -3,14 +3,34 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::Locks
+  # @return [Hash]
+  #
+  # @api private
+  # @since 0.1.0
+  NO_LOCK_INFO = {}.freeze
+
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
+    # @option with_info [Boolean]
+    # @return [Set<String>,Set<Hash<Symbol,Any>>]
+    #
+    # @api private
+    # @since 0.1.0
+    def locks(redis_client, scan_size:, with_info:)
+      lock_keys = scan_locks(redis_client, scan_size)
+      with_info ? extract_locks_info(redis_client, lock_keys) : lock_keys
+    end
+
+    private
+
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
     # @return [Set<String>]
     #
     # @api private
     # @since 0.1.0
-    def locks(redis_client, scan_size:)
+    def scan_locks(redis_client, scan_size)
       Set.new.tap do |lock_keys|
         redis_client.scan(
           'MATCH',
@@ -22,5 +42,54 @@ module RedisQueuedLocks::Acquier::Locks
         end
       end
     end
+
+    # @param redis_client [RedisClient]
+    # @param lock_keys [Set<String>]
+    # @return [Set<Hash<Symbol,Any>>]
+    #
+    # @api private
+    # @since 0.1.0
+    # rubocop:disable Metrics/MethodLength
+    def extract_locks_info(redis_client, lock_keys)
+      # TODO: refactor with RedisQueuedLocks::Acquier::LockInfo
+      Set.new.tap do |seeded_locks|
+        # Step X: iterate each lock and extract their info
+        lock_keys.each do |lock_key|
+          # Step 1: extract lock info from redis
+          lock_info = redis_client.multi(watch: [lock_key]) do |transact|
+            transact.call('HGETALL', lock_key)
+            transact.call('PTTL', lock_key)
+          end.yield_self do |result| # Step 2: format the result
+            # Step 2.X: lock is released
+            if result == nil
+              {}
+            else
+              hget_cmd_res = result[0] # NOTE: HGETALL result (hash)
+              pttl_cmd_res = result[1] # NOTE: PTTL result (integer)
+
+              # Step 2.Y: lock is released
+              if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
+                {}
+              else
+                # Step 2.Z: lock is alive => format received info + add additional rem_ttl info
+                hget_cmd_res.tap do |lock_data|
+                  lock_data['ts'] = Float(lock_data['ts'])
+                  lock_data['ini_ttl'] = Integer(lock_data['ini_ttl'])
+                  lock_data['rem_ttl'] = ((pttl_cmd_res == -1) ? Infinity : pttl_cmd_res)
+                end
+              end
+            end
+          end
+
+          # Step 3: push the lock info to the result store
+          seeded_locks << {
+            lock: lock_key,
+            status: (lock_info.empty? ? :released : :alive),
+            info: lock_info
+          }
+        end
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/redis_queued_locks/acquier/queues.rb

@@ -4,13 +4,27 @@
 # @since 0.1.0
 module RedisQueuedLocks::Acquier::Queues
   class << self
+    # @param redis_client [RedisClient]
+    # @option scan_size [Integer]
+    # @option with_info [Boolean]
+    # @return [Set<String>,Set<Hash<Symbol,Any>>]
+    #
+    # @api private
+    # @since 0.1.0
+    def queues(redis_client, scan_size:, with_info:)
+      lock_queues = scan_queues(redis_client, scan_size)
+      with_info ? extract_queues_info(redis_client, lock_queues) : lock_queues
+    end
+
+    private
+
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
     # @return [Set<String>]
     #
     # @api private
     # @since 0.1.0
-    def queues(redis_client, scan_size:)
+    def scan_queues(redis_client, scan_size)
       Set.new.tap do |lock_queues|
         redis_client.scan(
           'MATCH',
@@ -22,5 +36,41 @@ module RedisQueuedLocks::Acquier::Queues
         end
       end
     end
+
+    # @param redis_client [RedisClient]
+    # @param lock_queus [Set<String>]
+    # @return [Set<Hash<Symbol,Any>>]
+    #
+    # @api private
+    # @since 0.1.0
+    def extract_queues_info(redis_client, lock_queues)
+      # TODO: refactor with RedisQueuedLocks::Acquier::QueueInfo
+      Set.new.tap do |seeded_queues|
+        # Step X: iterate over each lock queue and extract their info
+        lock_queues.each do |lock_queue|
+          # Step 1: extract lock queue info from reids
+          queue_info = redis_client.pipelined do |pipeline|
+            pipeline.call('EXISTS', lock_queue)
+            pipeline.call('ZRANGE', lock_queue, '0', '-1', 'WITHSCORES')
+          end.yield_self do |result| # Step 2: format the result
+            exists_cmd_res = result[0]
+            zrange_cmd_res = result[1]
+
+            if exists_cmd_res == 1 # Step 2.X: lock queue existed during the piepline invocation
+              zrange_cmd_res.map { |val| { 'acq_id' => val[0], 'score' => val[1] } }
+            else
+              # Step 2.Y: lock queue did not exist during the pipeline invocation
+              []
+            end
+          end
+
+          # Step 3: push the lock queue info to the result store
+          seeded_queues << {
+            queue: lock_queue,
+            requests: queue_info
+          }
+        end
+      end
+    end
   end
 end

data/lib/redis_queued_locks/client.rb

@@ -280,21 +280,68 @@ class RedisQueuedLocks::Client
   end
 
   # @option scan_size [Integer]
-  # @return [Set<String>]
+  #   The batch of scanned keys for Redis'es SCAN command.
+  # @option with_info [Boolean]
+  #   Extract lock info or not. If you want to extract a lock info too you have to consider
+  #   that during info extration the lock key may expire. The keys extraction (SCAN) without
+  #   any info extraction is doing first.
+  #   Possible options:
+  #   - `true` => returns a set of hashes that represents the lock state: <lock:, status:, info:>
+  #     - :lock (String) - the lock key in Redis database;
+  #     - :status (Symbol) - lock key state in redis. possible values:
+  #       - :released - the lock is expired/released during the info extraction;
+  #       - :alive - the lock still obtained;
+  #     - :info (Hash) - see #lock_info method for detals;
+  #   - `false` => returns a set of strings that represents an active locks
+  #     at the moment of Redis'es SCAN;
+  # @return [Set<String>,Set<Hash<Symbol,Any>>]
   #
   # @api public
   # @since 0.1.0
-  def locks(scan_size: config[:key_extraction_batch_size])
-    RedisQueuedLocks::Acquier::Locks.locks(redis_client, scan_size:)
+  def locks(scan_size: config[:key_extraction_batch_size], with_info: false)
+    RedisQueuedLocks::Acquier::Locks.locks(redis_client, scan_size:, with_info:)
   end
 
+  # Extracts lock keys with their info. See #locks(with_info: true) for details.
+  #
   # @option scan_size [Integer]
-  # @return [Set<String>]
+  # @return [Set<Hash<String,Any>>]
+  #
+  # @api public
+  # @since 0.1.0
+  def locks_info(scan_size: config[:key_extraction_batch_size])
+    locks(scan_size:, with_info: true)
+  end
+
+  # @option scan_size [Integer]
+  #   The batch of scanned keys for Redis'es SCAN command.
+  # @option with_info [Boolean]
+  #   Extract lock qeue info or not. If you want to extract a lock queue info too you have to
+  #   consider that during info extration the lock queue may become empty. The queue key extraction
+  #   (SCAN) without queue info extraction is doing first.
+  #   Possible options:
+  #   - `true` => returns a set of hashes that represents the queue state: <queue:, containing:>
+  #     - :queue (String) - the lock queue key in Redis database;
+  #     - :requests (Array<Hash<String,Any>>) - queue state in redis. see #queue_info for details;
+  #   - `false` => returns a set of strings that represents an active queues
+  #     at the moment of Redis'es SCAN;
+  # @return [Set<String>,String<Hash<Symbol,Any>>]
+  #
+  # @api public
+  # @since 0.1.0
+  def queues(scan_size: config[:key_extraction_batch_size], with_info: false)
+    RedisQueuedLocks::Acquier::Queues.queues(redis_client, scan_size:, with_info:)
+  end
+
+  # Extracts lock queues with their info. See #queues(with_info: true) for details.
+  #
+  # @option scan_size [Integer]
+  # @return [Set<Hash<Symbol,Any>>]
   #
   # @api public
   # @since 0.1.0
-  def queues(scan_size: config[:key_extraction_batch_size])
-    RedisQueuedLocks::Acquier::Queues.queues(redis_client, scan_size:)
+  def queues_info(scan_size: config[:key_extraction_batch_size])
+    queues(scan_size:, with_info: true)
   end
 
   # @option scan_size [Integer]

data/lib/redis_queued_locks/version.rb

@@ -5,6 +5,6 @@ module RedisQueuedLocks
   #
   # @api public
   # @since 0.0.1
-  # @version 0.0.35
-  VERSION = '0.0.35'
+  # @version 0.0.37
+  VERSION = '0.0.37'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.35
+  version: 0.0.37
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-26 00:00:00.000000000 Z
+date: 2024-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client