redis_queued_locks 1.1.0 → 1.3.0

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

@@ -1,12 +1,21 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 # rubocop:disable Metrics/ModuleLength, Metrics/BlockNesting
 module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
-  # @since 0.1.0
+  # @since 1.0.0
   extend RedisQueuedLocks::Utilities
 
+  # @return [String]
+  #
+  # @api private
+  # @since 1.3.0
+  EXTEND_LOCK_PTTL = <<~LUA_SCRIPT.strip.tr("\n", '').freeze
+    local new_lock_pttl = redis.call("PTTL", KEYS[1]) + ARGV[1];
+    return redis.call("PEXPIRE", KEYS[1], new_lock_pttl);
+  LUA_SCRIPT
+
   # @param redis [RedisClient]
   # @param logger [::Logger,#debug]
   # @param log_lock_try [Boolean]
@@ -17,11 +26,13 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @param ttl [Integer]
   # @param queue_ttl [Integer]
   # @param fail_fast [Boolean]
+  # @param conflict_strategy [Symbol]
   # @param meta [NilClass,Hash<String|Symbol,Any>]
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Symbol|Hash<Symbol,Any> }
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.3.0
   # rubocop:disable Metrics/MethodLength
   def try_to_lock(
     redis,
@@ -34,11 +45,13 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     ttl,
     queue_ttl,
     fail_fast,
+    conflict_strategy,
     meta
   )
     # Step X: intermediate invocation results
     inter_result = nil
     timestamp = nil
+    spc_processed_timestamp = nil
 
     if log_lock_try
       run_non_critical do
@@ -68,9 +81,162 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       #   watch the lock key changes (and discard acquirement if lock is already
       #   obtained by another acquier during the current lock acquiremntt)
       rconn.multi(watch: [lock_key]) do |transact|
