redis_queued_locks 1.19.0 → 1.20.0

data/lib/redis_queued_locks/acquirer/lock_series_poc.rb

@@ -14,7 +14,7 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
   class << self
     # @api private
     # @since 1.16.0
-    # @version 1.18.0
+    # @version 1.20.0
     def lock_series_poc( # steep:ignore
       redis,
       lock_names,
@@ -25,6 +25,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
       ractor_id:,
       ttl:,
       queue_ttl:,
+      lock_index_enabled:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -155,6 +157,8 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
               ractor_id:,
               ttl: lock_operation_options[:ttl],
               queue_ttl:,
+              lock_index_enabled:,
+              lock_index_grace_period:,
               timeout:,
               timed:,
               retry_count:,
@@ -357,7 +361,11 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     end
 
     # Releases write locks of the given acquirer (compare-and-delete: the lock can be expired
-    # and obtained by another acquirer when the series logic exceeds the lock ttl).
+    # and obtained by another acquirer when the series logic exceeds the lock ttl) in one
+    # transaction for the whole series (three round trips: WATCH, lock owners, MULTI/EXEC):
+    #   - an aborted transaction (one of the watched locks is changed) is retried with the locks
+    #     that were still owned by the acquirer at the last check: the locks of other acquirers
+    #     are neither deleted nor watched, so the retries converge;
     #
     # @param redis [RedisClient]
     # @param lock_names [Array<String>]
@@ -366,17 +374,28 @@ module RedisQueuedLocks::Acquirer::LockSeriesPoC # steep:ignore
     #
     # @api private
     # @since 1.18.0
+    # @version 1.20.0
     def release_write_lock_series(redis, lock_names, acquirer_id) # steep:ignore
       return if lock_names.empty?
 
+      own_lock_keys = lock_names.map do |lock_name|
+        RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+      end
+
       redis.with do |conn|
-        lock_names.each do |lock_name|
-          lock_key = RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
-          conn.multi(watch: [lock_key]) do |transaction|
-            if conn.call('HGET', lock_key, 'acq_id') == acquirer_id
-              transaction.call('DEL', lock_key)
+        until own_lock_keys.empty?
+          released = conn.multi(watch: own_lock_keys) do |transaction|
+            # NOTE: (pipeline layout) one reply (lock owner) per lock in the series order
+            lock_owners = conn.pipelined do |pipeline|
+              own_lock_keys.each { |lock_key| pipeline.call('HGET', lock_key, 'acq_id') }
+            end
+            own_lock_keys = own_lock_keys.select.with_index do |_lock_key, index|
+              lock_owners[index] == acquirer_id
             end
+            own_lock_keys.each { |lock_key| transaction.call('DEL', lock_key) }
           end
+          # NOTE: `nil` => the transaction is aborted (a watched lock is changed) => retry
+          break unless released.nil?
         end
       end
     end

data/lib/redis_queued_locks/acquirer/locks.rb

@@ -2,27 +2,42 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.20.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::Locks
+  # The number of replies of one lock in the lock state pipeline of a batch of locks
+  # (`extract_locks_info`): HGETALL (write lock), PTTL (write lock), ZRANGE (readers registry).
+  #
+  # @return [Integer]
+  #
+  # @api private
+  # @since 1.20.0
+  LOCK_STATE_REPLIES = 3
+
   # rubocop:disable Metrics/ClassLength
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
     # @option with_info [Boolean]
+    # @option lock_index_enabled [Boolean]
+    #   Find locks via the lock index (`index_locks`) instead of the keyspace SCAN (`scan_locks`).
     # @return [Set<String>,Set<Hash<Symbol,Any>>]
     #
     # @api private
     # @since 1.0.0
-    def locks(redis_client, scan_size:, with_info:)
+    # @version 1.20.0
+    def locks(redis_client, scan_size:, with_info:, lock_index_enabled:)
       redis_client.with do |rconn|
-        lock_keys = scan_locks(rconn, scan_size)
-        with_info ? extract_locks_info(rconn, lock_keys) : lock_keys
+        lock_keys =
+          lock_index_enabled ? index_locks(rconn, scan_size) : scan_locks(rconn, scan_size)
+        with_info ? extract_locks_info(rconn, lock_keys, scan_size) : lock_keys
       end
     end
 
     private
 
+    # Write locks and read locks in one SCAN pass (the disabled lock index).
+    #
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
     # @return [Set<String>]
@@ -30,88 +45,192 @@ module RedisQueuedLocks::Acquirer::Locks
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.20.0
     def scan_locks(redis_client, scan_size)
       Set.new.tap do |lock_keys|
+        # @type var lock_keys: Set[String]
         redis_client.scan(
           'MATCH',
-          RedisQueuedLocks::Resource::LOCK_PATTERN,
+          RedisQueuedLocks::Resource::KEY_PATTERN,
           count: scan_size
-        ) do |lock_key|
-          # TODO: reduce unnecessary iterations
-          lock_keys.add(lock_key)
+        ) do |key|
+          case RedisQueuedLocks::Resource.lock_key_family(key)
+          when :lock
+            lock_keys.add(key)
+          when :lock_readers
+            # NOTE: (RW) read locks (readers registries can contain expired read locks only)
+            lock_keys.add(RedisQueuedLocks::Resource.lock_key_from_readers(key))
+          end
         end
