redis_queued_locks 1.22.0 → 1.23.0

data/lib/redis_queued_locks/acquirer.rb

@@ -4,7 +4,7 @@
 # @since 1.0.0
 module RedisQueuedLocks::Acquirer
   require_relative 'acquirer/acquire_lock'
-  require_relative 'acquirer/lock_series_poc'
+  require_relative 'acquirer/lock_series'
   require_relative 'acquirer/release_lock'
   require_relative 'acquirer/release_read_lock'
   require_relative 'acquirer/release_all_locks'

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.22.0
+# @version 1.23.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @return [RedisClient]
@@ -222,7 +222,7 @@ class RedisQueuedLocks::Client
   #     - `:wait_for_lock` - (default) - work in classic way
   #       (with timeouts, retry delays, retry limits, etc - in classic way :));
   #     - `:dead_locking` - fail with deadlock exception;
-  # @option read_write_mode [Symbol]
+  # @option rw_mode [Symbol]
   #   - The lock mode (read/write lock semantics);
   #   - `:write` mode is used by default;
   #   - Supports:
@@ -366,7 +366,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.22.0
+  # @version 1.23.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
@@ -381,7 +381,7 @@ class RedisQueuedLocks::Client
     raise_errors: false,
     fail_fast: false,
     conflict_strategy: config['default_conflict_strategy'],
-    read_write_mode: :write,
+    rw_mode: :write,
     access_strategy: config['default_access_strategy'],
     priority: config['default_lock_priority'],
     identity: uniq_identity,
@@ -422,7 +422,7 @@ class RedisQueuedLocks::Client
       identity:,
       fail_fast:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
       priority:,
       lock_priorities: config['lock_priorities'],
@@ -444,12 +444,41 @@ class RedisQueuedLocks::Client
   end
   # rubocop:enable Metrics/MethodLength
 
-  # NOTE: Lock Series PoC
+  # Obtains a series of locks atomically: all locks of the series are obtained at the same moment
+  # with the same ttl or none of them (nothing is held while the series waits for its locks).
+  # Lock series are deadlock-free for any order of the lock names.
+  #
+  # @param lock_names [Array<String>]
+  #   Lock names to be obtained (at least one; a duplicated name is the same lock).
+  # @option detailed_result [Boolean]
+  #   Return the detailed result of the series (the block result, times, lock keys).
+  # @option ttl [Integer]
+  #   The time to live of each lock of the series (in milliseconds). See `#lock`.
+  # @option timeout [Integer,NilClass]
+  #   Time period whe should try to acquire the whole series (in seconds). See `#lock`.
+  # @option retry_count [Integer,NilClass]
+  #   How many times we should try to acquire the whole series. See `#lock`.
+  # @option rw_mode [Symbol]
+  #   The mode of all locks of the series. See `#lock`.
+  # @option priority [Integer,Symbol]
+  #   The lock request priority of the series. See `#lock`.
+  # @yield A block of code that should be executed under all obtained locks.
+  # @yieldreturn [Any]
+  # @return [Hash<Symbol,Any>,yield]
+  #   - the result of the block when the series is obtained with a block;
+  #   - `{ ok: true, result: { lock_series:, rql_lock_series:, acq_id:, hst_id:, ts:, ttl: } }`
+  #     when the series is obtained without a block (the locks live till their ttl);
+  #   - the detailed result of the series with `detailed_result: true`;
+  #   - `{ ok: false, result: { error:, detailed_errors:, lock_series:, acquired_locks:,
+  #     missing_locks:, failed_on_lock: } }` when the series is not obtained;
+  #
+  # @note See #lock method signature for all other options.
+  #
   # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.16.0
