redis_queued_locks 1.19.0 → 1.21.0

data/lib/redis_queued_locks/acquirer/queues.rb

@@ -2,25 +2,41 @@
 
 # @api private
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.20.0
 module RedisQueuedLocks::Acquirer::Queues
   class << self
     # @param redis_client [RedisClient]
     # @option scan_size [Integer]
     # @option with_info [Boolean]
+    # @option lock_index_enabled [Boolean]
+    #   Find lock queues via the lock index (`index_queues`) instead of the keyspace SCAN
+    #   (`scan_queues`).
     # @return [Set<String>,Set<Hash<Symbol,Any>>]
     #
     # @api private
     # @since 1.0.0
-    def queues(redis_client, scan_size:, with_info:)
+    # @version 1.21.0
+    def queues(redis_client, scan_size:, with_info:, lock_index_enabled:)
+      # NOTE: (arguments) the same range as the config key: zero/negative sizes fail SCAN/ZSCAN
+      #   (`COUNT 0`) and the batching (`each_slice(0)`);
+      if !scan_size.is_a?(::Integer) || scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:scan_size` argument should be a positive Integer, got #{scan_size.inspect}."
+        )
+      end
+
       redis_client.with do |rconn|
-        lock_queues = scan_queues(rconn, scan_size)
-        with_info ? extract_queues_info(rconn, lock_queues) : lock_queues
+        lock_queues =
+          lock_index_enabled ? index_queues(rconn, scan_size) : scan_queues(rconn, scan_size)
+        with_info ? extract_queues_info(rconn, lock_queues, scan_size) : lock_queues
       end
     end
 
     private
 
+    # Write and read lock queues in one SCAN pass (the disabled lock index).
+    #
     # @param redis_client [RedisClient]
     # @param scan_size [Integer]
     # @return [Set<String>]
@@ -28,80 +44,137 @@ module RedisQueuedLocks::Acquirer::Queues
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.20.0
     def scan_queues(redis_client, scan_size)
       Set.new.tap do |lock_queues|
         # @type var lock_queues: Set[String]
         redis_client.scan(
           'MATCH',
-          RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
+          RedisQueuedLocks::Resource::ALL_LOCK_QUEUES_PATTERN,
           count: scan_size
-        ) do |lock_queue|
-          # TODO: reduce unnecessary iterations
-          # @type var lock_queue: String
-          lock_queues.add(lock_queue)
+        ) do |key|
+          # NOTE: the pattern matches other keys too (lock names with `queue:`): lock queues only
+          family = RedisQueuedLocks::Resource.lock_key_family(key)
+          lock_queues.add(key) if family == :lock_queue || family == :read_lock_queue
         end
+      end
+    end
 
-        # NOTE: (RW) queues of read lock requests
-        redis_client.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::READ_LOCK_QUEUE_PATTERN,
-          count: scan_size
-        ) do |read_lock_queue|
-          # TODO: reduce unnecessary iterations
-          # @type var read_lock_queue: String
-          lock_queues.add(read_lock_queue)
+    # Write and read lock queues 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 both lock queues 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) queues of read lock requests are included;
+    #
+    # @api private
+    # @since 1.20.0
+    def index_queues(redis_client, scan_size)
+      Set.new.tap do |lock_queues|
+        # @type var lock_queues: Set[String]
+        each_lock_name_batch(redis_client, scan_size) do |lock_names|
+          # NOTE: (pipeline layout) two replies per lock name in the batch order:
+          #   EXISTS (write lock queue), EXISTS (read lock queue);
+          # @type var queues_existence: Array[Integer]
+          queues_existence = redis_client.pipelined do |pipeline|
+            lock_names.each do |lock_name|
+              pipeline.call('EXISTS', RedisQueuedLocks::Resource.prepare_lock_queue(lock_name))
+              pipeline.call(
+                'EXISTS', RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
+              )
+            end
+          end
+
+          lock_names.each_with_index do |lock_name, index|
+            if queues_existence[index * 2] == 1
+              lock_queues.add(RedisQueuedLocks::Resource.prepare_lock_queue(lock_name))
+            end
+            if queues_existence[(index * 2) + 1] == 1
+              lock_queues.add(RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name))
+            end
+          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 `Locks.each_lock_name_batch`);
+    #
+    # @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
+
     # @param redis_client [RedisClient]
     # @param lock_queues [Set<String>]
+    # @param scan_size [Integer] The number of queues whose requests are read in one round trip.
     # @return [Set<Hash<Symbol,Any>>]
     #   - each request: `{ 'acq_id' => String, 'score' => Float, 'rw_mode' => 'read'/'write' }`;
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
-    def extract_queues_info(redis_client, lock_queues)
+    # @version 1.20.0
+    def extract_queues_info(redis_client, lock_queues, scan_size)
       # NOTE: the same approach as in `QueueInfo` (duplicated on purpose: public operation modules
       #   do not reuse each other, they share logic via `Resource`, `Utilities`);
       Set.new.tap do |seeded_queues|
-        # Step X: iterate over each lock queue and extract their info
         # @type var seeded_queues: Set[Hash[Symbol,untyped]]
-        lock_queues.each do |lock_queue|
-          # NOTE:
-          #   - (RW) the mode of the requests of the queue (`'read'` or `'write'`);
-          #   - lock queues are scanned by the lock queue patterns, so the mode is never `nil`;
-          rw_mode = RedisQueuedLocks::Resource.lock_queue_rw_mode(lock_queue) #: String
-
-          # Step 1: extract lock queue info from reids
-          queue_info = redis_client.pipelined do |pipeline|
-            pipeline.call('EXISTS', lock_queue)
-            pipeline.call('ZRANGE', lock_queue, '0', '-1', 'WITHSCORES')
-          end.yield_self do |result| # Step 2: format the result
-            # @type var result: [Integer, Array[[String,Float]]]
+        lock_queues.each_slice(scan_size) do |lock_queues_batch|
+          # Step 1: extract the requests of the batch of lock queues in one round trip
+          #   - redis deletes empty sorted sets, so a queue that does not exist anymore gives
+          #     an empty ZRANGE result (no need for EXISTS checks);
+          #   - (pipeline layout) one reply per queue in the batch order;
+          # @type var queues_requests: Array[Array[[String,Float]]]
+          queues_requests = redis_client.pipelined do |pipeline|
+            lock_queues_batch.each do |lock_queue|
+              pipeline.call('ZRANGE', lock_queue, '0', '-1', 'WITHSCORES')
+            end
+          end
 
-            exists_cmd_res = result[0]
-            zrange_cmd_res = result[1]
+          lock_queues_batch.each_with_index do |lock_queue, index|
+            # NOTE:
+            #   - (RW) the mode of the requests of the queue (`'read'` or `'write'`);
+            #   - lock queues are scanned by the lock queue patterns, so the mode is never `nil`;
+            rw_mode = RedisQueuedLocks::Resource.lock_queue_rw_mode(lock_queue) #: String
 
-            if exists_cmd_res == 1 # Step 2.X: lock queue existed during the piepline invocation
-              zrange_cmd_res.map do |val|
+            # Step 2: format the result and push it to the result store
+            seeded_queues << {
+              queue: lock_queue,
+              requests: queues_requests[index].map do |val|
                 { 'acq_id' => val[0], 'score' => val[1], 'rw_mode' => rw_mode }
               end
-            else
-              # Step 2.Y: lock queue did not exist during the pipeline invocation
-              [] #: Array[Hash[String,String|Float]]
-            end
+            }
           end
-
-          # @type var queue_info: Array[Hash[String,String|Float]]
-
-          # Step 3: push the lock queue info to the result store
-          seeded_queues << {
-            queue: lock_queue,
-            requests: queue_info
-          }
         end
       end
     end

data/lib/redis_queued_locks/acquirer/reindex_locks.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.20.0
+# @version 1.21.0
+# rubocop:disable Metrics/ModuleLength
+module RedisQueuedLocks::Acquirer::ReindexLocks
+  # @since 1.21.0
+  extend RedisQueuedLocks::Utilities
+
+  # rubocop:disable Metrics/ClassLength
+  class << self
+    # Adds the lock keys without the lock index entry (keys of older RQL versions created before
+    # the lock index) to the lock index (`RedisQueuedLocks::Resource::LOCK_INDEX_KEY`):
+    #   - one SCAN pass over the RQL keys (`KEY_PATTERN`) with pipelined batches of `scan_size`
+    #     keys collected across SCAN pages (two round trips per batch: key TTLs, then the index);
+    #   - write locks and readers registries are indexed with their remaining TTL (`PTTL`):
+    #     the score is the client time + the remaining TTL + the grace period;
+    #   - lock queues without TTL (older RQL versions) get the queue TTL first (`PEXPIRE NX`):
+    #     the lifetime of every indexed key is bounded;
+    #   - read lock data is not indexed: it is found via its readers registry;
+    #   - keys without TTL (unreachable for RQL keys) are indexed forever (`+inf` score);
+    #   - the index score is never decreased (`ZADD GT`): the operation is idempotent and can be
+    #     invoked at any time (keys of the current RQL version are indexed already);
+    #   - the operation is reported with one log and one instrumentation event
+    #     (`redis_queued_locks.reindex_locks`) with the time of the whole operation;
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @param queue_ttl [Integer] TTL of the lock queues without TTL (in seconds).
+    # @param lock_index_grace_period [Integer]
+    #   The lock index score margin over the key lifetime (in milliseconds).
+    # @param logger [::Logger,#debug]
+    # @param instrumenter [#notify]
+    # @param instrument [NilClass,Any]
+    # @param log_sampling_enabled [Boolean]
+    # @param log_sampling_percent [Integer]
+    # @param log_sampler [#sampling_happened?,Module<RedisQueuedLocks::Logging::Sampler>]
+    # @param log_sample_this [Boolean]
+    # @param instr_sampling_enabled [Boolean]
+    # @param instr_sampling_percent [Integer]
+    # @param instr_sampler [#sampling_happened?,Module<RedisQueuedLocks::Instrument::Sampler>]
+    # @param instr_sample_this [Boolean]
+    # @return [Hash<Symbol,Boolean|Hash<Symbol,Integer>>]
+    #   Format: { ok: true, result: { idx_key_cnt: Integer } } (the number of indexed keys)
+    #
+    # @api private
+    # @since 1.20.0
+    # @version 1.21.0
+    # rubocop:disable Metrics/MethodLength
+    def reindex_locks(
+      redis_client,
+      scan_size,
+      queue_ttl,
+      lock_index_grace_period,
+      logger,
+      instrumenter,
+      instrument,
+      log_sampling_enabled,
+      log_sampling_percent,
+      log_sampler,
+      log_sample_this,
+      instr_sampling_enabled,
+      instr_sampling_percent,
+      instr_sampler,
+      instr_sample_this
+    )
+      # NOTE: (arguments) the same ranges as the config keys: zero/negative sizes fail SCAN
+      #   (`COUNT 0`), a non-positive queue ttl expires the lock queues without TTL at once;
+      if !scan_size.is_a?(::Integer) || scan_size <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:scan_size` argument should be a positive Integer, got #{scan_size.inspect}."
+        )
+      end
+      if !queue_ttl.is_a?(::Integer) || queue_ttl <= 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:queue_ttl` argument should be a positive Integer, got #{queue_ttl.inspect}."
+        )
+      end
+      if !lock_index_grace_period.is_a?(::Integer) || lock_index_grace_period < 0
+        raise(
+          RedisQueuedLocks::ArgumentError,
+          "`:lock_index_grace_period` argument should be a non-negative Integer, " \
+          "got #{lock_index_grace_period.inspect}."
+        )
+      end
+
+      idx_start_time = clock_gettime
+      idx_key_cnt = fully_reindex_locks(redis_client, scan_size, queue_ttl, lock_index_grace_period)
+      time_at = Time.now.to_f
+      idx_end_time = clock_gettime
+      idx_time = ((idx_end_time - idx_start_time) / 1_000.0).ceil(2)
+
+      log_sampled = RedisQueuedLocks::Logging.should_log?(
+        log_sampling_enabled,
+        log_sample_this,
+        log_sampling_percent,
+        log_sampler
+      )
+      instr_sampled = RedisQueuedLocks::Instrument.should_instrument?(
+        instr_sampling_enabled,
+        instr_sample_this,
+        instr_sampling_percent,
+        instr_sampler
+      )
+
+      run_non_critical do
+        logger.debug do
+          "[redis_queued_locks.reindex_locks] " \
+          "idx_key_cnt => #{idx_key_cnt} " \
+          "idx_time => #{idx_time} " \
+          "at => #{time_at}"
+        end
+      end if log_sampled
+
+      run_non_critical do
+        instrumenter.notify('redis_queued_locks.reindex_locks', {
+          idx_key_cnt: idx_key_cnt,
+          idx_time: idx_time,
+          at: time_at,
+          instrument: instrument
+        })
+      end if instr_sampled
+
+      { ok: true, result: { idx_key_cnt: } }
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    private
+
+    # Adds the lock keys without the lock index entry to the lock index (see `reindex_locks`).
+    #
+    # @param redis_client [RedisClient]
+    # @param scan_size [Integer]
+    # @param queue_ttl [Integer] TTL of the lock queues without TTL (in seconds).
+    # @param lock_index_grace_period [Integer]
+    # @return [Integer] The number of indexed keys.
+    #
+    # @api private
+    # @since 1.21.0
+    def fully_reindex_locks(redis_client, scan_size, queue_ttl, lock_index_grace_period)
+      # NOTE: `ceil` - queue ttl can be passed as a Float (in seconds), PEXPIRE requires Integer
+      queue_pttl = (queue_ttl * 1_000).ceil
+      idx_key_cnt = 0
+
+      redis_client.with do |rconn|
+        # NOTE: write locks and readers registries of the batch
+        # @type var lock_keys: Array[String]
+        lock_keys = []
+        # @type var lock_queues: Array[String]
+        lock_queues = []
+
+        rconn.scan('MATCH', RedisQueuedLocks::Resource::KEY_PATTERN, count: scan_size) do |key|
+          case RedisQueuedLocks::Resource.lock_key_family(key)
+          when :lock, :lock_readers then lock_keys << key
+          when :lock_queue, :read_lock_queue then lock_queues << key
+          else next # NOTE: read lock data and keys out of the lock key families
+          end
+          next if (lock_keys.size + lock_queues.size) < scan_size
+
+          idx_key_cnt += index_lock_keys(
+            rconn, lock_keys, lock_queues, queue_pttl, lock_index_grace_period
+          )
+          lock_keys.clear
+          lock_queues.clear
+        end
+
+        unless lock_keys.empty? && lock_queues.empty?
+          idx_key_cnt += index_lock_keys(
+            rconn, lock_keys, lock_queues, queue_pttl, lock_index_grace_period
+          )
+        end
+      end
+
+      idx_key_cnt
+    end
+
+    # Adds the given batch of lock keys to the lock index (two round trips: key TTLs, then
+    # the index entries).
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_keys [Array<String>] Write locks and readers registries.
+    # @param lock_queues [Array<String>] Lock queues (write and read).
+    # @param queue_pttl [Integer] TTL of the lock queues without TTL (in milliseconds).
+    # @param lock_index_grace_period [Integer] In milliseconds.
+    # @return [Integer] The number of indexed keys (keys deleted after the SCAN are not indexed).
+    #
+    # @api private
+    # @since 1.20.0
+    def index_lock_keys(redis_client, lock_keys, lock_queues, queue_pttl, lock_index_grace_period)
+      # NOTE: (pipeline layout) `PEXPIRE NX` + `PTTL` for each lock queue (two replies per queue),
+      #   then `PTTL` for each lock key, in the batch order;
+      # @type var key_ttls: Array[Integer]
+      key_ttls = redis_client.pipelined do |pipeline|
+        lock_queues.each do |lock_queue|
+          pipeline.call('PEXPIRE', lock_queue, queue_pttl, 'NX')
+          pipeline.call('PTTL', lock_queue)
+        end
+        lock_keys.each { |lock_key| pipeline.call('PTTL', lock_key) }
+      end
+      # NOTE: the client time after the TTLs are received: the score is not less than the key
+      #   expiration time (+ the grace period for the client clock skew);
+      lock_index_time = RedisQueuedLocks::Resource.lock_index_time
+      indexed_keys_count = 0
+
+      redis_client.pipelined do |pipeline|
+        lock_queues.each_with_index do |lock_queue, index|
+          indexed_keys_count += index_lock_key(
+            pipeline, lock_queue, key_ttls[(index * 2) + 1], lock_index_time,
+            lock_index_grace_period
+          )
+        end
+        lock_keys.each_with_index do |lock_key, index|
+          indexed_keys_count += index_lock_key(
+            pipeline, lock_key, key_ttls[(lock_queues.size * 2) + index], lock_index_time,
+            lock_index_grace_period
+          )
+        end
+      end
+
+      indexed_keys_count
+    end
+
+    # Adds the lock name of the given key to the lock index (`ZADD GT`).
+    #
+    # @param pipeline [RedisClient::Pipeline]
+    # @param key [String] Write lock, readers registry or lock queue.
+    # @param key_ttl [Integer] The remaining key TTL (`PTTL`: `-2` - no key, `-1` - no TTL).
+    # @param lock_index_time [Integer] Epoch, in milliseconds.
+    # @param lock_index_grace_period [Integer] In milliseconds.
+    # @return [Integer] `1` - the key is indexed, `0` - the key does not exist anymore.
+    #
+    # @api private
+    # @since 1.20.0
+    def index_lock_key(pipeline, key, key_ttl, lock_index_time, lock_index_grace_period)
+      return 0 if key_ttl == -2
+
+      lock_name = RedisQueuedLocks::Resource.lock_name_from_key(
+        key, RedisQueuedLocks::Resource.lock_key_family(key)
+      )
+      lock_index_score =
+        (key_ttl == -1) ? '+inf' : (lock_index_time + key_ttl + lock_index_grace_period)
+      pipeline.call(
+        'ZADD', RedisQueuedLocks::Resource::LOCK_INDEX_KEY, 'GT', lock_index_score, lock_name
+      )
+      1
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end
+# rubocop:enable Metrics/ModuleLength