+      end
+    end
 
-        # NOTE: (RW) read locks (readers registries can contain expired read locks only)
-        redis_client.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::LOCK_READERS_PATTERN,
-          count: scan_size
-        ) do |lock_readers_key|
-          # TODO: reduce unnecessary iterations
-          lock_keys.add(RedisQueuedLocks::Resource.lock_key_from_readers(lock_readers_key))
+    # Write locks and read locks of the lock index (the enabled lock index): one ZSCAN pass over
+    # the lock names (`RedisQueuedLocks::Resource::LOCK_INDEX_KEY`, the keyspace is never scanned)
+    # with one round trip per batch of `scan_size` lock names (`EXISTS` of the write lock and of
+    # the readers registry of each lock name).
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer] ZSCAN count and the number of lock names in one batch.
+    # @return [Set<String>]
+    #   - (RW) read locks are represented by their lock keys (`rql:lock:<lock_name>`) too
+    #     (readers registries can contain expired read locks only);
+    #
+    # @api private
+    # @since 1.20.0
+    def index_locks(redis_client, scan_size)
+      Set.new.tap do |lock_keys|
+        # @type var lock_keys: Set[String]
+        each_lock_name_batch(redis_client, scan_size) do |lock_names|
+          # NOTE: (pipeline layout) one reply per lock name in the batch order: the number of
+          #   the existing keys of the lock (the write lock and the readers registry);
+          # @type var lock_keys_count: Array[Integer]
+          lock_keys_count = redis_client.pipelined do |pipeline|
+            lock_names.each do |lock_name|
+              pipeline.call(
+                'EXISTS',
+                RedisQueuedLocks::Resource.prepare_lock_key(lock_name),
+                RedisQueuedLocks::Resource.prepare_lock_readers(lock_name)
+              )
+            end
+          end
+
+          lock_names.each_with_index do |lock_name, index|
+            next if lock_keys_count[index] == 0
+
+            lock_keys.add(RedisQueuedLocks::Resource.prepare_lock_key(lock_name))
+          end
         end
       end
     end
 
+    # Iterates over the lock names of the lock index (one ZSCAN pass) in batches of `scan_size`
+    # lock names (batches are collected across ZSCAN pages). Expired lock names (not dropped from
+    # the index yet) are skipped: all their keys are expired.
+    #
+    # NOTE: each operation module iterates over the lock index by itself (duplicated on purpose:
+    #   operation modules are independent of each other, see `extract_locks_info`);
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer] ZSCAN count and the number of lock names in one batch.
+    # @yield [lock_names]
+    # @yieldparam lock_names [Array<String>] The batch of lock names (reused between batches).
+    # @return [void]
+    #
+    # @api private
+    # @since 1.20.0
+    def each_lock_name_batch(redis_client, scan_size)
+      lock_index_time = RedisQueuedLocks::Resource.lock_index_time
+      # @type var lock_names: Array[String]
+      lock_names = []
+
+      redis_client.zscan(
+        RedisQueuedLocks::Resource::LOCK_INDEX_KEY, count: scan_size
+      ) do |lock_name, lock_index_score|
+        next if lock_index_score.to_f < lock_index_time
+
+        lock_names << lock_name
+        next if lock_names.size < scan_size
+
+        yield(lock_names)
+        lock_names.clear
+      end
+
+      yield(lock_names) unless lock_names.empty?
+    end
+
     # NOTE:
     #   - the lock info is extracted by the module itself with the same approach as in `LockInfo`:
     #     public operation modules do not reuse each other (they share logic via `Resource`,
     #     `Utilities`), so the similar logic is duplicated on purpose;
