redis_queued_locks 1.12.0 → 1.13.0

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

@@ -3,7 +3,7 @@
 # @api private
 # @since 1.3.0
 # @version 1.7.0
-module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
+module RedisQueuedLocks::Acquirer::AcquireLock::YieldExpire
   require_relative 'yield_expire/log_visitor'
 
   # @return [String]
@@ -18,14 +18,13 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   # @param redis [RedisClient] Redis connection.
   # @param logger [::Logger,#debug] Logger object.
   # @param lock_key [String] Obtained lock key that should be expired.
-  # @param acquier_id [String] Acquier identifier.
+  # @param acquirer_id [String] Acquirer identifier.
   # @param host_id [String] Host identifier.
   # @param access_strategy [Symbol] Lock obtaining strategy.
   # @param timed [Boolean] Should the lock be wrapped by Timeout with with lock's ttl
-  # @param ttl_shift [Float] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
+  # @param ttl_shift [Numeric] Lock's TTL shifting. Should affect block's ttl. In millisecodns.
   # @param ttl [Integer,NilClass] Lock's time to live (in ms). Nil means "without timeout".
   # @param queue_ttl [Integer] Lock request lifetime.
-  # @param block [Block] Custom logic that should be invoked unter the obtained lock.
   # @param meta [NilClass,Hash<String|Symbol,Any>] Custom metadata wich is passed to the lock data;
   # @param log_sampled [Boolean] Should the logic be logged or not.
   # @param instr_sampled [Boolean] Should the logic be instrumented or not.
@@ -33,7 +32,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   # @param should_decrease [Boolean]
   #   - Should decrease the lock TTL after the lock invocation;
   #   - It is suitable for extendable reentrant locks;
-  # @return [Any,NilClass] nil is returned no block parametr is provided.
+  # @param block [Block] Custom logic that should be invoked under the obtained lock.
+  # @return [Any,NilClass] nil is returned when no block parametr is provided.
   #
   # @api private
   # @since 1.3.0
@@ -43,7 +43,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
     redis,
     logger,
     lock_key,
-    acquier_id,
+    acquirer_id,
     host_id,
     access_strategy,
     timed,
@@ -60,33 +60,56 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
     initial_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
 
     if block_given?
-      timeout = ((ttl - ttl_shift) / 1_000.0).yield_self do |time|
-        # NOTE: time in <seconds> cuz Ruby's Timeout requires <seconds>
-        (time < 0) ? 0.0 : time
-      end
-
       if timed && ttl != nil
-        yield_with_timeout(timeout, lock_key, ttl, acquier_id, host_id, meta, &block)
+        # NOTE:
+        #   - steep is ignored cuz steep can not recognize `::Integer - ::Integer|::Float`
+        #     operation here for some mystical reason (it tryes to find overloadd `-` method for
+        #     integer and fails on it);
+        #   - so we need to ignore steep here at all and manually set the type of each
+        #     variable for the correct following variable type recognitions;
+
+        # steep:ignore:start
+        # @type var ttl: Integer
+        # @type var ttl_shift: Float|Integer
+        # @type var timeout: Float
+        timeout = ((ttl - ttl_shift) / 1_000.0).yield_self do |time|
+          # @type var time: Float
+          # NOTE: time in <seconds> cuz Ruby's Timeout requires <seconds>
+          (time < 0) ? 0.0 : time
+        end
+        # steep:ignore:end
+
+        yield_with_timeout(
+          timeout,
+          lock_key,
+          ttl,
+          acquirer_id,
+          host_id,
+          meta,
+          &block # steep:ignore
+        )
       else
         yield
       end
     end
   ensure
-    if should_expire
+    if should_expire # TODO: comment all cases/examples when should_expire is true
       LogVisitor.expire_lock(
         logger, log_sampled, lock_key,
-        queue_ttl, acquier_id, host_id, access_strategy
+        queue_ttl, acquirer_id, host_id, access_strategy
       )
       redis.call('EXPIRE', lock_key, '0')
-    elsif should_decrease
+    elsif should_decrease # TODO: comment all cases/examples when should_expire is true
       finish_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+      # @type var initial_time: Integer
       spent_time = (finish_time - initial_time)
+      # @type var ttl: Integer
       decreased_ttl = ttl - spent_time - RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
 
       if decreased_ttl > 0
         LogVisitor.decrease_lock(
           logger, log_sampled, lock_key,
-          decreased_ttl, queue_ttl, acquier_id, host_id, access_strategy
+          decreased_ttl, queue_ttl, acquirer_id, host_id, access_strategy
         )
         # NOTE:# NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)
         redis.call('EVAL', DECREASE_LOCK_PTTL, 1, lock_key, decreased_ttl)