-  # @version 1.22.0
-  def lock_series( # steep:ignore
+  # @version 1.23.0
+  def lock_series(
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
@@ -463,7 +492,7 @@ class RedisQueuedLocks::Client
     raise_errors: false,
     fail_fast: false,
     conflict_strategy: config['default_conflict_strategy'],
-    read_write_mode: :write,
+    rw_mode: :write,
     access_strategy: config['default_access_strategy'],
     priority: config['default_lock_priority'],
     identity: uniq_identity,
@@ -483,7 +512,7 @@ class RedisQueuedLocks::Client
     instr_sample_this: false,
     &block
   )
-    RedisQueuedLocks::Acquirer::LockSeriesPoC.lock_series_poc( # steep:ignore
+    RedisQueuedLocks::Acquirer::LockSeries.lock_series(
       redis_client,
       lock_names,
       detailed_result:,
@@ -505,7 +534,7 @@ class RedisQueuedLocks::Client
       identity:,
       fail_fast:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
       priority:,
       lock_priorities: config['lock_priorities'],
@@ -527,12 +556,13 @@ class RedisQueuedLocks::Client
   end
   # rubocop:enable Metrics/MethodLength
 
-  # NOTE: Lock Series PoC
+  # @note See #lock_series method signature.
+  #
   # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.16.0
-  # @version 1.22.0
-  def lock_series!( # steep:ignore
+  # @version 1.23.0
+  def lock_series!(
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
@@ -545,7 +575,7 @@ class RedisQueuedLocks::Client
     retry_jitter: config['retry_jitter'],
     fail_fast: false,
     conflict_strategy: config['default_conflict_strategy'],
-    read_write_mode: :write,
+    rw_mode: :write,
     access_strategy: config['default_access_strategy'],
     priority: config['default_lock_priority'],
     identity: uniq_identity,
@@ -565,8 +595,8 @@ class RedisQueuedLocks::Client
     instr_sample_this: false,
     &block
   )
-    lock_series( # steep:ignore
-      *lock_names, # steep:ignore
+    lock_series(
+      *lock_names,
       detailed_result:,
       ttl:,
       queue_ttl:,
@@ -579,7 +609,7 @@ class RedisQueuedLocks::Client
       raise_errors: true,
       fail_fast:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
       priority:,
       identity:,
@@ -607,7 +637,7 @@ class RedisQueuedLocks::Client
   # rubocop:disable Metrics/MethodLength
   # @api public
   # @since 1.0.0
-  # @version 1.22.0
+  # @version 1.23.0
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'],
@@ -620,7 +650,7 @@ class RedisQueuedLocks::Client
     retry_jitter: config['retry_jitter'],
     fail_fast: false,
     conflict_strategy: config['default_conflict_strategy'],
-    read_write_mode: :write,
+    rw_mode: :write,
     access_strategy: config['default_access_strategy'],
     priority: config['default_lock_priority'],
     identity: uniq_identity,
@@ -660,7 +690,7 @@ class RedisQueuedLocks::Client
       instrument:,
       instrumenter:,
       conflict_strategy:,
-      read_write_mode:,
+      rw_mode:,
       access_strategy:,
       priority:,
       log_sampling_enabled:,
@@ -952,7 +982,7 @@ class RedisQueuedLocks::Client
   # @param lock_name [String]
   # @param milliseconds [Integer]
   #   How many milliseconds should be added: a positive Integer.
-  # @option read_write_mode [Symbol]
+  # @option rw_mode [Symbol]
   #   - `:write` (default) - extends the write lock (the method description above);
   #   - `:read` - extends the read lock of the current acquirer only (an expired read lock or
   #     a read lock replaced by a writer is not extended);
@@ -981,11 +1011,11 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.21.0
+  # @version 1.23.0
   def extend_lock_ttl(
     lock_name,
     milliseconds,
-    read_write_mode: :write,
+    rw_mode: :write,
     all_read_locks: false,
     identity: uniq_identity,
     logger: config['logger'],
@@ -1004,7 +1034,7 @@ class RedisQueuedLocks::Client
       redis_client,
       lock_name,
       milliseconds,
-      read_write_mode,
+      rw_mode,
       all_read_locks,
       current_acquirer_id(identity:),
       config['lock_index_enabled'],

data/lib/redis_queued_locks/version.rb

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

data/redis_queued_locks.gemspec

@@ -14,20 +14,27 @@ Gem::Specification.new do |spec|
     'Distributed locks with "prioritized lock acquisition queue" ' \
     'capabilities based on the Redis Database.'
 
-  spec.description =
-    "|> Distributed locks with \"prioritized lock acquisition queue\" capabilities " \
-    "based on the Redis Database.\n" \
-    "|> Each lock request is put into the request queue " \
-    "(each lock is hosted by its own queue separately from other queues) and processed " \
-    "in order of their priority (FIFO).\n" \
-    "|> Each lock request lives some period of time (RTTL) " \
-    "(with requeue capabilities) which guarantees the request queue will never be stacked.\n" \
-    "|> In addition to the classic `queued` (FIFO) strategy RQL supports " \
-    "`random` (RANDOM) lock obtaining strategy when any acquirer from the lock queue " \
-    "can obtain the lock regardless the position in the queue.\n" \
-    "|> Provides flexible invocation flow, parametrized limits " \
-    "(lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), " \
-    "logging and instrumentation."
+  spec.description = <<~GEMSPEC_DESCRIPTION
+    RedisQueuedLocks (aka RQL, aka RQL-lock) - distributed locks with
+    "prioritized lock acquisition queue" capabilities based on the Redis Database.
+
+    Each lock request is put into the request queue
+    (each lock is hosted by its own queue separately from other queues)
+    and processed in order of their priority: requests of a higher priority go first,
+    requests of the same priority are processed in FIFO order.
+    Each lock request lives some period of time (RTTL) (with requeue capabilities)
+    which guarantees the request queue will never be stacked.
+
+    In addition to the classic queued (FIFO) strategy RQL supports random (RANDOM)
+    lock obtaining strategy when any acquirer from the lock queue
+    can obtain the lock regardless the position in the queue.
+
+    Supports lock request prioritization, Read/Write locks and Reentrant locks.
+
+    Provides flexible invocation flow, parametrized limits (lock request ttl, lock ttl,
+    queue ttl, lock attempts limit, fast failing, etc), zombie locks elimination,
+    lock indexing, logging and instrumentation (and much more).
+  GEMSPEC_DESCRIPTION
 
   spec.homepage = 'https://github.com/0exp/redis_queued_locks'
   spec.license = 'MIT'

data/sig/redis_queued_locks/acquirer/acquire_lock/dequeue_from_lock_queue.rbs

@@ -9,7 +9,7 @@ module RedisQueuedLocks
           RC::client redis,
           RQL::loggerObj logger,
           String lock_key,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           String lock_key_queue,
           String read_lock_key_queue,
           Integer queue_ttl,

data/sig/redis_queued_locks/acquirer/acquire_lock/try_to_lock.rbs

@@ -13,6 +13,9 @@ module RedisQueuedLocks
         LOCK_STATE_QUEUE_REPLIES_AT: Integer
         QUEUE_HEAD_REPLY: Integer
         OPPOSITE_QUEUE_HEAD_REPLY: Integer
+        QUEUE_REPLIES: Integer
+        QUEUE_LOCK_INDEX_REPLIES: Integer
+        READ_LOCK_EXTENSION_COMMANDS: Integer
         MAX_DEAD_REQUEST_REMOVALS: Integer
 
         # { ok: bool, result: Symbol }
@@ -35,7 +38,7 @@ module RedisQueuedLocks
           RQL::loggerObj logger,
           bool log_lock_try,
           String lock_key,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           String lock_key_queue,
           String read_lock_key_queue,
           String lock_readers_key,
@@ -60,6 +63,83 @@ module RedisQueuedLocks
 
         private
 
+        def same_process_conflict_status: (
+          RQL::conflictStrategy conflict_strategy,
+          bool lock_upgrade
+        ) -> Symbol
+
+        def transact_write_lock_extension: (
+          RedisClient::Multi transact,
+          String lock_key,
+          String lock_name,
+          Integer? ttl,
+          bool lock_index_enabled,
+          Float spc_processed_timestamp
+        ) -> void
+
+        def transact_read_lock_extension: (
+          RedisClient::Multi transact,
+          String lock_readers_key,
+          String? read_lock_key,
+          String lock_name,
+          String acquirer_id,
+          Integer? ttl,
+          bool lock_index_enabled,
+          Float? own_read_lock_expiration,
+          Integer redis_time,
+          Float spc_processed_timestamp
+        ) -> void
+
+        def transact_lock_index_extension: (
+          RedisClient::Multi transact,
+          String lock_name,
+          Integer? ttl,
+          bool lock_index_enabled
+        ) -> void
+
+        def transact_write_lock_work_through: (
+          RedisClient::Multi transact,
+          String lock_key,
+          Float spc_processed_timestamp
+        ) -> void
+
+        def transact_read_lock_work_through: (
+          RedisClient::Multi transact,
+          String? read_lock_key,
+          Float? own_read_lock_expiration,
+          Integer redis_time,
+          Float spc_processed_timestamp
+        ) -> void
+
+        def transact_read_lock_obtaining: (
+          RedisClient::Multi transact,
+          String request_queue,
+          String lock_readers_key,
+          String? read_lock_key,
+          String lock_name,
+          String acquirer_id,
+          Integer? ttl,
+          bool lock_index_enabled,
+          Integer lock_index_grace_period,
+          Hash[String|Symbol,untyped]? meta,
+          Integer redis_time,
+          Float timestamp
+        ) -> void
+
+        def transact_write_lock_obtaining: (
+          RedisClient::Multi transact,
+          String lock_key,
+          String request_queue,
+          String lock_name,
+          String acquirer_id,
+          String host_id,
+          Integer? ttl,
+          bool lock_index_enabled,
+          Integer lock_index_grace_period,
+          Hash[String|Symbol,untyped]? meta,
+          Float timestamp
+        ) -> void
+
         def queue_lock_request: (
           RedisClient::Pipeline pipeline,
           String request_queue,
@@ -135,7 +215,7 @@ module RedisQueuedLocks
           String acquirer_id,
           String host_id,
           RQL::accessStrategy access_strategy,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           String? waiting_acquirer,
           Integer? waiting_priority,
           [String, Float]? opposite_waiting_request,
@@ -150,7 +230,7 @@ module RedisQueuedLocks
 
         def drop_dead_requests_ahead: (
           RC::client rconn,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           String request_queue,
           String opposite_request_queue,
           String acquirer_id,
@@ -161,6 +241,27 @@ module RedisQueuedLocks
           [String, Float]? opposite_waiting_request
         ) -> [[String, Float]?, [String, Float]?, Array[[String, Integer]]]?
 
+        def find_dead_requests_ahead: (
+          bool read_mode,
+          RQL::accessStrategy access_strategy,
+          String acquirer_id,
+          Integer|Float acquirer_position,
+          Float acquirer_dead_score,
+          [String, Float]? waiting_request,
+          [String, Float]? opposite_waiting_request
+        ) -> [[String, Float]?, Integer?, [String, Float]?, Integer?]?
+
+        def pipeline_dead_requests_ahead_removal: (
+          RedisClient::Pipeline pipeline,
+          String request_queue,
+          String opposite_request_queue,
+          Float acquirer_dead_score,
+          [String, Float]? dead_head,
+          Integer? dead_head_priority,
+          [String, Float]? dead_ahead,
+          Integer? dead_ahead_priority
+        ) -> void
+
         def log_dropped_requests: (
           RQL::loggerObj logger,
           bool log_sampled,
@@ -170,7 +271,7 @@ module RedisQueuedLocks
           String acquirer_id,
           String host_id,
           RQL::accessStrategy access_strategy,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           Array[[String, Integer]] dropped_requests
         ) -> void
 
@@ -182,7 +283,7 @@ module RedisQueuedLocks
           bool log_sampled,
           bool log_lock_try,
           String lock_key,
-          RQL::readWriteMode read_write_mode,
+          RQL::readWriteMode rw_mode,
           String lock_readers_key,
           String request_queue,
           String opposite_request_queue,

data/sig/redis_queued_locks/acquirer/acquire_lock.rbs

@@ -38,7 +38,7 @@ module RedisQueuedLocks
         log_lock_try: bool,
         instrument: untyped?,
         conflict_strategy: RQL::conflictStrategy,
-        read_write_mode: Symbol, # NOTE: (rbs test) validated at runtime (Step 0.1 (RW)): any Symbol is accepted here
+        rw_mode: Symbol, # NOTE: (rbs test) validated at runtime (Step 0.1 (RW)): any Symbol is accepted here
         access_strategy: RQL::accessStrategy,
         priority: RQL::lockPriority,
         lock_priorities: Hash[Symbol, Integer],

data/sig/redis_queued_locks/acquirer/extend_lock_ttl.rbs

@@ -13,7 +13,7 @@ module RedisQueuedLocks
         RC::client redis_client,
         String lock_name,
         Integer milliseconds,
-        Symbol read_write_mode, # NOTE: (rbs test) validated at runtime: any Symbol is accepted here
+        Symbol rw_mode, # NOTE: (rbs test) validated at runtime: any Symbol is accepted here
         bool all_read_locks,
         String acquirer_id,
         bool lock_index_enabled,
@@ -35,7 +35,7 @@ module RedisQueuedLocks
         String lock_name,
         String lock_key,
         Integer milliseconds,
-        RQL::readWriteMode read_write_mode,
+        RQL::readWriteMode rw_mode,
         bool all_read_locks,
         String acquirer_id,
         bool lock_index_enabled

data/sig/redis_queued_locks/acquirer/lock_series/instr_visitor.rbs

@@ -0,0 +1,102 @@
+use RedisQueuedLocks as RQL
+
+module RedisQueuedLocks
+  module Acquirer
+    module LockSeries
+      module InstrVisitor
+        def self.lock_series_intermediate_lock_obtained: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          String lock_key,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          untyped? instrument
+        ) -> void
+
+        def self.lock_series_lock_obtained: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          String lock_key,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          untyped? instrument
+        ) -> void
+
+        def self.lock_series_lock_obtaining_failed: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          String lock_key,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          Symbol result,
+          untyped? instrument
+        ) -> void
+
+        def self.lock_series_obtained: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          Array[String] reentrant_lock_keys,
+          untyped? instrument
+        ) -> void
+
+        def self.lock_series_hold_and_release: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          Integer|Float hold_time,
+          Array[String] reentrant_lock_keys,
+          untyped? instrument
+        ) -> void
+
+        def self.lock_series_obtaining_failed: (
+          RQL::instrObj instrumenter,
+          bool instr_sampled,
+          Array[String] lock_keys,
+          RQL::readWriteMode rw_mode,
+          Integer priority,
+          Integer ttl,
+          String acq_id,
+          String hst_id,
+          Integer|Float ts,
+          Integer|Float acq_time,
+          Symbol result,
+          String? failed_lock_key,
+          untyped? instrument
+        ) -> void
+      end
+    end
+  end
+end