+    #   - locks are processed in batches of `scan_size` locks: two round trips per batch
+    #     (the state of the locks, then the data of the live read locks);
     #
     # @param redis_client [RedisClient]
     # @param lock_keys [Set<String>]
+    # @param scan_size [Integer] The number of locks in one batch.
     # @return [Set<Hash<Symbol,Any>>]
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.20.0
     # rubocop:disable Metrics/MethodLength
-    def extract_locks_info(redis_client, lock_keys)
+    def extract_locks_info(redis_client, lock_keys, scan_size)
       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
+        lock_keys.each_slice(scan_size) do |lock_keys_batch|
+          # Step 1: extract the state of the batch of locks in one round trip
+          # NOTE: (pipeline layout) [0] TIME (read locks are checked in redis time), then
+          #   `LOCK_STATE_REPLIES` replies per lock in the batch order (the replies of the lock
+          #   with the index N start at `1 + N * LOCK_STATE_REPLIES`): HGETALL (write lock),
+          #   PTTL (write lock), ZRANGE WITHSCORES (readers registry);
+          # @type var batch_state: Array[untyped]
+          batch_state = redis_client.pipelined do |pipeline|
+            pipeline.call('TIME')
+            lock_keys_batch.each do |lock_key|
+              lock_readers_key = RedisQueuedLocks::Resource.prepare_lock_readers(
+                lock_key.delete_prefix('rql:lock:')
+              )
+              pipeline.call('HGETALL', lock_key)
+              pipeline.call('PTTL', lock_key)
+              pipeline.call('ZRANGE', lock_readers_key, '0', '-1', 'WITHSCORES')
+            end
+          end
+          now = RedisQueuedLocks::Resource.redis_time_ms(batch_state[0])
 
-          # NOTE: (RW) readers registry of the lock
-          lock_name = lock_key.delete_prefix('rql:lock:')
-          lock_readers_key = RedisQueuedLocks::Resource.prepare_lock_readers(lock_name)
+          # Step 2: (RW) live read locks of the locks without a write lock
+          #   (`nil` for the locks with a write lock: their read locks are not reported);
+          # @type var live_read_locks: Array[Array[[String, Float]]?]
+          live_read_locks = lock_keys_batch.each_with_index.map do |_lock_key, index|
+            replies_at = 1 + (index * LOCK_STATE_REPLIES)
+            # NOTE: `nil` when the write lock is alive (the key exists)
+            next unless batch_state[replies_at].empty? || batch_state[replies_at + 1] == -2
 
-          # @type var lock_info: RedisQueuedLocks::Acquirer::Locks::lockInfo
-          lock_info = redis_client.pipelined do |pipeline|
-            pipeline.call('HGETALL', lock_key)
-            pipeline.call('PTTL', lock_key)
-            pipeline.call('TIME')
-            pipeline.call('ZRANGE', lock_readers_key, '0', '-1', 'WITHSCORES')
-          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)
-
-              # rubocop:disable Layout/LineLength
-              # @type var result: [Hash[String,String|Float|Integer],Integer,Array[String],Array[[String, Float]]]
-              # rubocop:enable Layout/LineLength
-              hget_cmd_res = result[0] # NOTE: HGETALL result (hash)
-              pttl_cmd_res = result[1] # NOTE: PTTL result (integer)
-
-              # Step 2.Y: write lock is released
-              if hget_cmd_res == {} || pttl_cmd_res == -2 # NOTE: key does not exist
+            # @type var read_locks: Array[[String, Float]]
+            read_locks = batch_state[replies_at + 2]
+            read_locks.select { |(_acquirer_id, expiration)| expiration > now }
+          end
+
+          # Step 3: (RW) read lock data of the live read locks in one round trip
+          # NOTE: (pipeline layout) one reply per live read lock in the lock and reader order;
+          #   read lock data can be absent if it is dropped during the read lock life;
+          # @type var read_locks_data: Array[Hash[String,String]]
+          read_locks_data = redis_client.pipelined do |pipeline|
+            lock_keys_batch.each_with_index do |lock_key, index|
+              lock_name = lock_key.delete_prefix('rql:lock:')
+              live_read_locks[index]&.each do |(acquirer_id, _expiration)|
+                pipeline.call(
+                  'HGETALL',
+                  RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+                )
+              end
+            end
+          end
+
+          # Step 4: format the info of each lock and push it to the result store
+          read_locks_data_at = 0
+          lock_keys_batch.each_with_index do |lock_key, index|
+            lock_live_read_locks = live_read_locks[index]
+
+            # @type var lock_info: RedisQueuedLocks::Acquirer::Locks::lockInfo
+            lock_info =
+              if lock_live_read_locks
+                # Step 4.Y: write lock is released
                 # NOTE: (RW) read locks (or nothing if there are no live read locks)
                 read_lock_info(
-                  redis_client, lock_name, lock_key, result[2], result[3]
+                  lock_key, now, lock_live_read_locks, read_locks_data, read_locks_data_at
                 ) || {} #: Hash[String,String|Float|Integer]
               else