-        # Fast-Step X0: fail-fast check
-        if fail_fast && rconn.call('HGET', lock_key, 'acq_id')
-          # Fast-Step X1: is lock already obtained. fail fast leads to "no try".
+        # SP-Conflict status PREPARING: get the current lock obtainer
+        current_lock_obtainer = rconn.call('HGET', lock_key, 'acq_id')
+        # SP-Conflict status PREPARING: status flag variable
+        sp_conflict_status = nil
+
+        # SP-Conflict Step X1: calculate the current deadlock status
+        if current_lock_obtainer != nil && acquier_id == current_lock_obtainer
+          if log_lock_try
+            run_non_critical do
+              logger.debug do
+                "[redis_queued_locks.try_lock.same_process_conflict_detected] " \
+                "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
+                "acq_id => '#{acquier_id}'"
+              end
+            end
+          end
+
+          # SP-Conflict Step X2: self-process dead lock moment started.
+          # SP-Conflict CHECK (Step CHECK): check chosen strategy and flag the current status
+          # rubocop:disable Lint/DuplicateBranch
+          case conflict_strategy
+          when :work_through
+            # <SP-Conflict Moment>: work through => exit
+            sp_conflict_status = :conflict_work_through
+          when :extendable_work_through
+            # <SP-Conflict Moment>: extendable_work_through => extend the lock pttl and exit
+            sp_conflict_status = :extendable_conflict_work_through
+          when :wait_for_lock
+            # <SP-Conflict Moment>: wait_for_lock => obtain a lock in classic way
+            sp_conflict_status = :conflict_wait_for_lock
+          when :dead_locking
+            # <SP-Conflict Moment>: dead_locking => exit and fail
+            sp_conflict_status = :conflict_dead_lock
+          else
+            # <SP-Conflict Moment>:
+            #   - unknown status => work in classic way <wait_for_lock>
+            #   - it is a case when the new status is added to the code base in the past
+            #     but is forgotten to be added here;
+            sp_conflict_status = :conflict_wait_for_lock
+          end
+          # rubocop:enable Lint/DuplicateBranch
+
+          if log_lock_try
+            run_non_critical do
+              logger.debug do
+                "[redis_queued_locks.try_lock.same_process_conflict_analyzed] " \
+                "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
+                "acq_id => '#{acquier_id}' " \
+                "spc_status => '#{sp_conflict_status}'"
+              end
+            end
+          end
+        end
+
+        # SP-Conflict-Step X2: switch to conflict-based logic or not
+        if sp_conflict_status == :extendable_conflict_work_through
+          # SP-Conflict-Step FINAL (SPCF): extend the lock and work through
+          #   - extend the lock ttl;
+          #   - store extensions in lock metadata;
+          # SPCF Step 1: extend the lock pttl
+          #   - [REDIS RESULT]: in normal cases should return the last script command value
+          #     - for the current script should return:
+          #       <1> => timeout was set;
+          #       <0> => timeount was not set;
+          transact.call('EVAL', EXTEND_LOCK_PTTL, 1, lock_key, ttl)
+          # SPCF Step <Meta>: store conflict-state additionals in lock metadata:
+          # SPCF Step 2: (lock meta-data)
+          #   - add the added ttl to reflect the real lock TTL in info;
+          #   - [REDIS RESULT]: in normal cases should return the value of <ttl> key
+          #     - for non-existent key value starts from <0> (zero)
+          transact.call('HINCRBY', lock_key, 'spc_ext_ttl', ttl)
+          # SPCF Step 3: (lock meta-data)
+          #   - increment the conflcit counter in order to remember
+          #     how many times dead lock happened;
+          #   - [REDIS RESULT]: in normal cases should return the value of <spc_cnt> key
+          #     - for non-existent key starts from 0
+          transact.call('HINCRBY', lock_key, 'spc_cnt', 1)
+          # SPCF Step 4: (lock meta-data)
+          #   - remember the last ext-timestamp and the last ext-initial ttl;
+          #   - [REDIS RESULT]: for normal cases should return the number of fields
+          #     were added/changed;
+          transact.call(
+            'HSET',
+            lock_key,
+            'l_spc_ext_ts', (spc_processed_timestamp = Time.now.to_f),
+            'l_spc_ext_ini_ttl', ttl
+          )
+          inter_result = :extendable_conflict_work_through
+
+          if log_lock_try
+            run_non_critical do
+              logger.debug do
+                "[redis_queued_locks.try_lock.reentrant_lock__extend_and_work_through] " \
+                "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
+                "acq_id => '#{acquier_id}'" \
+                "spc_status => '#{sp_conflict_status} '" \
+                "last_ext_ttl => '#{ttl}' " \
+                "last_ext_ts => '#{spc_processed_timestamp}'"
+              end
+            end
+          end
+        # SP-Conflict-Step X2: switch to dead lock logic or not
+        elsif sp_conflict_status == :conflict_work_through
+          inter_result = :conflict_work_through
+
+          # SPCF Step X: (lock meta-data)
+          #   - increment the conflcit counter in order to remember
+          #     how many times dead lock happened;
+          #   - [REDIS RESULT]: in normal cases should return the value of <spc_cnt> key
+          #     - for non-existent key starts from 0
+          transact.call('HINCRBY', lock_key, 'spc_cnt', 1)
+          # SPCF Step 4: (lock meta-data)
+          #   - remember the last ext-timestamp and the last ext-initial ttl;
+          #   - [REDIS RESULT]: for normal cases should return the number of fields
+          #     were added/changed;
+          transact.call(
+            'HSET',
+            lock_key,
+            'l_spc_ts', (spc_processed_timestamp = Time.now.to_f)
+          )
+
+          if log_lock_try
+            run_non_critical do
+              logger.debug do
+                "[redis_queued_locks.try_lock.reentrant_lock__work_through] " \
+                "lock_key => '#{lock_key}' " \
+                "queue_ttl => #{queue_ttl} " \
+                "acq_id => '#{acquier_id}' " \
+                "spc_status => '#{sp_conflict_status} ' " \
+                "last_spc_ts => '#{spc_processed_timestamp}'"
+              end
+            end
+          end
+        # SP-Conflict-Step X2: switch to dead lock logic or not
+        elsif sp_conflict_status == :conflict_dead_lock
+          inter_result = :conflict_dead_lock
+          spc_processed_timestamp = Time.now.to_f
+
+          if log_lock_try
+            logger.debug do
+              "[redis_queued_locks.try_lock.single_process_lock_conflict__dead_lock] " \
+              "lock_key => '#{lock_key}' " \
+              "queue_ttl => #{queue_ttl} " \
+              "acq_id => '#{acquier_id}' " \
+              "spc_status => '#{sp_conflict_status}' " \
+              "last_spc_ts => '#{spc_processed_timestamp}'"
+            end
+          end
+        # Reached the SP-Non-Conflict Mode (NOTE):
+        #   - in other sp-conflict cases we are in <wait_for_lock> (non-conflict) status and should
+        #     continue to work in classic way (next lines of code):
+        elsif fail_fast && current_lock_obtainer != nil # Fast-Step X0: fail-fast check
+          # Fast-Step X1: lock is already obtained. fail fast leads to "no try".
           inter_result = :fail_fast_no_try
         else
           # Step 1: add an acquier to the lock acquirement queue
