redis_queued_locks 0.0.19 → 0.0.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c77f863ddb9f33c75a636ea12281ce1f4df1215d50f43b113b5be5f79b679526
-  data.tar.gz: 9585690846e55b141e089d26ac160f6481297cfa6f43d21df1403411903221be
+  metadata.gz: 2ea008491f8c631aea2677c6571a206db919c0ca5d599b58adc37fa82c372145
+  data.tar.gz: 41e5bece44a3b1af1031d28a4d7bfe480641151573b97c89d62841f296cbc3ca
 SHA512:
-  metadata.gz: 9e132a1464d92aa59539d5489d5b7d777399de6c38f313cbad063b819e0e32503591532eb010f5c6b87da41096172e9dde8f5fa2fc84623ca2256b84cd3fa98d
-  data.tar.gz: ea8dc9808a5c16697e5606ce8394c987ceb8df4f561fbf06250bd7669188665f56825a582e9c82240a52b6376767eedda9afeed588f960498fb32070466c512c
+  metadata.gz: cf96a4535a3fa8f6c7a62797805263e7957f198997213df65c164b9261d5199526f7dbc6e2a3f5e13a912e79cc7cd718ed193b0f197586cd03f1f3f95d958fca
+  data.tar.gz: 46726b0d18cd73d108b57b34872f1369ab63771a7d6c899aee021ab628ced537e6e0a7e255aecee259b902d682f5d13a12519dcc7033b786ef832c035a61f12a

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.0.21] - 2024-03-19
+### Changed
+- `RedisQueuedLocks::Acquier` refactirngs;
+
+## [0.0.20] - 2024-03-14
+### Added
+- An ability to provide custom metadata to `lock` and `lock!` methods that will be passed
+  to the instrumentation level inside the `payload` parameter with `:meta` key;
+
 ## [0.0.19] - 2024-03-12
 ### Added
 - An ability to set the invocation time period to the block of code invoked under

data/README.md

@@ -36,7 +36,9 @@ Each lock request is put into the request queue and processed in order of their
 
 ### Algorithm
 
-- soon
+> Each lock request is put into the request queue 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.
+
+**Soon**: detailed explanation.
 
 ---
 
@@ -174,6 +176,7 @@ def lock(
   raise_errors: false,
   fail_fast: false,
   identity: uniq_identity, # (attr_accessor) calculated during client instantiation via config[:uniq_identifier] proc;
+  metadata: nil,
   &block
 )
 ```
@@ -209,6 +212,8 @@ def lock(
     pods or/and nodes of your application;
   - It is calculated once during `RedisQueuedLock::Client` instantiation and stored in `@uniq_identity`
     ivar (accessed via `uniq_dentity` accessor method);
+- `metadata` - `[NilClass,Any]`
+  - A custom metadata wich will be passed to the instrumenter's payload with `:meta` key;
 - `block` - `[Block]`
   - A block of code that should be executed after the successfully acquired lock.
   - If block is **passed** the obtained lock will be released after the block execution or it's ttl (what will happen first);
@@ -262,6 +267,7 @@ def lock!(
   retry_jitter: config[:retry_jitter],
   identity: uniq_identity,
   fail_fast: false,
+  metadata: nil,
   &block
 )
 ```
@@ -536,6 +542,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;
 - `"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;
@@ -546,6 +553,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;
 - `"redis_queued_locks.explicit_lock_release"`
   - an event signalizes about the explicit lock release (invoked via `RedisQueuedLock#unlock`);
   - payload:
@@ -571,10 +579,13 @@ Detalized event semantics and payload structure:
     the acquired lock for long-running blocks of code (that invoked "under" the lock
     whose ttl may expire before the block execution completes);
   - an ability to add custom metadata to the lock and an ability to read this data;
+  - lock prioritization;
+  - support for LIFO strategy;
 - **Minor**
   - GitHub Actions CI;
   - `RedisQueuedLocks::Acquier::Try.try_to_lock` - detailed successful result analization;
   - better code stylization and interesting refactorings;
+  - lock queue expiration (dead queue cleanup);
 
 ---
 

data/lib/redis_queued_locks/acquier/{delay.rb → acquire_lock/delay_execution.rb}