@@ -101,7 +124,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   # @param timeout [Float]
   # @parma lock_key [String]
   # @param lock_ttl [Integer,NilClass]
-  # @param acquier_id [String]
+  # @param acquirer_id [String]
   # @param host_id [String]
   # @param meta [NilClass,Hash<Symbol|String,Any>]
   # @param block [Blcok]
@@ -112,7 +135,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
   # @api private
   # @since 1.3.0
   # @version 1.12.0
-  def yield_with_timeout(timeout, lock_key, lock_ttl, acquier_id, host_id, meta, &block)
+  def yield_with_timeout(timeout, lock_key, lock_ttl, acquirer_id, host_id, meta, &block)
     ::Timeout.timeout(timeout, RedisQueuedLocks::TimedLockIntermediateTimeoutError, &block)
   rescue RedisQueuedLocks::TimedLockIntermediateTimeoutError
     raise(
@@ -121,8 +144,8 @@ module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
       "(lock: \"#{lock_key}\", " \
       "ttl: #{lock_ttl}, " \
       "meta: #{meta ? meta.inspect : '<no-meta>'}, " \
-      "acq_id: \"#{acquier_id}\", " \
-      "hst_id: \"#{host_id}\")",
+      "acq_id: \"#{acquirer_id}\", " \
+      "hst_id: \"#{host_id}\")"
     )
   end
 end

data/lib/redis_queued_locks/{acquier → acquirer}/acquire_lock.rb

@@ -8,7 +8,7 @@
 # rubocop:disable Metrics/ClassLength
 # rubocop:disable Metrics/BlockNesting
 # rubocop:disable Style/IfInsideElse
-module RedisQueuedLocks::Acquier::AcquireLock
+module RedisQueuedLocks::Acquirer::AcquireLock
   require_relative 'acquire_lock/log_visitor'
   require_relative 'acquire_lock/instr_visitor'
   require_relative 'acquire_lock/delay_execution'
@@ -32,7 +32,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
     # @param redis [RedisClient]
     #   Redis connection client.
     # @param lock_name [String]
-    #   Lock name to be acquier.
+    #   Lock name to be acquirer.
     # @option process_id [Integer,String]
     #   The process that want to acquire a lock.
     # @option thread_id [Integer,String]
@@ -45,7 +45,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   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]
+    # @option timeout [Integer,NilClass]
     #   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.
@@ -72,15 +72,15 @@ module RedisQueuedLocks::Acquier::AcquireLock
     # @option detailed_acq_timeout_error [Boolean]
     #   - Add additional data to the acquirement timeout error such as the current lock queue state
     #   and the required lock state;
-    #   - See `config[:detailed_acq_timeout_error]` for details;
+    #   - See `config['detailed_acq_timeout_error']` for details;
     # @option logger [::Logger,#debug]
-    #   - Logger object used from the configuration layer (see config[:logger]);
+    #   - Logger object used from the configuration layer (see config['logger']);
     #   - See `RedisQueuedLocks::Logging::VoidLogger` for example;
     #   - Supports `SemanticLogger::Logger` (see "semantic_logger" gem)
     # @option log_lock_try [Boolean]
     #   - should be logged the each try of lock acquiring (a lot of logs can be generated depending
     #     on your retry configurations);
-    #   - see `config[:log_lock_try]`;
+    #   - see `config['log_lock_try']`;
     # @option instrument [NilClass,Any]
     #   - Custom instrumentation data wich will be passed to the instrumenter's payload
     #     with :instrument key;
@@ -88,12 +88,14 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   - The conflict strategy mode for cases when the process that obtained the lock
     #     want to acquire this lock again;
     #   - By default uses `:wait_for_lock` strategy;
-    #   - pre-confured in `config[:default_conflict_strategy]`;
+    #   - pre-confured in `config['default_conflict_strategy']`;
     #   - Supports:
     #     - `:work_through`;
     #     - `:extendable_work_through`;
     #     - `:wait_for_lock`;
     #     - `:dead_locking`;
+    # @option read_write_mode [Symbol]
+    #   - ?
     # @option access_strategy [Symbol]
     #   - The way in which the lock will be obtained;
     #   - By default it uses `:queued` strategy;