@@ -216,6 +382,63 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
     # Step 7: Analyze the aquirement attempt:
     # rubocop:disable Lint/DuplicateBranch
     case
+    when inter_result == :extendable_conflict_work_through
+      # Step 7.same_process_conflict.A:
+      #   - extendable_conflict_work_through case => yield <block> without lock realesing/extending;
+      #   - lock is extended in logic above;
+      #   - if <result == nil> => the lock was changed during an extention:
+      #     it is the fail case => go retry.
+      #   - else: let's go! :))
+      if result.is_a?(::Array) && result.size == 4 # NOTE: four commands should be processed
+        # TODO:
+        #   => (!) analyze the command result and do actions with the depending on it
+        #   1. EVAL (extend lock pttl) (OK for != nil)
+        #   2. HINCRBY (ttl extension) (OK for != nil)
+        #   3. HINCRBY (increased spc count) (OK for != nil)
+        #   4. HSET (store the last spc time and ttl data) (OK for == 2 or != nil)
+        if result[0] != nil && result[1] != nil && result[2] != nil && result[3] != nil
+          RedisQueuedLocks::Data[ok: true, result: {
+            process: :extendable_conflict_work_through,
+            lock_key: lock_key,
+            acq_id: acquier_id,
+            ts: spc_processed_timestamp,
+            ttl: ttl
+          }]
+        elsif result[0] != nil
+          # NOTE: that is enough to the fact that the lock is extended but <TODO>
+          # TODO: add detalized overview (log? some in-line code clarifications?) of the result
+          RedisQueuedLocks::Data[ok: true, result: {
+            process: :extendable_conflict_work_through,
+            lock_key: lock_key,
+            acq_id: acquier_id,
+            ts: spc_processed_timestamp,
+            ttl: ttl
+          }]
+        else
+          # NOTE: unknown behaviour :thinking:
+          RedisQueuedLocks::Data[ok: false, result: :unknown]
+        end
+      elsif result == nil || (result.is_a?(::Array) && result.empty?)
+        # NOTE: the lock key was changed durign an SPC logic execution
+        RedisQueuedLocks::Data[ok: false, result: :lock_is_acquired_during_acquire_race]
+      else
+        # NOTE: unknown behaviour :thinking:. this part is not reachable at the moment.
+        RedisQueuedLocks::Data[ok: false, result: :unknown]
+      end
+    when inter_result == :conflict_work_through
+      # Step 7.same_process_conflict.B:
+      #   - conflict_work_through case => yield <block> without lock realesing/extending
+      RedisQueuedLocks::Data[ok: true, result: {
+        process: :conflict_work_through,
+        lock_key: lock_key,
+        acq_id: acquier_id,
+        ts: spc_processed_timestamp,
+        ttl: ttl
+      }]
+    when inter_result == :conflict_dead_lock
+      # Step 7.same_process_conflict.C:
+      #  - deadlock. should fail in acquirement logic;
+      RedisQueuedLocks::Data[ok: false, result: inter_result]
     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
       RedisQueuedLocks::Data[ok: false, result: inter_result]
@@ -238,10 +461,13 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
       #   3. pexpire should return 1 (expiration time is successfully applied)
 
       # Step 7.d: locked! :) let's go! => successfully acquired
-      RedisQueuedLocks::Data[
-        ok: true,
-        result: { lock_key: lock_key, acq_id: acquier_id, ts: timestamp, ttl: ttl }
-      ]
+      RedisQueuedLocks::Data[ok: true, result: {
+        process: :lock_obtaining,
+        lock_key: lock_key,
+        acq_id: acquier_id,
+        ts: timestamp,
+        ttl: ttl
+      }]
     else
       # Ste 7.3: unknown behaviour :thinking:
       RedisQueuedLocks::Data[ok: false, result: :unknown]