@@ -2,8 +2,8 @@
 
 # @api private
 # @since 0.1.0
-module RedisQueuedLocks::Acquier::Delay
-  # Sleep with random time-shifting (it is necessary for empty-time-slot lock acquirement).
+module RedisQueuedLocks::Acquier::AcquireLock::DelayExecution
+  # Sleep with random time-shifting (it is necessary for empty lock-acquirement time slots).
   #
   # @param retry_delay [Integer] In milliseconds
   # @param retry_jitter [Integer] In milliseconds

data/lib/redis_queued_locks/acquier/{try.rb → acquire_lock/try_to_lock.rb}

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 0.1.0
-module RedisQueuedLocks::Acquier::Try
+module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param redis [RedisClient]
   # @param lock_key [String]
   # @param lock_key_queue [String]

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
+  # @param timeout [NilClass,Integer]
+  #   Time period after which the logic will fail with timeout error.
+  # @param lock_key [String]
+  #   Lock name.
+  # @param raise_errors [Boolean]
+  #   Raise erros on exceptional cases.
+  # @option on_timeout [Proc,NilClass]
+  #   Callback invoked on Timeout::Error.
+  # @return [Any]
+  #
+  # @api private
+  # @since 0.1.0
+  def with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
+    ::Timeout.timeout(timeout, &block)
+  rescue ::Timeout::Error
+    on_timeout.call unless on_timeout == nil
+
+    if raise_errors
+      raise(RedisQueuedLocks::LockAcquiermentTimeoutError, <<~ERROR_MESSAGE.strip)
+        Failed to acquire the lock "#{lock_key}" for the given timeout (#{timeout} seconds).
+      ERROR_MESSAGE
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/{yield_expire.rb → acquire_lock/yield_with_expire.rb}

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 0.1.0
-module RedisQueuedLocks::Acquier::YieldExpire
+module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
   # @param redis [RedisClient] Redis connection manager.
   # @param lock_key [String] Lock key to be expired.
   # @param timed [Boolean] Should the lock be wrapped by Tiemlout with with lock's ttl

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+# rubocop:disable Metrics/ModuleLength
+# rubocop:disable Metrics/MethodLength
+# rubocop:disable Metrics/ClassLength
+# rubocop:disable Metrics/BlockNesting
+module RedisQueuedLocks::Acquier::AcquireLock
+  require_relative 'acquire_lock/delay_execution'
+  require_relative 'acquire_lock/with_acq_timeout'
+  require_relative 'acquire_lock/yield_with_expire'
+  require_relative 'acquire_lock/try_to_lock'
+
+  # @since 0.1.0
+  extend TryToLock
+  # @since 0.1.0
+  extend DelayExecution
+  # @since 0.1.0
+  extend YieldWithExpire
+  # @since 0.1.0
+  extend WithAcqTimeout
+  # @since 0.1.0
+  extend RedisQueuedLocks::Utilities
+
+  # @return [Integer] Redis expiration error (in milliseconds).
+  #
+  # @api private
+  # @since 0.1.0
+  REDIS_EXPIRE_ERROR = 1
+
+  class << self
+    # @param redis [RedisClient]
+    #   Redis connection client.
+    # @param lock_name [String]
+    #   Lock name to be acquier.
+    # @option process_id [Integer,String]
+    #   The process that want to acquire a lock.
+    # @option thread_id [Integer,String]
+    #   The process's thread that want to acquire a lock.
+    # @option fiber_id [Integer,String]
+    #   A current fiber that want to acquire a lock.
+    # @option ractor_id [Integer,String]
+    #   The current ractor that want to acquire a lock.
+    # @option ttl [Integer,NilClass]
+    #   Lock's time to live (in milliseconds). Nil means "without timeout".
+    # @option queue_ttl [Integer]
+    #   Lifetime of the acuier's lock request. In seconds.
+    # @option timeout [Integer]
+    #   Time period whe should try to acquire the lock (in seconds).
+    # @option timed [Boolean]
+    #   Limit the invocation time period of the passed block of code by the lock's TTL.
+    # @option retry_count [Integer,NilClass]
+    #   How many times we should try to acquire a lock. Nil means "infinite retries".
+    # @option retry_delay [Integer]
+    #   A time-interval between the each retry (in milliseconds).
+    # @option retry_jitter [Integer]
+    #   Time-shift range for retry-delay (in milliseconds).
+    # @option raise_errors [Boolean]
+    #   Raise errors on exceptional cases.
+    # @option instrumenter [#notify]
+    #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
+    # @option identity [String]
+    #   Unique acquire identifier that is also should be unique between processes and pods
+    #   on different machines. By default the uniq identity string is
+    #   represented as 10 bytes hexstr.
+    # @option fail_fast [Boolean]
+    #   Should the required lock to be checked before the try and exit immidetly if lock is
+    #   already obtained.
+    # @option metadata [NilClass,Any]
+    #   - A custom metadata wich will be passed to the instrumenter's payload with :meta key;
+    # @param [Block]
+    #   A block of code that should be executed after the successfully acquired lock.
+    # @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.
+    #
+    # @api private
+    # @since 0.1.0
+    def acquire_lock(
+      redis,
+      lock_name,
+      process_id:,
+      thread_id:,
+      fiber_id:,
+      ractor_id:,
+      ttl:,
+      queue_ttl:,
+      timeout:,
+      timed:,
+      retry_count:,
+      retry_delay:,
+      retry_jitter:,
+      raise_errors:,
+      instrumenter:,
+      identity:,
+      fail_fast:,
+      metadata:,
+      &block
+    )
+      # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
+      acquier_id = RedisQueuedLocks::Resource.acquier_identifier(
+        process_id,
+        thread_id,
+        fiber_id,
+        ractor_id,
+        identity
+      )
+      # NOTE:
+      #   - think aobut the redis expiration error
+      #   - (ttl - REDIS_EXPIRE_ERROR).yield_self { |val| (val == 0) ? ttl : val }
+      lock_ttl = ttl
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+      acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
+
+      # Step X: intermediate result observer
+      acq_process = {
+        lock_info: {},
+        should_try: true,
+        tries: 0,
+        acquired: false,
+        result: nil,
+        acq_time: nil, # NOTE: in milliseconds
+        hold_time: nil, # NOTE: in milliseconds
+        rel_time: nil # NOTE: in milliseconds
+      }
+      acq_dequeue = -> { dequeue_from_lock_queue(redis, lock_key_queue, acquier_id) }
+
+      # Step 2: try to lock with timeout
+      with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: acq_dequeue) do
+        acq_start_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+
+        # Step 2.1: caclically try to obtain the lock
+        while acq_process[:should_try]
+          try_to_lock(
+            redis,
+            lock_key,
+            lock_key_queue,
+            acquier_id,
+            acquier_position,
+            lock_ttl,
+            queue_ttl,
+            fail_fast
+          ) => { ok:, result: }
+
+          acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          acq_time = ((acq_end_time - acq_start_time) * 1_000).ceil(2)
+
+          # Step X: save the intermediate results to the result observer
+          acq_process[:result] = result
+          acq_process[:acq_end_time] = acq_end_time
+
+          # Step 2.1: analyze an acquirement attempt
+          if ok
+            # Step X (instrumentation): lock obtained
+            instrumenter.notify('redis_queued_locks.lock_obtained', {
+              lock_key: result[:lock_key],
+              ttl: result[:ttl],
+              acq_id: result[:acq_id],
+              ts: result[:ts],
+              acq_time: acq_time,
+              meta: metadata
+            })
+
+            # Step 2.1.a: successfully acquired => build the result
+            acq_process[:lock_info] = {
+              lock_key: result[:lock_key],
+              acq_id: result[:acq_id],
+              ts: result[:ts],
+              ttl: result[:ttl]
+            }
+            acq_process[:acquired] = true
+            acq_process[:should_try] = false
+            acq_process[:acq_time] = acq_time
+            acq_process[:acq_end_time] = acq_end_time
+          elsif fail_fast && acq_process[:result] == :fail_fast_no_try
+            acq_process[:should_try] = false
+            if raise_errors
+              raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
+                Lock "#{lock_key}" is already obtained.
+              ERROR_MESSAGE
+            end
+          else
+            # Step 2.1.b: failed acquirement => retry
+            acq_process[:tries] += 1
+
+            if (retry_count != nil && acq_process[:tries] >= retry_count) || fail_fast
+              # NOTE:
+              #   - reached the retry limit => quit from the loop
+              #   - should fail fast => quit from the loop
+              acq_process[:should_try] = false
+              acq_process[:result] = fail_fast ? :fail_fast_after_try : :retry_limit_reached
+
+              # NOTE:
+              #   - reached the retry limit => dequeue from the lock queue
+              #   - should fail fast => dequeue from the lock queue
+              acq_dequeue.call
+
+              # NOTE: check and raise an error
+              if fail_fast && raise_errors
+                raise(RedisQueuedLocks::LockAlreadyObtainedError, <<~ERROR_MESSAGE.strip)
+                  Lock "#{lock_key}" is already obtained.
+                ERROR_MESSAGE
+              elsif raise_errors
+                raise(RedisQueuedLocks::LockAcquiermentRetryLimitError, <<~ERROR_MESSAGE.strip)
+                  Failed to acquire the lock "#{lock_key}"
+                  for the given retry_count limit (#{retry_count} times).
+                ERROR_MESSAGE
+              end
+            else
+              # NOTE:
+              #   delay the exceution in order to prevent chaotic attempts
+              #   and to allow other processes and threads to obtain the lock too.
+              delay_execution(retry_delay, retry_jitter)
+            end
+          end
+        end
+      end
+
+      # Step 3: analyze acquirement result
+      if acq_process[:acquired]
+        # Step 3.a: acquired successfully => run logic or return the result of acquirement
+        if block_given?
+          begin
+            yield_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            ttl_shift = ((yield_time - acq_process[:acq_end_time]) * 1000).ceil(2)
+            yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
+          ensure
+            acq_process[:rel_time] = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            acq_process[:hold_time] = (
+              (acq_process[:rel_time] - acq_process[:acq_end_time]) * 1000
+            ).ceil(2)
+
+            # Step X (instrumentation): lock_hold_and_release
+            run_non_critical do
+              instrumenter.notify('redis_queued_locks.lock_hold_and_release', {
+                hold_time: acq_process[:hold_time],
+                ttl: acq_process[:lock_info][:ttl],
+                acq_id: acq_process[:lock_info][:acq_id],
+                ts: acq_process[:lock_info][:ts],
+                lock_key: acq_process[:lock_info][:lock_key],
+                acq_time: acq_process[:acq_time],
+                meta: metadata
+              })
+            end
+          end
+        else
+          RedisQueuedLocks::Data[ok: true, result: acq_process[:lock_info]]
+        end
+      else
+        if acq_process[:result] != :retry_limit_reached &&
+           acq_process[:result] != :fail_fast_no_try &&
+           acq_process[:result] != :fail_fast_after_try
+          # NOTE: we have only two situations if lock is not acquired withou fast-fail flag:
+          #   - time limit is reached
+          #   - retry count limit is reached
+          #   In other cases the lock obtaining time and tries count are infinite.
+          acq_process[:result] = :timeout_reached
+        end
+        # Step 3.b: lock is not acquired (acquier is dequeued by timeout callback)
+        RedisQueuedLocks::Data[ok: false, result: acq_process[:result]]
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ModuleLength
+# rubocop:enable Metrics/MethodLength
+# rubocop:enable Metrics/ClassLength
+# rubocop:enable Metrics/BlockNesting

data/lib/redis_queued_locks/acquier/extend_lock_ttl.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::ExtendLockTTL
+  class << self
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @param milliseconds [Integer]
+    # @return [?]
+    #
+    # @api private
+    # @since 0.1.0
+    def extend_lock_ttl(redis_client, lock_name, milliseconds)
+      # TODO: realize
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/is_locked.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::IsLocked
+  class << self
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 0.1.0
+    def locked?(redis_client, lock_name)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      redis_client.call('EXISTS', lock_key) == 1
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/is_queued.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::IsQueued
+  class << self
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Boolean]
+    #
+    # @api private
+    # @since 0.1.0
+    def queued?(redis_client, lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+      redis_client.call('EXISTS', lock_key_queue) == 1
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/keys.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Keys
+  class << self
+    # @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
+  end
+end

data/lib/redis_queued_locks/acquier/lock_info.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::LockInfo
+  class << self
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Hash<Symbol,String|Numeric>,NilClass]
+    #   - `nil` is returned when lock key does not exist or expired;
+    #   - result format: {
+    #     lock_key: "rql:lock:your_lockname", # acquired lock key
+    #     acq_id: "rql:acq:process_id/thread_id", # lock acquier identifier
+    #     ts: 123456789, # <locked at> time stamp (epoch)
+    #     ini_ttl: 123456789, # initial lock key ttl (milliseconds),
+    #     rem_ttl: 123456789, # remaining lock key ttl (milliseconds)
+    #   }
+    #
+    # @api private
+    # @since 0.1.0
+    def lock_info(redis_client, lock_name)
+      lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+
+      result = redis_client.multi(watch: [lock_key]) do |transact|
+        transact.call('HGETALL', lock_key)
+        transact.call('PTTL', lock_key)
+      end
+
+      if result == nil
+        # NOTE:
+        #   - nil result means that during transaction invocation the lock is changed (CAS):
+        #     - lock is expired;
+        #     - lock is released;
+        #     - lock is expired + re-obtained;
+        nil
+      else
+        hget_cmd_res = result[0]
+        pttl_cmd_res = result[1]
+
+        if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
+          nil
+        else
+          # NOTE: the result of MULTI-command is an array of results of each internal command
+          #   - result[0] (HGETALL) (Hash<String,String>)
+          #   - result[1] (PTTL) (Integer)
+          {
+            lock_key: lock_key,
+            acq_id: hget_cmd_res['acq_id'],
+            ts: Integer(hget_cmd_res['ts']),
+            ini_ttl: Integer(hget_cmd_res['ini_ttl']),
+            rem_ttl: ((pttl_cmd_res == -1) ? Infinity : pttl_cmd_res)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/locks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Locks
+  class << self
+    # @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
+  end
+end

data/lib/redis_queued_locks/acquier/queue_info.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::QueueInfo
+  class << self
+    # Returns an information about the required lock queue by the lock name. The result
+    # represnts the ordered lock request queue that is ordered by score (Redis sets) and shows
+    # lock acquirers and their position in queue. Async nature with redis communcation can lead
+    # the sitaution when the queue becomes empty during the queue data extraction. So sometimes
+    # you can receive the lock queue info with empty queue.
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_name [String]
+    # @return [Hash<Symbol,String|Array<Hash<Symbol,String|Float>>,NilClass]
+    #   - `nil` is returned when lock queue does not exist;
+    #   - result format: {
+    #     lock_queue: "rql:lock_queue:your_lock_name", # lock queue key in redis,
+    #     queue: [
+    #       { acq_id: "rql:acq:process_id/thread_id", score: 123 },
+    #       { acq_id: "rql:acq:process_id/thread_id", score: 456 },
+    #     ] # ordered set (by score) with information about an acquier and their position in queue
+    #   }
+    #
+    # @api private
+    # @since 0.1.0
+    def queue_info(redis_client, lock_name)
+      lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+
+      result = redis_client.pipelined do |pipeline|
+        pipeline.call('EXISTS', lock_key_queue)
+        pipeline.call('ZRANGE', lock_key_queue, '0', '-1', 'WITHSCORES')
+      end
+
+      exists_cmd_res = result[0]
+      zrange_cmd_res = result[1]
+
+      if exists_cmd_res == 1
+        # NOTE: queue existed during the piepline invocation
+        {
+          lock_queue: lock_key_queue,
+          queue: zrange_cmd_res.map { |val| { acq_id: val[0], score: val[1] } }
+        }
+      else
+        # NOTE: queue did not exist during the pipeline invocation
+        nil
+      end
+    end
+  end
+end

data/lib/redis_queued_locks/acquier/queues.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 0.1.0
+module RedisQueuedLocks::Acquier::Queues
+  class << self
+    # @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
+  end
+end