@@ -103,19 +105,19 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #     - `:random` (RANDOM): obtain a lock without checking the positions in the queue
     #       (but with checking the limist, retries, timeouts and so on). if lock is
     #       free to obtain - it will be obtained;
-    #   - pre-configured in `config[:default_access_strategy]`;
+    #   - pre-configured in `config['default_access_strategy']`;
     # @option log_sampling_enabled [Boolean]
     #   - enables <log sampling>: only the configured percent of RQL cases will be logged;
     #   - disabled by default;
-    #   - works in tandem with <config.log_sampling_percent and <log.sampler>;
+    #   - works in tandem with <config['log_sampling_percent'] and <config['log_sampler']>;
     # @option log_sampling_percent [Integer]
     #   - the percent of cases that should be logged;
-    #   - take an effect when <config.log_sampling_enalbed> is true;
-    #   - works in tandem with <config.log_sampling_enabled> and <config.log_sampler> configs;
+    #   - take an effect when <config['log_sampling_enalbed']> is true;
+    #   - works in tandem with <config['log_sampling_enabled']> and <config['log_sampler']> configs;
     # @option log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
     #   - percent-based log sampler that decides should be RQL case logged or not;
-    #   - works in tandem with <config.log_sampling_enabled> and
-    #     <config.log_sampling_percent> configs;
+    #   - works in tandem with <config['log_sampling_enabled']> and
+    #     <config['log_sampling_percent']> configs;
     #   - based on the ultra simple percent-based (weight-based) algorithm that uses
     #     SecureRandom.rand method so the algorithm error is ~(0%..13%);
     #   - you can provide your own log sampler with bettter algorithm that should realize
@@ -128,15 +130,16 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   - enables <instrumentaion sampling>: only the configured percent
     #     of RQL cases will be instrumented;
     #   - disabled by default;
-    #   - works in tandem with <config.instr_sampling_percent and <log.instr_sampler>;
+    #   - works in tandem with <config['instr_sampling_percent']> and <config['instr_sampler']>;
     # @option instr_sampling_percent [Integer]
     #   - the percent of cases that should be instrumented;
-    #   - take an effect when <config.instr_sampling_enalbed> is true;
-    #   - works in tandem with <config.instr_sampling_enabled> and <config.instr_sampler> configs;
+    #   - take an effect when <config['instr_sampling_enalbed']> is true;
+    #   - works in tandem with <config['instr_sampling_enabled']>
+    #     and <config['instr_sampler']> configs;
     # @option instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
     #   - percent-based log sampler that decides should be RQL case instrumented or not;
-    #   - works in tandem with <config.instr_sampling_enabled> and
-    #     <config.instr_sampling_percent> configs;
+    #   - works in tandem with <config['instr_sampling_enabled']> and
+    #     <config['instr_sampling_percent']> configs;
     #   - based on the ultra simple percent-based (weight-based) algorithm that uses
     #     SecureRandom.rand method so the algorithm error is ~(0%..13%);
     #   - you can provide your own log sampler with bettter algorithm that should realize
@@ -148,13 +151,13 @@ module RedisQueuedLocks::Acquier::AcquireLock
     #   - makes sense when instrumentation sampling is enabled;
     # @param [Block]
     #   A block of code that should be executed after the successfully acquired lock.