-                # Step 2.Z: lock is alive => format received info + add additional rem_ttl info
+                # Step 4.Z: lock is alive => format received info + add additional rem_ttl info
+                replies_at = 1 + (index * LOCK_STATE_REPLIES)
+                # @type var hget_cmd_res: Hash[String,String|Float|Integer]
+                hget_cmd_res = batch_state[replies_at] # NOTE: HGETALL result (hash)
+                # @type var pttl_cmd_res: Integer
+                pttl_cmd_res = batch_state[replies_at + 1] # NOTE: PTTL result (integer)
+
                 hget_cmd_res.tap do |lock_data|
                   lock_data['rw_mode'] = 'write'
                   lock_data['ts'] = Float(lock_data['ts'])
@@ -127,30 +246,30 @@ module RedisQueuedLocks::Acquirer::Locks
                     Float(lock_data['l_spc_ext_ts']) if lock_data['l_spc_ext_ts']
                 end
               end
-            end
-          end
+            read_locks_data_at += lock_live_read_locks.size if lock_live_read_locks
 
-          # Step 3: push the lock info to the result store
-          seeded_locks << {
-            lock: lock_key,
-            status: (lock_info.empty? ? :released : :alive),
-            info: lock_info
-          }
+            seeded_locks << {
+              lock: lock_key,
+              status: (lock_info.empty? ? :released : :alive),
+              info: lock_info
+            }
+          end
         end
       end
     end
     # rubocop:enable Metrics/MethodLength
 
-    # Formats live read locks of the lock (expired read locks are ignored).
+    # Formats live read locks of the lock.
     #
     # NOTE: the same approach as in `LockInfo` (duplicated on purpose: operation modules are
-    #   independent of each other, see `extract_locks_info`);
+    #   independent of each other, see `extract_locks_info`); the read lock data is extracted
+    #   for the whole batch of locks in advance;
     #
-    # @param redis_client [RedisClient]
-    # @param lock_name [String]
     # @param lock_key [String]
-    # @param redis_time [Array<String>] Result of the redis `TIME` command.
-    # @param read_locks [Array<Array<String,Float>>] Readers registry (acquirer id, expiration).
+    # @param now [Integer] Redis time (in milliseconds).
+    # @param live_read_locks [Array<Array<String,Float>>] Live read locks (acquirer id, expiration).
+    # @param read_locks_data [Array<Hash<String,String>>] Read lock data of the batch of locks.
+    # @param read_locks_data_at [Integer] Position of the first read lock data of the lock.
     # @return [Hash<String,String|Numeric|Array<Hash<String,String|Numeric>>>,NilClass]
     #   - `nil` is returned when there are no live read locks;
     #   - each reader has the same data as the write lock (acq_id, hst_id, ts, ini_ttl, rem_ttl,
@@ -158,32 +277,25 @@ module RedisQueuedLocks::Acquirer::Locks
     #
     # @api private
     # @since 1.18.0
+    # @version 1.20.0
     # rubocop:disable Metrics/MethodLength
-    def read_lock_info(redis_client, lock_name, lock_key, redis_time, read_locks)
-      now = RedisQueuedLocks::Resource.redis_time_ms(redis_time)
-      live_read_locks = read_locks.select { |(_acquirer_id, expiration)| expiration > now }
+    def read_lock_info(lock_key, now, live_read_locks, read_locks_data, read_locks_data_at)
       return nil if live_read_locks.empty?
 
