redis_queued_locks 1.18.0 → 1.20.0

data/lib/redis_queued_locks/acquirer/release_lock.rb

@@ -12,6 +12,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #      from the lock aquierment and should retry;
     # - 2. delete the lock: drop lock key from Redis;
     # - 3. (RW) clear the read lock queue and drop all read locks (the readers registry);
+    # - 4. (lock index) drop the lock name from the lock index (the enabled lock index only);
     # It is safe because the lock obtain logic is transactional and
     # watches the original lock for changes.
     #
@@ -19,6 +20,8 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #   Redis connection client.
     # @param lock_name [String]
     #   The lock name that should be released.
+    # @param lock_index_enabled [Boolean]
+    #   Drop the lock name from the lock index (the enabled lock index).
     # @param instrumenter [#notify]
     #   See RedisQueuedLocks::Instrument::ActiveSupport for example.
     # @param logger [::Logger,#debug]
@@ -72,11 +75,12 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.20.0
     # rubocop:disable Metrics/MethodLength
     def release_lock(
       redis,
       lock_name,
+      lock_index_enabled,
       instrumenter,
       logger,
       log_sampling_enabled,
@@ -96,7 +100,8 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
       rel_start_time = clock_gettime
       # steep:ignore:start
       fully_release_lock(
-        redis, lock_name, lock_key, lock_key_queue, read_lock_key_queue, lock_readers_key
+        redis, lock_name, lock_key, lock_key_queue, read_lock_key_queue, lock_readers_key,
+        lock_index_enabled
       ) => { ok:, result: }
       # steep:ignore:end
 
@@ -138,7 +143,8 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
 
     private
 
-    # Realease the lock: clear the lock queues and expire the lock (write lock and read locks).
+    # Realease the lock: clear the lock queues and expire the lock (write lock and read locks),
+    # drop the lock name from the lock index (the enabled lock index).
     #
     # @param redis [RedisClient]
     # @param lock_name [String]
@@ -146,6 +152,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     # @param lock_key_queue [String]
     # @param read_lock_key_queue [String]
     # @param lock_readers_key [String]
+    # @param lock_index_enabled [Boolean]
     # @return [Hash<Symbol,Boolean|Hash<Symbol,Symbol>>]
     #   Format: {
     #     ok: true/false,
@@ -157,43 +164,69 @@ module RedisQueuedLocks::Acquirer::ReleaseLock
     #
     # @api private
     # @since 1.0.0
-    # @version 1.18.0
+    # @version 1.20.0
+    # rubocop:disable Metrics/MethodLength
     def fully_release_lock(
       redis,
       lock_name,
       lock_key,
       lock_key_queue,
       read_lock_key_queue,
-      lock_readers_key
+      lock_readers_key,
+      lock_index_enabled
     )
-      # @type var result: [Integer,Integer,Integer,Integer]
+      # @type var result: [Array[String],Integer,Integer,Integer,Integer]
       result = redis.with do |rconn|
-        # NOTE: (RW) data of read locks (it is a data carrier only: read locks are released via
-        #   the readers registry, so the data of concurrently obtained read locks expires itself)
-        # @type var read_lock_acquirers: Array[String]
-        read_lock_acquirers = rconn.call('ZRANGE', lock_readers_key, '0', '-1')
-
-        rconn.multi do |transact|
+        # Step 1: release the lock in one transaction (one round trip):
+        #   - (RW) the readers registry is read in the same transaction: the snapshot of all
+        #     released read locks (their data is dropped in Step 2);
+        #   - (lock index) the enabled lock index: all the indexed keys of the lock are dropped,
+        #     so the lock name is dropped from the lock index in the same transaction (a lock
+        #     request queued or a lock obtained after this transaction indexes the lock name again);
+        # NOTE: (transaction layout) replies are read by their positions:
+        #   [0] ZRANGE (released read locks), [1] write lock queue, [2] write lock,
+        #   [3] read lock queue, [4] readers registry, [5] lock index (the enabled lock index
+        #   only, the last command: not read);
+        released = rconn.multi do |transact|
+          transact.call('ZRANGE', lock_readers_key, '0', '-1')
           transact.call('ZREMRANGEBYSCORE', lock_key_queue, '-inf', '+inf')
           transact.call('EXPIRE', lock_key, '0')
           transact.call('ZREMRANGEBYSCORE', read_lock_key_queue, '-inf', '+inf')
           transact.call('EXPIRE', lock_readers_key, '0')
-          read_lock_acquirers.each do |acquirer_id|
-            transact.call(
-              'DEL',
-              RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
-            )
+          if lock_index_enabled
+            transact.call('ZREM', RedisQueuedLocks::Resource::LOCK_INDEX_KEY, lock_name)
           end
         end
+
+        # Step 2: (RW) drop the data of the released read locks (only when read locks existed)
+        # NOTE:
+        #   - the read lock data is a data carrier only: read locks are released via the readers
+        #     registry (Step 1);
+        #   - (trade-off) a reader of the snapshot that obtains a new read lock between Step 1 and
+        #     Step 2 loses the data of the new read lock (meta, timestamps); the read lock itself is
+        #     not affected (the readers registry is the source of truth);
+        # @type var read_lock_acquirers: Array[String]
+        read_lock_acquirers = released[0]
+        unless read_lock_acquirers.empty?
+          rconn.call(
+            'DEL',
+            *read_lock_acquirers.map do |acquirer_id|
+              RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+            end
+          )
+        end
+
+        released
       end
 
       {
         ok: true,
         result: {
-          queue: (result[0] != 0 || result[2] != 0) ? :released : :nothing_to_release,
-          lock: (result[1] != 0 || result[3] != 0) ? :released : :nothing_to_release
+          queue: (result[1] != 0 || result[3] != 0) ? :released : :nothing_to_release,
+          lock: (result[2] != 0 || result[4] != 0) ? :released : :nothing_to_release
         }
       }
     end
+    # rubocop:enable Metrics/MethodLength
   end
 end

data/lib/redis_queued_locks/acquirer/release_locks_of.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.14.0
-# @version 1.18.0
+# @version 1.20.0
 # rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Acquirer::ReleaseLocksOf
   # @since 1.14.0
@@ -20,11 +20,16 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     # @param redis [RedisClient]
     #   Redis connection client.
     # @param lock_scan_size [Integer]
-    #   The number of lock keys that should be released in a time.
+    #   The number of lock keys (the disabled lock index: the SCAN count of the single SCAN pass
+    #   over the lock keys and lock queues) or locks (lock names, the enabled lock index: the ZSCAN
+    #   count of the single ZSCAN pass over the lock index) that should be processed in a time.
     #   Affects the RubyVM memmory (cuz each found lock will be temporary stored in memory for
     #   subsequent removal from redis in one query at a time).
     # @param queue_scan_size [Integer]
-    #   The number of lock queues that should be scanned removing an acquirer from them (at a time).
+    #   The number of lock queues that should be processed removing an acquirer from them
+    #   (in one round trip).
+    # @param lock_index_enabled [Boolean]
+    #   Find locks via the lock index instead of the keyspace SCAN.
     # @param logger [::Logger,#debug]
     #   - Logger object used from `configuration` layer (see config['logger']);
     #   - See RedisQueuedLocks::Logging::VoidLogger for example;
@@ -88,7 +93,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
     #
     # @api private
     # @since 1.14.0
-    # @version 1.18.0
+    # @version 1.20.0
     # rubocop:disable Metrics/MethodLength
     def release_locks_of(
       refused_host_id,
@@ -96,6 +101,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
       redis,
       lock_scan_size,
       queue_scan_size,
+      lock_index_enabled,
       logger,
       instrumenter,
       instrument,
@@ -107,7 +113,7 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
       instr_sampling_percent,
       instr_sampler,
       instr_sample_this
-    ) # TODO: move from SCAN to indexes :thinking:
+    )
       rel_start_time = clock_gettime
 
       # steep:ignore:start
