redis_queued_locks 0.0.16 → 0.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 524740cce42224df4610bce35ced68e38f0fceb13ba233fe9c2f4ceac76fa49a
-  data.tar.gz: f3cb8b791292ba1c98b9b97c2a23b413edf74a3a5a25cebba5c7e3900f5705fd
+  metadata.gz: '0993079d1a7cca97094c741d65c4ef1e8a5694184212b6597960e0b3c91d83cb'
+  data.tar.gz: 22535e254fa22db6bfb0225f391e3d4606ad680bb401034fcbdfcd8e93a1fc5c
 SHA512:
-  metadata.gz: 732ffd5fe549d093f8bc4ef6edd1db9751aa951b0cd0f75d3ba63b8facc7a5bea1d31c88527ae2ae1c3bd4bfc5e686a447ab3907d18f37c1756167d306c929aa
-  data.tar.gz: f6b95308ec0653068de4816ce47a45f2470000079d468a54950f4a4bfc10c2689778108a265d3be097811d0da31b16678d14aa284903066e9c889201cc412abb
+  metadata.gz: 7db77251aefc59a83a9727d756774f5eb6b30a156fd058d69ec5170d252cc8fb875b2f213da2e15a4bdf9f5565565aa5ca699545ac0a83dcbc333fbed8c7aec1
+  data.tar.gz: 659c47a6aaa421ade9c7ffaea000a7133c1ba72f5ab0a2e66bc56f5ad72f84f4d9525fc86024e5d52b8196a6dfc7b0a714100462915a91405c97c3b3d77d3e26

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.0.18] - 2024-03-04
+### Changed
+- Semantic results for methods returning `{ ok: true/false, result: Any }` hash objects.
+  Now these objects are represented as `RedisQueuedLocks::Data` objects inherited from `Hash`;
+
+## [0.0.17] - 2024-02-29
+### Added
+- `RedisQueuedLocks::Client#locks` - list of obtained locks;
+- `RedisQueuedLocks::Client#queues` - list of existing lock request queus;
+- `RedisQueuedLocks::Client#keys` - get list of taken locks and queues;
+
 ## [0.0.16] - 2024-02-29
 ### Fixed
 - Execution delay formula returns the value "in seconds" (should be "in milliseconds");

data/README.md

@@ -1,4 +1,4 @@
-# RedisQueuedLocks · [![Gem Version](https://badge.fury.io/rb/redis_queued_locks.svg)](https://badge.fury.io/rb/redis_queued_locks)
+# RedisQueuedLocks
 
 Distributed locks with "lock acquisition queue" capabilities based on the Redis Database.
 