-      # NOTE: read lock data (it can be absent if it is dropped during the read lock life)
-      # @type var read_locks_data: Array[Hash[String,String]]
-      read_locks_data = redis_client.pipelined do |pipeline|
-        live_read_locks.each do |(acquirer_id, _expiration)|
-          pipeline.call(
-            'HGETALL',
-            RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
-          )
-        end
-      end
-
       longest_rem_ttl = 0
       readers = live_read_locks.each_with_index.map do |(acquirer_id, expiration), index|
         rem_ttl = (expiration - now).ceil
         longest_rem_ttl = rem_ttl if rem_ttl > longest_rem_ttl
 
+        # NOTE: acquirer and host ids are not stored in the read lock data (both are derived from
+        #   the acquirer id): they are the first fields like in the write lock info (read lock data
+        #   of older versions contains them with the same values);
         # @type var reader: Hash[String,String|Float|Integer|nil]
-        reader = read_locks_data[index] || {}
-        reader['acq_id'] = acquirer_id
-        reader['hst_id'] ||= RedisQueuedLocks::Resource.host_identifier_from_acquirer(acquirer_id)
+        reader = {
+          'acq_id' => acquirer_id,
+          'hst_id' => RedisQueuedLocks::Resource.host_identifier_from_acquirer(acquirer_id)
+        }
+        read_locks_data[read_locks_data_at + index]&.each { |field, value| reader[field] = value }
         reader['ts'] = Float(reader['ts']) if reader['ts']
         reader['ini_ttl'] = Integer(reader['ini_ttl']) if reader['ini_ttl']
         reader['rem_ttl'] = rem_ttl

data/lib/redis_queued_locks/acquirer/queue_info.rb

@@ -2,14 +2,13 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.20.0
 module RedisQueuedLocks::Acquirer::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.
+    # lock acquirers and their position in queue. The write lock queue is empty when only
+    # the queue of read lock requests exists.
     #
     # @param redis_client [RedisClient]
     # @param lock_name [String]
@@ -33,28 +32,24 @@ module RedisQueuedLocks::Acquirer::QueueInfo
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
-    # rubocop:disable Metrics/MethodLength
+    # @version 1.20.0
     def queue_info(redis_client, lock_name)
       lock_key_queue = RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
       read_lock_key_queue = RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
 
+      # NOTE:
+      #   redis deletes empty sorted sets, so an empty ZRANGE result means that the queue
+      #   does not exist (no need for EXISTS checks);
       result = redis_client.pipelined do |pipeline|
-        pipeline.call('EXISTS', lock_key_queue)
         pipeline.call('ZRANGE', lock_key_queue, '0', '-1', 'WITHSCORES')
-        pipeline.call('EXISTS', read_lock_key_queue)
         pipeline.call('ZRANGE', read_lock_key_queue, '0', '-1', 'WITHSCORES')
       end
 
-      # rubocop:disable Layout/LineLength
-      # @type var result: [Integer,Array[[String,Integer|Float]],Integer,Array[[String,Integer|Float]]]
-      # rubocop:enable Layout/LineLength
-      exists_cmd_res = result[0]
-      zrange_cmd_res = result[1]
-      read_exists_cmd_res = result[2]
-      read_zrange_cmd_res = result[3]
+      # @type var result: [Array[[String,Integer|Float]],Array[[String,Integer|Float]]]
+      zrange_cmd_res = result[0]
+      read_zrange_cmd_res = result[1]
 
-      if exists_cmd_res == 1 || read_exists_cmd_res == 1
+      if !zrange_cmd_res.empty? || !read_zrange_cmd_res.empty?
         # NOTE: queue existed during the piepline invocation
         # @type var queue_info: RedisQueuedLocks::Acquirer::QueueInfo::queueInfo
         queue_info = {
@@ -64,7 +59,7 @@ module RedisQueuedLocks::Acquirer::QueueInfo
           end
         }
         # NOTE: (RW) the queue of read lock requests
-        if read_exists_cmd_res == 1
+        unless read_zrange_cmd_res.empty?
           queue_info['read_lock_queue'] = read_lock_key_queue
           queue_info['read_queue'] = read_zrange_cmd_res.map do |val|
             { 'acq_id' => val[0], 'score' => val[1], 'rw_mode' => 'read' }
@@ -76,6 +71,5 @@ module RedisQueuedLocks::Acquirer::QueueInfo
         nil
       end
     end
-    # rubocop:enable Metrics/MethodLength
   end
 end