@@ -116,7 +122,8 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
         refused_acquirer_id,
         redis,
         lock_scan_size,
-        queue_scan_size
+        queue_scan_size,
+        lock_index_enabled
       ) => { ok:, result: }
       # steep:ignore:end
 
@@ -158,104 +165,266 @@ module RedisQueuedLocks::Acquirer::ReleaseLocksOf
 
     private
 
+    # Releases the locks and the lock requests of the passed host/acquirer found in one pass:
+    #   - the disabled lock index: one SCAN pass over the RQL keys (`KEY_PATTERN`): the found keys
+    #     are processed in batches with one round trip per batch (batches are collected across
+    #     SCAN pages);
+    #   - the enabled lock index: one ZSCAN pass over the lock index (`LOCK_INDEX_KEY`: lock names,
+    #     the keyspace is never scanned): the keys of each batch of `lock_scan_size` lock names are
+    #     derived from the lock names and processed with one round trip per key family and batch;
+    #     the lock names stay in the lock index (other keys of the locks can exist);
+    # Batches:
+    #   - write locks of the passed acquirer (`lock_scan_size` locks per batch);
+    #   - (RW) read locks of the passed acquirer (`lock_scan_size` readers registries per batch);
+    #   - requests of the passed acquirer in the lock queues (`queue_scan_size` queues per batch);
+    #
     # @param refused_host_id [String]
     # @param refused_acquirer_id [String]
     # @param redis [RedisClient]
     # @param lock_scan_size [Integer]