@@ -21,6 +21,10 @@ Each lock request is put into the request queue and processed in order of their
   - [queued?](#queued)
   - [unlock](#unlock---release-a-lock)
   - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+  - [extend_lock_ttl](#extend_lock_ttl)
+  - [locks](#locks---get-list-of-obtained-locks)
+  - [queues](#queues---get-list-of-lock-request-queues)
+  - [keys](#keys---get-list-of-taken-locks-and-queues)
 - [Instrumentation](#instrumentation)
   - [Instrumentation Events](#instrumentation-events)
 - [Roadmap](#roadmap)
@@ -104,10 +108,15 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   config.default_queue_ttl = 15
 
   # (default: 100)
-  # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic;
-  # - affects the performancs capabilites (redis, rubyvm);
+  # - how many items will be released at a time in RedisQueuedLocks::Client#clear_locks logic (uses SCAN);
+  # - affects the performancs of your Redis and Ruby Application (configure thoughtfully);
   config.lock_release_batch_size = 100
 
+  # (default: 500)
+  # - how many items should be extracted from redis during the #locks, #queues and #keys operations (uses SCAN);
+  # - affects the performance of your Redis and Ruby Application (configure thoughtfully;)
+  config.key_extraction_batch_size = 500
+
   # (default: RedisQueuedLocks::Instrument::VoidNotifier)
   # - instrumentation layer;
   # - you can provde your own instrumenter with `#notify(event, payload = {})`
@@ -138,6 +147,10 @@ end
 - [queued?](#queued)
 - [unlock](#unlock---release-a-lock)
 - [clear_locks](#clear_locks---release-all-locks-and-lock-queues)
+- [extend_lock_ttl](#extend_lock_ttl)
+- [locks](#locks---get-list-of-obtained-locks)
+- [queues](#queues---get-list-of-lock-request-queues)
+- [keys](#keys---get-list-of-taken-locks-and-queues)
 
 ---
 
@@ -231,6 +244,7 @@ Return value:
 #### #lock! - exceptional lock obtaining
 
 - fails when (and with):
+  - (`RedisQueuedLocks::LockAlreadyObtainedError`) when `fail_fast` is `true` and lock is already obtained;
   - (`RedisQueuedLocks::LockAcquiermentTimeoutError`) `timeout` limit reached before lock is obtained;
   - (`RedisQueuedLocks::LockAcquiermentRetryLimitError`) `retry_count` limit reached before lock is obtained;
 
@@ -393,6 +407,94 @@ Return:
 
 ---
 
+#### #extend_lock_ttl
+
+- soon
+
+---
+
+#### #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>`
+
+```ruby
+rql.locks # or rql.locks(scan_size: 123)
+
+=>
+#<Set:
+ {"rql:lock:locklock75",
+  "rql:lock:locklock9",
+  "rql:lock:locklock108",
+  "rql:lock:locklock7",
+  "rql:lock:locklock48",
+  "rql:lock:locklock104",
+  "rql:lock:locklock13",
+  "rql:lock:locklock62",
+  "rql:lock:locklock80",
+  "rql:lock:locklock28",
+  ...}>
+```
+
+---
+
+#### #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>`
+
+```ruby
+rql.queues # or rql.queues(scan_size: 123)
+
+=>
+#<Set:
+ {"rql:lock_queue:locklock75",
+  "rql:lock_queue:locklock9",
+  "rql:lock_queue:locklock108",
+  "rql:lock_queue:locklock7",
+  "rql:lock_queue:locklock48",
+  "rql:lock_queue:locklock104",
+  "rql:lock_queue:locklock13",
+  "rql:lock_queue:locklock62",
+  "rql:lock_queue:locklock80",
+  "rql:lock_queue:locklock28",
+  ...}>
+```
+
+---
+
+#### #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>`
+
+```ruby
+rql.keys # or rql.keys(scan_size: 123)
+
+=>
+#<Set:
+ {"rql:lock_queue:locklock75",
+  "rql:lock_queue:locklock9",
+  "rql:lock:locklock9",
+  "rql:lock_queue:locklock108",
+  "rql:lock_queue:locklock7",
+  "rql:lock:locklock7",
+  "rql:lock_queue:locklock48",
+  "rql:lock_queue:locklock104",
+  "rql:lock:locklock104",
+  "rql:lock_queue:locklock13",
+  "rql:lock_queue:locklock62",
+  "rql:lock_queue:locklock80",
+  "rql:lock:locklock80",
+  "rql:lock_queue:locklock28",
+  ...}>
+```
+
+---
+
 ## Instrumentation
 
 An instrumentation layer is incapsulated in `instrumenter` object stored in [config](#configuration) (`RedisQueuedLocks::Client#config[:instrumenter]`).

data/lib/redis_queued_locks/acquier/release.rb

@@ -8,7 +8,7 @@ module RedisQueuedLocks::Acquier::Release
   # @param redis [RedisClient]
   # @param lock_key [String]
   # @param lock_key_queue [String]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
@@ -18,14 +18,14 @@ module RedisQueuedLocks::Acquier::Release
       transact.call('EXPIRE', lock_key, '0')
     end
 
-    { ok: true, result: }
+    RedisQueuedLocks::Data[ok: true, result:]
   end
 
   # Release all locks: clear all lock queus and expire all locks.
   #
   # @param redis [RedisClient]
   # @param batch_size [Integer]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
   # @since 0.1.0
@@ -37,6 +37,7 @@ module RedisQueuedLocks::Acquier::Release
         RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
         count: batch_size
       ) do |lock_queue|
+        # TODO: reduce unnecessary iterations
         pipeline.call('ZREMRANGEBYSCORE', lock_queue, '-inf', '+inf')
         pipeline.call('EXPIRE', RedisQueuedLocks::Resource.lock_key_from_queue(lock_queue), '0')
       end
@@ -47,12 +48,13 @@ module RedisQueuedLocks::Acquier::Release
         RedisQueuedLocks::Resource::LOCK_PATTERN,
         count: batch_size
       ) do |lock_key|
+        # TODO: reduce unnecessary iterations
         pipeline.call('EXPIRE', lock_key, '0')
       end
     end
 
     rel_keys = result.count { |red_res| red_res == 0 }
 
-    { ok: true, result: { rel_keys: rel_keys } }
+    RedisQueuedLocks::Data[ok: true, result: { rel_keys: rel_keys }]
   end
 end

data/lib/redis_queued_locks/acquier/try.rb

@@ -130,13 +130,13 @@ module RedisQueuedLocks::Acquier::Try
     case
     when fail_fast && inter_result == :fail_fast_no_try
       # Step 7.a: lock is still acquired and we should exit from the logic as soon as possible
-      { ok: false, result: inter_result }
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     when inter_result == :lock_is_still_acquired || inter_result == :acquier_is_not_first_in_queue
       # Step 7.b: lock is still acquired by another process => failed to acquire
-      { ok: false, result: inter_result }
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     when result == nil || (result.is_a?(::Array) && result.empty?)
       # Step 7.c: lock is already acquired durign the acquire race => failed to acquire
-      { ok: false, result: :lock_is_acquired_during_acquire_race }
+      RedisQueuedLocks::Data[ok: false, result: :lock_is_acquired_during_acquire_race]
     when result.is_a?(::Array) && result.size == 3 # NOTE: 3 is a count of redis lock commands
       # TODO:
       #   => (!) analyze the command result and do actions with the depending on it;
@@ -147,10 +147,13 @@ module RedisQueuedLocks::Acquier::Try
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.d: locked! :) let's go! => successfully acquired
-      { ok: true, result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl }
+      ]
     else
       # Ste 7.3: unknown behaviour :thinking:
-      { ok: false, result: :unknown }
+      RedisQueuedLocks::Data[ok: false, result: :unknown]
     end
     # rubocop:enable Lint/DuplicateBranch
   end
@@ -170,6 +173,6 @@ module RedisQueuedLocks::Acquier::Try
       "Step ~ [СМЕРТЬ ПРОЦЕССА]: [#{acquier_id} :: #{lock_key_queue}] РЕЗУЛЬТАТ: #{result}"
     )
 
-    { ok: true, result: result }
+    RedisQueuedLocks::Data[ok: true, result: result]
   end
 end

data/lib/redis_queued_locks/acquier.rb

@@ -63,7 +63,7 @@ module RedisQueuedLocks::Acquier
     #   already obtained.
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
-    # @return [Hash<Symbol,Any>,yield]
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
     #  - Format: { ok: true/false, result: Any }
     #  - If block is given the result of block's yeld will be returned.
     #
@@ -232,7 +232,7 @@ module RedisQueuedLocks::Acquier
             end
           end
         else
-          { ok: true, result: acq_process[:lock_info] }
+          RedisQueuedLocks::Data[ok: true, result: acq_process[:lock_info]]
         end
       else
         if acq_process[:result] != :retry_limit_reached &&
@@ -245,7 +245,7 @@ module RedisQueuedLocks::Acquier
           acq_process[:result] = :timeout_reached
         end
         # Step 3.b: lock is not acquired (acquier is dequeued by timeout callback)
-        { ok: false, result: acq_process[:result] }
+        RedisQueuedLocks::Data[ok: false, result: acq_process[:result]]
       end
     end
     # rubocop:enable Metrics/MethodLength, Metrics/BlockNesting
@@ -257,10 +257,14 @@ module RedisQueuedLocks::Acquier
     # It is safe because the lock obtain logic is transactional and
     # watches the original lock for changes.
     #
-    # @param redis [RedisClient] Redis connection client.
-    # @param lock_name [String] The lock name that should be released.
-    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param lock_name [String]
+    #   The lock name that should be released.
+    # @param isntrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+    #   Format: { ok: true/false, result: Hash<Symbil,Numeric|String> }
     #
     # @api private
     # @since 0.1.0
@@ -283,17 +287,24 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { rel_time: rel_time, rel_key: lock_key, rel_queue: lock_key_queue }
+      ]
     end
 
     # Release all locks:
     # - 1. clear all lock queus: drop them all from Redis database by the lock queue pattern;
     # - 2. delete all locks: drop lock keys from Redis by the lock key pattern;
     #
-    # @param redis [RedisClient] Redis connection client.
-    # @param batch_size [Integer] The number of lock keys that should be released in a time.
-    # @param isntrumenter [#notify] See RedisQueuedLocks::Instrument::ActiveSupport for example.
-    # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Hash<Symbol,Numeric> }
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param batch_size [Integer]
+    #   The number of lock keys that should be released in a time.
+    # @param isntrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+    #   Format: { ok: true/false, result: Hash<Symbol,Numeric> }
     #
     # @api private
     # @since 0.1.0
@@ -312,7 +323,10 @@ module RedisQueuedLocks::Acquier
         })
       end
 
-      { ok: true, result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time } }
+      RedisQueuedLocks::Data[
+        ok: true,
+        result: { rel_key_cnt: result[:rel_keys], rel_time: rel_time }
+      ]
     end
 
     # @param redis_client [RedisClient]
@@ -437,7 +451,66 @@ module RedisQueuedLocks::Acquier
     #
     # @api private
     # @since 0.1.0
-    def extend_lock_ttl(redis_client, lock_name, milliseconds); end
+    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+      # TODO: realize
+    end
+
+    # @param redis_client [RedisClient]
+    # @option scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 0.1.0
+    def locks(redis_client, scan_size:)
+      Set.new.tap do |lock_keys|
+        redis_client.scan(
+          'MATCH',
+          RedisQueuedLocks::Resource::LOCK_PATTERN,
+          count: scan_size
+        ) do |lock_key|
+          # TODO: reduce unnecessary iterations
+          lock_keys.add(lock_key)
+        end
+      end
+    end
+
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 0.1.0
+    def queues(redis_client, scan_size:)
+      Set.new.tap do |lock_queues|
+        redis_client.scan(
+          'MATCH',
+          RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+          count: scan_size
+        ) do |lock_queue|
+          # TODO: reduce unnecessary iterations
+          lock_queues.add(lock_queue)
+        end
+      end
+    end
+
+    # @param redis_client [RedisClient]
+    # @option scan_size [Integer]
+    # @return [Array<String>]
+    #
+    # @api private
+    # @since 0.1.0
+    def keys(redis_client, scan_size:)
+      Set.new.tap do |keys|
+        redis_client.scan(
+          'MATCH',
+          RedisQueuedLocks::Resource::KEY_PATTERN,
+          count: scan_size
+        ) do |key|
+          # TODO: reduce unnecessary iterations
+          keys.add(key)
+        end
+      end
+    end
 
     private
 

data/lib/redis_queued_locks/client.rb

@@ -15,6 +15,7 @@ class RedisQueuedLocks::Client
     setting :default_lock_ttl, 5_000 # NOTE: milliseconds
     setting :default_queue_ttl, 15 # NOTE: seconds
     setting :lock_release_batch_size, 100
+    setting :key_extraction_batch_size, 500
     setting :instrumenter, RedisQueuedLocks::Instrument::VoidNotifier
     setting :uniq_identifier, -> { RedisQueuedLocks::Resource.calc_uniq_identity }
 
@@ -91,7 +92,7 @@ class RedisQueuedLocks::Client
   #   by another process while the lock request queue was initially empty;
   # @param block [Block]
   #   A block of code that should be executed after the successfully acquired lock.
-  # @return [Hash<Symbol,Any>,yield]
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
   #   - Format: { ok: true/false, result: Symbol/Hash }.
   #   - If block is given the result of block's yeld will be returned.
   #
@@ -162,8 +163,10 @@ class RedisQueuedLocks::Client
     )
   end
 
-  # @param lock_name [String] The lock name that should be released.
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
+  # @param lock_name [String]
+  #   The lock name that should be released.
+  # @return [RedisQueuedLocks::Data, Hash<Symbol,Any>]
+  #   Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
@@ -218,12 +221,40 @@ class RedisQueuedLocks::Client
   end
 
   # @option batch_size [Integer]
-  # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol/Hash }.
+  # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>]
+  #   Format: { ok: true/false, result: Symbol/Hash }.
   #
   # @api public
   # @since 0.1.0
   def clear_locks(batch_size: config[:lock_release_batch_size])
     RedisQueuedLocks::Acquier.release_all_locks!(redis_client, batch_size, config[:instrumenter])
   end
+
+  # @option scan_size [Integer]
+  # @return [Set<String>]
+  #
+  # @api public
+  # @since 0.1.0
+  def locks(scan_size: config[:key_extraction_batch_size])
+    RedisQueuedLocks::Acquier.locks(redis_client, scan_size:)
+  end
+
+  # @option scan_size [Integer]
+  # @return [Set<String>]
+  #
+  # @api public
+  # @since 0.1.0
+  def queues(scan_size: config[:key_extraction_batch_size])
+    RedisQueuedLocks::Acquier.queues(redis_client, scan_size:)
+  end
+
+  # @option scan_size [Integer]
+  # @return [Set<String>]
+  #
+  # @api public
+  # @since 0.1.0
+  def keys(scan_size: config[:key_extraction_batch_size])
+    RedisQueuedLocks::Acquier.keys(redis_client, scan_size:)
+  end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/data.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# NOTE: wiill be rewritten with Ruby's 3.2 "Data" class;
+class RedisQueuedLocks::Data < Hash
+end

data/lib/redis_queued_locks/resource.rb

@@ -3,6 +3,12 @@
 # @api private
 # @since 0.1.0
 module RedisQueuedLocks::Resource
+  # @return [String]
+  #
+  # @api private
+  # @since 0.1.0
+  KEY_PATTERN = 'rql:lock*'
+
   # @return [String]
   #
   # @api private

data/lib/redis_queued_locks/version.rb

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

data/lib/redis_queued_locks.rb

@@ -10,6 +10,7 @@ require 'securerandom'
 module RedisQueuedLocks
   require_relative 'redis_queued_locks/version'
   require_relative 'redis_queued_locks/errors'
+  require_relative 'redis_queued_locks/data'
   require_relative 'redis_queued_locks/debugger'
   require_relative 'redis_queued_locks/resource'
   require_relative 'redis_queued_locks/acquier'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 0.0.16
+  version: 0.0.18
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-02-29 00:00:00.000000000 Z
+date: 2024-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -61,6 +61,7 @@ files:
 - lib/redis_queued_locks/acquier/release.rb
 - lib/redis_queued_locks/acquier/try.rb
 - lib/redis_queued_locks/client.rb
+- lib/redis_queued_locks/data.rb
 - lib/redis_queued_locks/debugger.rb
 - lib/redis_queued_locks/debugger/interface.rb
 - lib/redis_queued_locks/errors.rb