@@ -259,13 +485,14 @@ module RedisQueuedLocks::Acquier::AcquireLock::TryToLock
   # @return [Hash<Symbol,Any>] Format: { ok: true/false, result: Any }
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
+  # @version 1.3.0
   def dequeue_from_lock_queue(redis, logger, lock_key, lock_key_queue, queue_ttl, acquier_id)
     result = redis.call('ZREM', lock_key_queue, acquier_id)
 
     run_non_critical do
       logger.debug do
-        "[redis_queued_locks.fail_fast_or_limits_reached__dequeue] " \
+        "[redis_queued_locks.fail_fast_or_limits_reached_or_deadlock__dequeue] " \
         "lock_key => '#{lock_key}' " \
         "queue_ttl => '#{queue_ttl}' " \
         "acq_id => '#{acquier_id}'"

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # @api private
-# @since 0.1.0
+# @since 1.0.0
 module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
   # @param timeout [NilClass,Integer]
   #   Time period after which the logic will fail with timeout error.
@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquier::AcquireLock::WithAcqTimeout
   # @return [Any]
   #
   # @api private
-  # @since 0.1.0
+  # @since 1.0.0
   def with_acq_timeout(timeout, lock_key, raise_errors, on_timeout: nil, &block)
     ::Timeout.timeout(timeout, &block)
   rescue ::Timeout::Error

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.3.0
+module RedisQueuedLocks::Acquier::AcquireLock::YieldExpire
+  # @since 1.3.0
+  extend RedisQueuedLocks::Utilities
+
+  # @return [String]
+  #
+  # @api private
+  # @since 1.3.0
+  DECREASE_LOCK_PTTL = <<~LUA_SCRIPT.strip.tr("\n", '').freeze
+    local new_lock_pttl = redis.call("PTTL", KEYS[1]) - ARGV[1];
+    return redis.call("PEXPIRE", KEYS[1], new_lock_pttl);
+  LUA_SCRIPT
+
+  # @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 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 [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 should_expire [Boolean] Should the lock be expired after the block invocation.
+  # @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.
+  #
+  # @api private
+  # @since 1.3.0
+  # rubocop:disable Metrics/MethodLength
+  def yield_expire(
+    redis,
+    logger,
+    lock_key,
+    acquier_id,
+    timed,
+    ttl_shift,
+    ttl,
+    queue_ttl,
+    should_expire,
+    should_decrease,
+    &block
+  )
+    initial_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+
+    if block_given?
+      timeout = ((ttl - ttl_shift) / 1000.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, &block)
+      else
+        yield
+      end
+    end
+  ensure
+    if should_expire
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.expire_lock] " \
+          "lock_key => '#{lock_key}' " \
+          "queue_ttl => #{queue_ttl} " \
+          "acq_id => '#{acquier_id}'"
+        end
+      end
+      redis.call('EXPIRE', lock_key, '0')
+    elsif should_decrease
+      finish_time = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC, :millisecond)
+      spent_time = (finish_time - initial_time)
+      decreased_ttl = ttl - spent_time - RedisQueuedLocks::Resource::REDIS_TIMESHIFT_ERROR
+      if decreased_ttl > 0
+        run_non_critical do
+          logger.debug do
+            "[redis_queued_locks.decrease_lock] " \
+            "lock_key => '#{lock_key}' " \
+            "decreased_ttl => '#{decreased_ttl} " \
+            "queue_ttl => #{queue_ttl} " \
+            "acq_id => '#{acquier_id}' " \
+          end
+        end
+        # NOTE:# NOTE: EVAL signature -> <lua script>, (number of keys), *(keys), *(arguments)
+        redis.call('EVAL', DECREASE_LOCK_PTTL, 1, lock_key, decreased_ttl)
+        # TODO: upload scripts to the redis
+      end
+    end
+  end
+  # rubocop:enable Metrics/MethodLength
+
+  private
+
+  # @param timeout [Float]
+  # @parma lock_key [String]
+  # @param lock_ttl [Integer,NilClass]
+  # @param block [Blcok]
+  # @return [Any]
+  #
+  # @api private
+  # @since 1.3.0
+  def yield_with_timeout(timeout, lock_key, lock_ttl, &block)
+    ::Timeout.timeout(timeout, &block)
+  rescue ::Timeout::Error
+    raise(
+      RedisQueuedLocks::TimedLockTimeoutError,
+      "Passed <timed> block of code exceeded " \
+      "the lock TTL (lock: \"#{lock_key}\", ttl: #{lock_ttl})"
+    )
+  end
+end