-    # @param queue_scan_size [Integer]
+    #   SCAN count and the batch size of locks (the disabled lock index) or ZSCAN count and
+    #   the batch size of locks (lock names, the enabled lock index).
+    # @param queue_scan_size [Integer] The batch size of lock queues.
+    # @param lock_index_enabled [Boolean]
     # @return [Hash<Symbol,Boolean|Hash<Symbol,Integer>>]
     #   - Example: { ok: true, result: { rel_key_cnt: 12345, tch_queue_cnt: 321 } }
     #
     # @api private
     # @since 1.14.0
-    # @version 1.18.0
+    # @version 1.20.0
     # rubocop:disable Metrics/MethodLength
     def fully_release_locks_of(
       refused_host_id,
       refused_acquirer_id,
       redis,
       lock_scan_size,
-      queue_scan_size
+      queue_scan_size,
+      lock_index_enabled
     )
-      # TODO: some indexing approach isntead of <scan>
       rel_key_cnt = 0
       tch_queue_cnt = 0
+      # NOTE: (RW) read locks store acquirer ids only (the host is a part of the acquirer id),
+      #   so they are released only when the passed acquirer belongs to the passed host;
+      with_read_locks =
+        RedisQueuedLocks::Resource.host_identifier_from_acquirer(refused_acquirer_id) ==
+        refused_host_id
 
       redis.with do |rconn|
-        # Step A: drop locks of the passed host/acquirer
-        refused_locks = Set.new #: Set[String]
-        rconn.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::LOCK_PATTERN,
-          count: lock_scan_size
-        ) do |lock_key|
-          acquirer_id, host_id = rconn.call('HMGET', lock_key, 'acq_id', 'hst_id')
-          if refused_host_id == host_id && refused_acquirer_id == acquirer_id
-            refused_locks << lock_key
-          end
+        # @type var lock_keys: Array[String]
+        lock_keys = []
+        # @type var lock_readers_keys: Array[String]
+        lock_readers_keys = []
+        # @type var lock_queues: Array[String]
+        lock_queues = []
 
-          if refused_locks.size >= lock_scan_size
-            # NOTE: steep can not recognize the `*`-splat operator on Set objects
-            rconn.call('DEL', *refused_locks) # steep:ignore
-            rel_key_cnt += refused_locks.size
-            refused_locks.clear
-          end
-        end
+        if lock_index_enabled
+          # NOTE: (lock index) the keys of each batch of lock names are derived from the lock names
+          each_lock_name_batch(rconn, lock_scan_size) do |lock_names|
+            lock_names.each do |lock_name|
+              lock_keys << RedisQueuedLocks::Resource.prepare_lock_key(lock_name)
+              if with_read_locks
+                lock_readers_keys << RedisQueuedLocks::Resource.prepare_lock_readers(lock_name)
+              end
+              lock_queues << RedisQueuedLocks::Resource.prepare_lock_queue(lock_name)
+              lock_queues << RedisQueuedLocks::Resource.prepare_read_lock_queue(lock_name)
+            end
 