-    # @return [RedisQueuedLocks::Data,Hash<Symbol,Any>,yield]
+    # @return [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 1.0.0
-    # @version 1.9.0
+    # @version 1.13.0
     def acquire_lock(
       redis,
       lock_name,
@@ -179,6 +182,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       logger:,
       log_lock_try:,
       conflict_strategy:,
+      read_write_mode:,
       access_strategy:,
       log_sampling_enabled:,
       log_sampling_percent:,
@@ -224,7 +228,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       end
 
       # Step 1: prepare lock requirements (generate lock name, calc lock ttl, etc).
-      acquier_id = RedisQueuedLocks::Resource.acquier_identifier(
+      acquirer_id = RedisQueuedLocks::Resource.acquirer_identifier(
         process_id,
         thread_id,
         fiber_id,
@@ -240,7 +244,11 @@ module RedisQueuedLocks::Acquier::AcquireLock
       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
+
+      read_lock_key_queue = RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
+      write_lock_key_queue = RedisQueuedLocks::Resource.prepare_write_lock_queue(lock_name)
+
+      acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position
 
       log_sampled = RedisQueuedLocks::Logging.should_log?(
         log_sampling_enabled,
@@ -256,6 +264,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
       )
 
       # Step X: intermediate result observer
+      # @type var acq_process: Hash[Symbol,untyped]
       acq_process = {
         lock_info: {},
         should_try: true,
@@ -272,9 +281,12 @@ module RedisQueuedLocks::Acquier::AcquireLock
           redis,
           logger,
           lock_key,
+          read_write_mode,
           lock_key_queue,
+          read_lock_key_queue,
+          write_lock_key_queue,
           queue_ttl,
-          acquier_id,
+          acquirer_id,
           host_id,
           access_strategy,
           log_sampled,
@@ -284,7 +296,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
       LogVisitor.start_lock_obtaining(
         logger, log_sampled, lock_key,
-        queue_ttl, acquier_id, host_id, access_strategy
+        queue_ttl, acquirer_id, host_id, access_strategy
       )
 
       # Step 2: try to lock with timeout
@@ -304,29 +316,34 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
           LogVisitor.start_try_to_lock_cycle(
             logger, log_sampled, lock_key,
-            queue_ttl, acquier_id, host_id, access_strategy
+            queue_ttl, acquirer_id, host_id, access_strategy
           )
 
           # Step 2.X: check the actual score: is it in queue ttl limit or not?
-          if RedisQueuedLocks::Resource.dead_score_reached?(acquier_position, queue_ttl)
+          if RedisQueuedLocks::Resource.dead_score_reached?(acquirer_position, queue_ttl)
             # Step 2.X.X: dead score reached => re-queue the lock request with the new score;
-            acquier_position = RedisQueuedLocks::Resource.calc_initial_acquier_position
+            acquirer_position = RedisQueuedLocks::Resource.calc_initial_acquirer_position
 
-            LogVisitor.dead_score_reached__reset_acquier_position(
+            LogVisitor.dead_score_reached__reset_acquirer_position(
               logger, log_sampled, lock_key,
-              queue_ttl, acquier_id, host_id, access_strategy
+              queue_ttl, acquirer_id, host_id, access_strategy
             )
           end
 
+          # NOTE: (steep ignorance) pattern matching is not supported in steep
+          # steep:ignore:start
           try_to_lock(
             redis,
             logger,
             log_lock_try,
             lock_key,
+            read_write_mode,
             lock_key_queue,
-            acquier_id,
+            read_lock_key_queue,
+            write_lock_key_queue,
+            acquirer_id,
             host_id,
-            acquier_position,
+            acquirer_position,
             lock_ttl,
             queue_ttl,
             fail_fast,
@@ -336,6 +353,10 @@ module RedisQueuedLocks::Acquier::AcquireLock
             log_sampled,
             instr_sampled
           ) => { ok:, result: }
+          # steep:ignore:end
+
+          # @type var ok: bool
+          # @type var result: Symbol|Hash[Symbol,untyped]
 
           acq_end_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :microsecond)
           acq_time = ((acq_end_time - acq_start_time) / 1_000.0).ceil(2)
@@ -346,12 +367,14 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
           # Step 2.1: analyze an acquirement attempt
           if ok
+            # @type var result: Hash[Symbol,untyped]
+
             # Step X: (instrumentation)
             if acq_process[:result][:process] == :extendable_conflict_work_through
               # instrumetnation: (reentrant lock with ttl extension)
               LogVisitor.extendable_reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquier_id, host_id, acq_time, access_strategy
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy
               )
               InstrVisitor.extendable_reentrant_lock_obtained(
                 instrumenter, instr_sampled, result[:lock_key],
@@ -362,7 +385,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               # instrumetnation: (reentrant lock without ttl extension)
               LogVisitor.reentrant_lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquier_id, host_id, acq_time, access_strategy
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy
               )
               InstrVisitor.reentrant_lock_obtained(
                 instrumenter, instr_sampled, result[:lock_key],
@@ -374,7 +397,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               # NOTE: classic is: acq_process[:result][:process] == :lock_obtaining
               LogVisitor.lock_obtained(
                 logger, log_sampled, result[:lock_key],
-                queue_ttl, acquier_id, host_id, acq_time, access_strategy
+                queue_ttl, acquirer_id, host_id, acq_time, access_strategy
               )
               InstrVisitor.lock_obtained(
                 instrumenter, instr_sampled, result[:lock_key],
@@ -397,6 +420,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
             acq_process[:acq_time] = acq_time
             acq_process[:acq_end_time] = acq_end_time
           else
+            # @type var result: Symbol
+
             # Step 2.2: failed to acquire. anylize each case and act in accordance
             if acq_process[:result] == :fail_fast_no_try # Step 2.2.a: fail without try
               acq_process[:should_try] = false
@@ -415,9 +440,9 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
               if raise_errors
                 raise(
-                  RedisQueuedLock::ConflictLockObtainError,
+                  RedisQueuedLocks::ConflictLockObtainError,
                   "Lock Conflict: trying to acquire the lock \"#{lock_key}\" " \
-                  "that is already acquired by the current acquier (acq_id: \"#{acquired_id}\")."
+                  "that is already acquired by the current acquirer (acq_id: \"#{acquirer_id}\")."
                 )
               end
             else
@@ -443,7 +468,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
 
                   if raise_errors
                     raise(
-                      RedisQueuedLocks::LockAcquiermentRetryLimitError,
+                      RedisQueuedLocks::LockAcquirementRetryLimitError,
                       "Failed to acquire the lock \"#{lock_key}\" " \
                       "for the given retry_count limit (#{retry_count} times)."
                     )
@@ -484,7 +509,7 @@ module RedisQueuedLocks::Acquier::AcquireLock
               redis,
               logger,
               lock_key,
-              acquier_id,
+              acquirer_id,
               host_id,
               access_strategy,
               timed,
@@ -531,14 +556,16 @@ module RedisQueuedLocks::Acquier::AcquireLock
                 acq_process[:lock_info][:acq_id],
                 acq_process[:lock_info][:hst_id],
                 acq_process[:lock_info][:ts],
-                acq_process[:lock_info][:lock_key],
                 acq_process[:acq_time],
+                acq_process[:hold_time],
                 instrument
               )
             end
           end
         else
-          RedisQueuedLocks::Data[ok: true, result: acq_process[:lock_info]]
+          # rubocop:disable Layout/LineLength
+          { ok: true, result: acq_process[:lock_info] } #: { ok: bool, result: Hash[Symbol,untyped] }
+          # rubocop:enable Layout/LineLength
         end
       else
         if acq_process[:result] != :retry_limit_reached &&
@@ -551,8 +578,8 @@ module RedisQueuedLocks::Acquier::AcquireLock
           #   - **(notice: 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]]
+        # Step 3.b: lock is not acquired (acquirer is dequeued by timeout callback)
+        { ok: false, result: acq_process[:result] } #: { ok: bool, result: Symbol }
       end
     end
   end

data/lib/redis_queued_locks/{acquier → acquirer}/clear_dead_requests.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::ClearDeadRequests
+module RedisQueuedLocks::Acquirer::ClearDeadRequests
   class << self
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
@@ -39,9 +39,11 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
       instr_sampler,
       instr_sample_this
     )
-      dead_score = RedisQueuedLocks::Resource.acquier_dead_score(dead_ttl / 1_000.0)
+      dead_score = RedisQueuedLocks::Resource.acquirer_dead_score(dead_ttl / 1_000.0)
 
+      # @type var result: Set[String]
       result = Set.new.tap do |processed_queues|
+        # @type var processed_queues: Set[String]
         redis_client.with do |rconn|
           each_lock_queue(rconn, scan_size) do |lock_queue|
             rconn.call('ZREMRANGEBYSCORE', lock_queue, '-inf', dead_score)
@@ -50,7 +52,7 @@ module RedisQueuedLocks::Acquier::ClearDeadRequests
         end
       end
 
-      RedisQueuedLocks::Data[ok: true, result: { processed_queues: result }]
+      { ok: true, result: { processed_queues: result } }
     end
 
     private

data/lib/redis_queued_locks/{acquier → acquirer}/extend_lock_ttl.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::ExtendLockTTL
+module RedisQueuedLocks::Acquirer::ExtendLockTTL
   # @return [String]
   #
   # @api private
@@ -54,10 +54,11 @@ module RedisQueuedLocks::Acquier::ExtendLockTTL
       result = redis_client.call('EVAL', EXTEND_LOCK_PTTL, 1, lock_key, milliseconds)
       # TODO: upload scripts to the redis
 
+      # @type var result: Integer
       if result == 1
-        RedisQueuedLocks::Data[ok: true, result: :ttl_extended]
+        { ok: true, result: :ttl_extended }
       else
-        RedisQueuedLocks::Data[ok: false, result: :async_expire_or_no_lock]
+        { ok: false, result: :async_expire_or_no_lock }
       end
     end
   end

data/lib/redis_queued_locks/{acquier → acquirer}/is_locked.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::IsLocked
+module RedisQueuedLocks::Acquirer::IsLocked
   class << self
     # @param redis_client [RedisClient]
     # @param lock_name [String]

data/lib/redis_queued_locks/{acquier → acquirer}/is_queued.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::IsQueued
+module RedisQueuedLocks::Acquirer::IsQueued
   class << self
     # @param redis_client [RedisClient]
     # @param lock_name [String]

data/lib/redis_queued_locks/{acquier → acquirer}/keys.rb

@@ -2,23 +2,23 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::Keys
+module RedisQueuedLocks::Acquirer::Keys
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
-    # @return [Array<String>]
+    # @return [Set<String>]
     #
     # @api private
     # @since 1.0.0
     def keys(redis_client, scan_size:)
-      Set.new.tap do |keys|
+      Set.new.tap do |keyset|
+        # @type var keyset: Set[String]
         redis_client.scan(
           'MATCH',
           RedisQueuedLocks::Resource::KEY_PATTERN,
           count: scan_size
         ) do |key|
-          # TODO: reduce unnecessary iterations
-          keys.add(key)
+          keyset.add(key)
         end
       end
     end

data/lib/redis_queued_locks/{acquier → acquirer}/lock_info.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::LockInfo
+module RedisQueuedLocks::Acquirer::LockInfo
   class << self
     # @param redis_client [RedisClient]
     # @param lock_name [String]
@@ -10,7 +10,7 @@ module RedisQueuedLocks::Acquier::LockInfo
     #   - `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:123/456/789/987/uniqstring", # lock acquier identifier
+    #     'acq_id' => "rql:acq:123/456/789/987/uniqstring", # lock acquirer identifier
     #     'hst_id' => "rql:hst:123/456/987/uniqstring", # lock host identifier
     #     'ts' => 123456789.2649841, # <locked at> time stamp (epoch, seconds.microseconds)
     #     'ini_ttl' => 123456789, # initial lock key ttl (milliseconds)
@@ -43,15 +43,19 @@ module RedisQueuedLocks::Acquier::LockInfo
         #     - lock is expired + re-obtained;
         nil
       else
+        # NOTE: the result of MULTI-command is an array of results of each internal command
+        #   - result[0] (HGETALL) (Hash<String,String>)
+        #     => (will be mutated further with different value types)
+        #   - result[1] (PTTL) (Integer)
+        #     => (without any mutation, integer is atomic)
+
+        # @type var result: [Hash[String,String|Float|Integer],Integer]
         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)
           hget_cmd_res.tap do |lock_data|
             lock_data['lock_key'] = lock_key
             lock_data['ts'] = Float(lock_data['ts'])

data/lib/redis_queued_locks/{acquier → acquirer}/locks.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.0.0
-module RedisQueuedLocks::Acquier::Locks
+module RedisQueuedLocks::Acquirer::Locks
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
@@ -50,23 +50,36 @@ module RedisQueuedLocks::Acquier::Locks
     def extract_locks_info(redis_client, lock_keys)
       # TODO: refactor with RedisQueuedLocks::Acquier::LockInfo
       Set.new.tap do |seeded_locks|
+        # rubocop:disable Layout/LineLength
+        # @type var seeded_locks: Set[{ lock: String, status: :released|:alive, info: Hash[String,untyped] }]
+        # rubocop:enable Layout/LineLength
+
         # Step X: iterate each lock and extract their info
         lock_keys.each do |lock_key|
           # Step 1: extract lock info from redis
+
+          # @type var lock_info: Hash[String,String|Float|Integer]
           lock_info = redis_client.pipelined do |pipeline|
             pipeline.call('HGETALL', lock_key)
             pipeline.call('PTTL', lock_key)
           end.yield_self do |result| # Step 2: format the result
             # Step 2.X: lock is released
             if result == nil
-              {}
+              {} #: Hash[String,String|Float|Integer]
             else
+              # NOTE: the result of MULTI-command is an array of results of each internal command
+              #   - result[0] (HGETALL) (Hash<String,String>)
+              #     => (will be mutated further with different value types)
+              #   - result[1] (PTTL) (Integer)
+              #     => (without any mutation, integer is atomic)
+
+              # @type var result: [Hash[String,String|Float|Integer],Integer]
               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
-                {}
+                {} #: Hash[String,String|Float|Integer]
               else
                 # Step 2.Z: lock is alive => format received info + add additional rem_ttl info
                 hget_cmd_res.tap do |lock_data|