redis_queued_locks 0.0.20 → 0.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 281c476c0b1318a3f061e0d22031de92983f4ebd2277bc7e024b2baf998ae559
-  data.tar.gz: 5547ace054290da08fb1eb26e965e2d0ff68dfc9b5c3df0adb8a77069543b8ef
+  metadata.gz: 4360a9af038cc33ca36215d729558bab6810b9c5a4fec7f31df6ca2871b7dd80
+  data.tar.gz: 10b80a0f389994fde9a4815c3a5031ae85cee3c61d9c2a02e85d80146208bb99
 SHA512:
-  metadata.gz: a971c732be6ef918ae6e9fc70e4456a076b36a50622cda4e0f2b4d5d3f0cb9479e768852e391b02a6420d3de682ccca7de374cf1410b25be37a5d8cf43a4865c
-  data.tar.gz: ef66b70b7ef28be2b9b2422a94dc89e2fff350ad5d8ce58806f28c7742fa4a3caa5032f64d4817abd52dc4bc2ae77327dcfee79b28f462241c63fb2ddaf992eb
+  metadata.gz: 362e7708a37f8716217e08117f072ef34d14886677379d28bef08f80c1a1a82e1309509dfc5fe4f748a3a10268bf340087c83e797ebcd72cb8172594352fb23d
+  data.tar.gz: 32a0943ee8c80b8ed745dff8eeea748c2289008d8fb00d3e20c7b464ef14a4d21158066e548bb86cfebc73c5d61a365289b49ae8061bc3ea0339ad7bb3c9894d

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [0.0.22] - 2024-03-21
+### Added
+- Logging infrastructure. Initial implementation includes the only debugging features.
+
+## [0.0.21] - 2024-03-19
+### Changed
+- Refactored `RedisQueuedLocks::Acquier`;
+
 ## [0.0.20] - 2024-03-14
 ### Added
 - An ability to provide custom metadata to `lock` and `lock!` methods that will be passed

data/README.md

@@ -134,6 +134,16 @@ clinet = RedisQueuedLocks::Client.new(redis_client) do |config|
   # - it is calculated once per `RedisQueudLocks::Client` instance;
   # - expects the proc object;
   config.uniq_identifier = -> { RedisQueuedLocks::Resource.calc_uniq_identity }
+
+  # (default: RedisQueuedLocks::Logging::VoidLogger)
+  # - the logger object;
+  # - should implement `debug(progname = nil, &block)` (minimal requirement) or be an instance of Ruby's `::Logger` class/subclass;
+  # - at this moment the only debug logs are realised in 3 cases:
+  #   - start of lock obtaining: "[redis_queud_locks.start_lock_obtaining] lock_key => 'rql:lock:your_lock'"
+  #   - finish of the lock obtaining: "[redis_queued_locks.lock_obtained] lock_key => 'rql:lock:your_lock' acq_time => 123.456 (ms)"
+  #   - start of the lock expiration after `yield`: "[redis_queud_locks.expire_lock] lock_key => 'rql:lock:your_lock'"
+  # - by default uses VoidLogger that does nothing;
+  config.logger = RedisQueuedLocks::Logging::VoidLogger
 end
 ```
 
@@ -213,7 +223,7 @@ def lock(
   - 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;
+  - 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);
@@ -580,10 +590,13 @@ Detalized event semantics and payload structure:
     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;
+  - structured logging;
 - **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,8 +2,12 @@
 
 # @api private
 # @since 0.1.0
-module RedisQueuedLocks::Acquier::YieldExpire
+module RedisQueuedLocks::Acquier::AcquireLock::YieldWithExpire
+  # @since 0.1.0
+  extend RedisQueuedLocks::Utilities
+
   # @param redis [RedisClient] Redis connection manager.
+  # @param logger [#debug] Logger object.
   # @param lock_key [String] Lock key to be expired.
   # @param timed [Boolean] Should the lock be wrapped by Tiemlout with with lock's ttl
   # @param ttl_shift [Float] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
@@ -13,7 +17,7 @@ module RedisQueuedLocks::Acquier::YieldExpire
   #
   # @api private
   # @since 0.1.0
-  def yield_with_expire(redis, lock_key, timed, ttl_shift, ttl, &block)
+  def yield_with_expire(redis, logger, lock_key, timed, ttl_shift, ttl, &block)
     if block_given?
       if timed && ttl != nil
         timeout = ((ttl - ttl_shift) / 1000.0).yield_self { |time| (time < 0) ? 0.0 : time }
@@ -23,6 +27,9 @@ module RedisQueuedLocks::Acquier::YieldExpire
       end
     end
   ensure
+    run_non_critical do
+      logger.debug("[redis_queued_locks.expire_lock] lock_key => '#{lock_key}'")
+    end
     redis.call('EXPIRE', lock_key, '0')
   end
 

data/lib/redis_queued_locks/acquier/acquire_lock.rb

@@ -0,0 +1,291 @@
+# 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;
+    # @option logger [#debug]
+    #   - Logger object used from `configuration` layer (see config[:logger]);
+    #   - See RedisQueuedLocks::Logging::VoidLogger for example;
+    # @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:,
+      logger:,
+      &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) }
+
+      run_non_critical do
+        logger.debug(
+          "[redis_queued_locks.start_lock_obtaining] " \
+          "lock_key => '#{lock_key}'"
+        )
+      end
+
+      # 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
+            run_non_critical do
+              logger.debug(
+                "[redis_queued_locks.lock_obtained] " \
+                "lock_key => '#{result[:lock_key]}'" \
+                "acq_time => #{acq_time} (ms)"
+              )
+            end
+
+            # Step X (instrumentation): lock obtained
+            run_non_critical do
+              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
+              })
+            end
+
+            # 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, logger, 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,19 @@
+# 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]
+    # @param logger [#debug]
+    # @return [?]
+    #
+    # @api private
+    # @since 0.1.0
+    def extend_lock_ttl(redis_client, lock_name, milliseconds, logger)
+      # 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