-        if refused_locks.any?
-          # NOTE: steep can not recognize the `*`-splat operator on Set objects
-          rconn.call('DEL', *refused_locks) # steep:ignore
-          rel_key_cnt += refused_locks.size
-        end
+            # Step A: drop locks of the passed host/acquirer
+            rel_key_cnt += release_refused_locks(
+              rconn, lock_keys, refused_host_id, refused_acquirer_id
+            )
+            # Step A (RW): drop read locks of the passed host/acquirer
+            unless lock_readers_keys.empty?
+              rel_key_cnt += release_refused_read_locks(
+                rconn, lock_readers_keys, refused_acquirer_id
+              )
+            end
+            # Step B: drop passed host/acquirer from lock queues (write and read)
+            lock_queues.each_slice(queue_scan_size) do |lock_queues_batch|
+              tch_queue_cnt += dequeue_refused_acquirer(
+                rconn, lock_queues_batch, refused_acquirer_id
+              )
+            end
 
-        # Step A (RW): drop read locks of the passed host/acquirer
-        #   - read locks store acquirer ids only (the host is a part of the acquirer id);
-        if RedisQueuedLocks::Resource.host_identifier_from_acquirer(refused_acquirer_id) ==
-           refused_host_id
+            lock_keys.clear
+            lock_readers_keys.clear
+            lock_queues.clear
+          end
+        else
+          # NOTE: (keyspace) the found keys are collected into batches by their key families
           rconn.scan(
             'MATCH',
-            RedisQueuedLocks::Resource::LOCK_READERS_PATTERN,
+            RedisQueuedLocks::Resource::KEY_PATTERN,
             count: lock_scan_size
-          ) do |lock_readers_key|
-            res = rconn.call('ZREM', lock_readers_key, refused_acquirer_id)
-            next if res == 0
+          ) do |key|
+            case RedisQueuedLocks::Resource.lock_key_family(key)
+            when :lock
+              # Step A: drop locks of the passed host/acquirer
+              lock_keys << key
+              next if lock_keys.size < lock_scan_size
+
+              rel_key_cnt += release_refused_locks(
+                rconn, lock_keys, refused_host_id, refused_acquirer_id
+              )
+              lock_keys.clear
+            when :lock_readers
+              # Step A (RW): drop read locks of the passed host/acquirer
+              next unless with_read_locks
+
+              lock_readers_keys << key
+              next if lock_readers_keys.size < lock_scan_size
 
-            rel_key_cnt += 1
-            # NOTE: drop the read lock data
-            rconn.call(
-              'DEL',
-              RedisQueuedLocks::Resource.prepare_read_lock_key(
-                RedisQueuedLocks::Resource.lock_name_from_readers(lock_readers_key),
-                refused_acquirer_id
+              rel_key_cnt += release_refused_read_locks(
+                rconn, lock_readers_keys, refused_acquirer_id
               )
+              lock_readers_keys.clear
+            when :lock_queue, :read_lock_queue
+              # Step B: drop passed host/acquirer from lock queues (write and read)
+              lock_queues << key
+              next if lock_queues.size < queue_scan_size
+
+              tch_queue_cnt += dequeue_refused_acquirer(rconn, lock_queues, refused_acquirer_id)
+              lock_queues.clear
+            end
+          end
+
+          unless lock_keys.empty?
+            rel_key_cnt += release_refused_locks(
+              rconn, lock_keys, refused_host_id, refused_acquirer_id
+            )
+          end
+          unless lock_readers_keys.empty?
+            rel_key_cnt += release_refused_read_locks(
+              rconn, lock_readers_keys, refused_acquirer_id
             )
           end
+          unless lock_queues.empty?
+            tch_queue_cnt += dequeue_refused_acquirer(rconn, lock_queues, refused_acquirer_id)
+          end
         end
+      end
+
+      { ok: true, result: { rel_key_cnt:, tch_queue_cnt: } }
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Drops the locks of the passed host/acquirer from the given batch of write locks
+    # (two round trips: lock owners, then one `DEL` of the refused locks).
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_keys [Array<String>]
+    # @param refused_host_id [String]
+    # @param refused_acquirer_id [String]
+    # @return [Integer] The number of the refused locks.
+    #
+    # @api private
+    # @since 1.20.0
+    def release_refused_locks(redis_client, lock_keys, refused_host_id, refused_acquirer_id)
+      # NOTE: (pipeline layout) one reply (acquirer and host) per lock in the batch order
+      # @type var lock_owners: Array[[String?, String?]]
+      lock_owners = redis_client.pipelined do |pipeline|
+        lock_keys.each { |lock_key| pipeline.call('HMGET', lock_key, 'acq_id', 'hst_id') }
+      end
 
-        # Step B: drop passed host/acquirer from lock queues
-        rconn.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::LOCK_QUEUE_PATTERN,
-          count: queue_scan_size
-        ) do |lock_queue|
-          res = rconn.call('ZREM', lock_queue, refused_acquirer_id)
-          tch_queue_cnt += 1 if res != 0
+      # @type var refused_locks: Array[String]
+      refused_locks = []
+      lock_keys.each_with_index do |lock_key, index|
+        acquirer_id, host_id = lock_owners[index]
+        if refused_host_id == host_id && refused_acquirer_id == acquirer_id
+          refused_locks << lock_key
         end
+      end
+      return 0 if refused_locks.empty?
 
-        # Step B (RW): drop passed host/acquirer from read lock queues
-        rconn.scan(
-          'MATCH',
-          RedisQueuedLocks::Resource::READ_LOCK_QUEUE_PATTERN,
-          count: queue_scan_size
-        ) do |read_lock_queue|
-          res = rconn.call('ZREM', read_lock_queue, refused_acquirer_id)
-          tch_queue_cnt += 1 if res != 0
+      redis_client.call('DEL', *refused_locks)
+      refused_locks.size
+    end
+
+    # (RW) Drops the read locks of the passed acquirer from the given batch of readers registries
+    # in one round trip: `ZREM` of the acquirer and `DEL` of its read lock data for each registry
+    # (the read lock data is a data carrier only: `DEL` of an absent data is a no-op).
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_readers_keys [Array<String>]
+    # @param refused_acquirer_id [String]
+    # @return [Integer] The number of the dropped read locks.
+    #
+    # @api private
+    # @since 1.20.0
+    def release_refused_read_locks(redis_client, lock_readers_keys, refused_acquirer_id)
+      # NOTE: (pipeline layout) two replies per registry in the batch order: ZREM, DEL
+      # @type var replies: Array[Integer]
+      replies = redis_client.pipelined do |pipeline|
+        lock_readers_keys.each do |lock_readers_key|
+          pipeline.call('ZREM', lock_readers_key, refused_acquirer_id)
+          pipeline.call(
+            'DEL',
+            RedisQueuedLocks::Resource.prepare_read_lock_key(
+              RedisQueuedLocks::Resource.lock_name_from_readers(lock_readers_key),
+              refused_acquirer_id
+            )
+          )
         end
       end
 
-      { ok: true, result: { rel_key_cnt:, tch_queue_cnt: } }
+      released = 0
+      replies.each_slice(2) { |(zrem_cmd_res, _del_cmd_res)| released += 1 if zrem_cmd_res != 0 }
+      released
+    end
+
+    # Drops the requests of the passed acquirer from the given batch of lock queues
+    # (write and read) in one round trip.
+    #
+    # @param redis_client [RedisClient]
+    # @param lock_queues [Array<String>]
+    # @param refused_acquirer_id [String]
+    # @return [Integer] The number of the touched lock queues.
+    #
+    # @api private
+    # @since 1.20.0
+    def dequeue_refused_acquirer(redis_client, lock_queues, refused_acquirer_id)
+      # @type var replies: Array[Integer]
+      replies = redis_client.pipelined do |pipeline|
+        lock_queues.each { |lock_queue| pipeline.call('ZREM', lock_queue, refused_acquirer_id) }
+      end
+      replies.count { |zrem_cmd_res| zrem_cmd_res != 0 }
+    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
   end
-  # rubocop:enable Metrics/MethodLength, Metrics/ClassLength
+  # rubocop:enable Metrics/ClassLength
 end
 # rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/acquirer.rb

@@ -18,4 +18,5 @@ module RedisQueuedLocks::Acquirer
   require_relative 'acquirer/keys'
   require_relative 'acquirer/extend_lock_ttl'
   require_relative 'acquirer/clear_dead_requests'
+  require_relative 'acquirer/reindex_locks'
 end