redis_queued_locks 1.18.0 → 1.20.0

data/lib/redis_queued_locks/client.rb

@@ -2,7 +2,7 @@
 
 # @api public
 # @since 1.0.0
-# @version 1.18.0
+# @version 1.20.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Client
   # @return [RedisClient]
@@ -174,6 +174,14 @@ class RedisQueuedLocks::Client
   #   Lock's time to live (in milliseconds).
   # @option queue_ttl [Integer]
   #   Lifetime of the acuier's lock request. In seconds.
+  # @option lock_index_grace_period [Integer]
+  #   - The lock index score margin over the lock key lifetime (in milliseconds): the lock name
+  #     stays in the lock index (`rql:index:locks`) for this period after the expiration of
+  #     the lock keys;
+  #   - should be greater than the client clock skew between your hosts plus the network latency;
+  #   - used only with the enabled lock index (`config['lock_index_enabled']`, the client-wide
+  #     mode: the lock index is maintained by all lock acquirements of the client);
+  #   - pre-configured in `config['lock_index_grace_period']`;
   # @option timeout [Integer,NilClass]
   #   Time period whe should try to acquire the lock (in seconds). Nil means "without timeout".
   # @option timed [Boolean]
@@ -331,12 +339,13 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.20.0
   # rubocop:disable Metrics/MethodLength
   def lock(
     lock_name,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -373,6 +382,8 @@ class RedisQueuedLocks::Client
       ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
       ttl:,
       queue_ttl:,
+      lock_index_enabled: config['lock_index_enabled'],
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -407,11 +418,13 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
+  # @version 1.20.0
   def lock_series( # steep:ignore
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -449,6 +462,8 @@ class RedisQueuedLocks::Client
       ractor_id: RedisQueuedLocks::Resource.get_ractor_id,
       ttl:,
       queue_ttl:,
+      lock_index_enabled: config['lock_index_enabled'],
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -483,11 +498,13 @@ class RedisQueuedLocks::Client
   # rubocop:disable all
   # @api public
   # @since 1.16.0
+  # @version 1.20.0
   def lock_series!( # steep:ignore
     *lock_names,
     detailed_result: false,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -519,6 +536,7 @@ class RedisQueuedLocks::Client
       detailed_result:,
       ttl:,
       queue_ttl:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -552,11 +570,12 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.20.0
   def lock!(
     lock_name,
     ttl: config['default_lock_ttl'],
     queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period'],
     timeout: config['try_to_lock_timeout'],
     timed: config['is_timed_by_default'],
     retry_count: config['retry_count'],
@@ -587,6 +606,7 @@ class RedisQueuedLocks::Client
       lock_name,
       ttl:,
       queue_ttl:,
+      lock_index_grace_period:,
       timeout:,
       timed:,
       retry_count:,
@@ -645,7 +665,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.20.0
   def unlock(
     lock_name,
     logger: config['logger'],
@@ -663,6 +683,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseLock.release_lock(
       redis_client,
       lock_name,
+      config['lock_index_enabled'],
       instrumenter,
       logger,
       log_sampling_enabled,
@@ -677,14 +698,20 @@ class RedisQueuedLocks::Client
   end
   alias_method :release_lock, :unlock
 
-  # Releases the read lock of the current acquirer only: other read locks, the write lock and
-  # lock requests are not affected (`#unlock` releases the lock entirely). It is suitable for
-  # read locks obtained without a block of code.
+  # Releases the read lock of the current acquirer (or of the custom acquirer passed via
+  # `acquirer_id:`) only: other read locks, the write lock and lock requests are not affected
+  # (`#unlock` releases the lock entirely). It is suitable for read locks obtained without
+  # a block of code.
   #
   # @param lock_name [String] The lock name whose read lock should be released.
+  # @option acquirer_id [String,NilClass]
+  #   - The acquirer whose read lock should be released (`nil` by default);
+  #   - `nil` => the current acquirer is used (calculated from `identity:`, see `#current_acquirer_id`);
+  #   - can be extracted from the lock data (`#lock_info`, `#locks_info`, `#queue_info`, `#queues_info`);
   # @option identity [String]
   #   Unique acquirer identity (the same as for `#lock`) that is used to calculate the current
-  #   acquirer id (see `#current_acquirer_id`).
+  #   acquirer id (see `#current_acquirer_id`). Ignored when `acquirer_id:` is passed: the acquirer id
+  #   already contains its own identity.
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
   # @option instrument [NilClass,Any]
@@ -707,10 +734,18 @@ class RedisQueuedLocks::Client
   #     }
   #   }
   #
+  # @example Release the read lock of the current acquirer:
+  #   client.unlock_read('report')
+  #
+  # @example Release the read lock of a different acquirer:
+  #   client.unlock_read('report', acquirer_id: "rql:acq:62681/2016/2024/2032/b30ec5e4bea10512")
+  #
   # @api public
   # @since 1.18.0
+  # @version 1.19.0
   def unlock_read(
     lock_name,
+    acquirer_id: nil,
     identity: uniq_identity,
     logger: config['logger'],
     instrumenter: config['instrumenter'],
@@ -727,7 +762,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseReadLock.release_read_lock(
       redis_client,
       lock_name,
-      current_acquirer_id(identity:),
+      acquirer_id || current_acquirer_id(identity:),
       instrumenter,
       logger,
       instrument,
@@ -909,7 +944,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.18.0
+  # @version 1.20.0
   def extend_lock_ttl(
     lock_name,
     milliseconds,
@@ -935,6 +970,7 @@ class RedisQueuedLocks::Client
       read_write_mode,
       all_read_locks,
       current_acquirer_id(identity:),
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -953,6 +989,7 @@ class RedisQueuedLocks::Client
   # Returns:
   #   - :rel_time - (milliseconds) - time spent to release all locks and queues;
   #   - :rel_key_cnt - (integer) - the number of released redis keys (queus+locks);
+  # Locks are found via the keyspace SCAN or via the lock index (`config['lock_index_enabled']`).
   #
   # @option batch_size [Integer]
   # @option logger [::Logger,#debug]
@@ -971,7 +1008,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.20.0
   def clear_locks(
     batch_size: config['lock_release_batch_size'],
     logger: config['logger'],
@@ -989,6 +1026,7 @@ class RedisQueuedLocks::Client
     RedisQueuedLocks::Acquirer::ReleaseAllLocks.release_all_locks(
       redis_client,
       batch_size,
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -1010,6 +1048,8 @@ class RedisQueuedLocks::Client
   # current puma request thread is killed by Rack::Timeout and you need to cleanup all zombie RQL
   # locks and lock reuqests obtained during the request processing).
   #
+  # Locks are found via the keyspace SCAN or via the lock index (`config['lock_index_enabled']`).
+  #
   # Identifiers can be extracted via:
   #   - `#current_host_id`
   #   - `#current_acquirer_id`
@@ -1057,6 +1097,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.14.0
+  # @version 1.20.0
   def clear_locks_of(
     host_id:,
     acquirer_id:,
@@ -1080,6 +1121,7 @@ class RedisQueuedLocks::Client
       redis_client,
       lock_scan_size,
       queue_scan_size,
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -1169,10 +1211,16 @@ class RedisQueuedLocks::Client
   #     at the moment of Redis'es SCAN;
   # @return [Set<String>,Set<Hash<Symbol,Any>>]
   #
+  # NOTE: locks are found via the keyspace SCAN or via the lock index (ZSCAN, the enabled
+  #   `config['lock_index_enabled']`: `scan_size` is the number of locks in one batch);
+  #
   # @api public
   # @since 1.0.0
+  # @version 1.20.0
   def locks(scan_size: config['key_extraction_batch_size'], with_info: false)
-    RedisQueuedLocks::Acquirer::Locks.locks(redis_client, scan_size:, with_info:)
+    RedisQueuedLocks::Acquirer::Locks.locks(
+      redis_client, scan_size:, with_info:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # Extracts lock keys with their info. See #locks(with_info: true) for details.
@@ -1200,10 +1248,16 @@ class RedisQueuedLocks::Client
   #     at the moment of Redis'es SCAN;
   # @return [Set<String>,String<Hash<Symbol,Any>>]
   #
+  # NOTE: lock queues are found via the keyspace SCAN or via the lock index (ZSCAN, the enabled
+  #   `config['lock_index_enabled']`: `scan_size` is the number of locks in one batch);
+  #
   # @api public
   # @since 1.0.0
+  # @version 1.20.0
   def queues(scan_size: config['key_extraction_batch_size'], with_info: false)
-    RedisQueuedLocks::Acquirer::Queues.queues(redis_client, scan_size:, with_info:)
+    RedisQueuedLocks::Acquirer::Queues.queues(
+      redis_client, scan_size:, with_info:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # Extracts lock queues with their info. See #queues(with_info: true) for details.
@@ -1219,11 +1273,17 @@ class RedisQueuedLocks::Client
 
   # @option scan_size [Integer]
   # @return [Set<String>]
+  #   - the disabled lock index: all the RQL keys (`rql:lock*`) found via the keyspace SCAN;
+  #   - the enabled lock index (`config['lock_index_enabled']`): the existing keys of the locks of
+  #     the lock index (ZSCAN, `scan_size` is the number of locks in one batch);
   #
   # @api public
   # @since 1.0.0
+  # @version 1.20.0
   def keys(scan_size: config['key_extraction_batch_size'])
-    RedisQueuedLocks::Acquirer::Keys.keys(redis_client, scan_size:)
+    RedisQueuedLocks::Acquirer::Keys.keys(
+      redis_client, scan_size:, lock_index_enabled: config['lock_index_enabled']
+    )
   end
 
   # @option dead_ttl [Integer]
@@ -1231,7 +1291,8 @@ class RedisQueuedLocks::Client
   #     considered as dead;
   #   - `config['dead_request_ttl']` is used by default;
   # @option scan_size [Integer]
-  #   - the batch of scanned keys for Redis'es SCAN command;
+  #   - the batch of scanned keys for Redis'es SCAN command (or the number of locks in one batch of
+  #     the lock index ZSCAN pass: the enabled `config['lock_index_enabled']`);
   #   - `config['lock_release_batch_size']` is used by default;
   # @option logger [::Logger,#debug]
   # @option instrumenter [#notify]
@@ -1249,7 +1310,7 @@ class RedisQueuedLocks::Client
   #
   # @api public
   # @since 1.0.0
-  # @version 1.6.0
+  # @version 1.20.0
   def clear_dead_requests(
     dead_ttl: config['dead_request_ttl'],
     scan_size: config['lock_release_batch_size'],
@@ -1269,6 +1330,7 @@ class RedisQueuedLocks::Client
       redis_client,
       scan_size,
       dead_ttl,
+      config['lock_index_enabled'],
       logger,
       instrumenter,
       instrument,
@@ -1282,5 +1344,43 @@ class RedisQueuedLocks::Client
       instr_sample_this
     )
   end
+
+  # Adds the lock keys without the lock index entry (keys of older RQL versions, keys created while
+  # the lock index was disabled) to the lock index (`rql:index:locks`). Invoke it once after the lock
+  # index is enabled (`config['lock_index_enabled']`) on all your processes: lock-iterating
+  # operations (the swarm, `#locks`, `#queues`, `#keys`, `#clear_locks`, ...) find locks via
+  # the lock index only.
+  #   - works regardless of `config['lock_index_enabled']` (the lock index is not used and not
+  #     maintained while it is disabled);
+  #   - one SCAN pass over the RQL keys;
+  #   - lock queues without TTL (older RQL versions) get `queue_ttl` as their TTL;
+  #   - idempotent: the lock index scores are never decreased, already indexed keys stay as is;
+  #
+  # @option scan_size [Integer]
+  #   - the batch of scanned keys for Redis'es SCAN command;
+  #   - `config['lock_release_batch_size']` is used by default;
+  # @option queue_ttl [Integer]
+  #   - TTL of the lock queues without TTL (in seconds);
+  #   - `config['default_queue_ttl']` is used by default;
+  # @option lock_index_grace_period [Integer]
+  #   - the lock index score margin over the key lifetime (in milliseconds);
+  #   - `config['lock_index_grace_period']` is used by default;
+  # @return [Hash<Symbol,Boolean|Hash<Symbol,Integer>>]
+  #   Format: { ok: true, result: { idx_key_cnt: Integer } } (the number of indexed keys)
+  #
+  # @api public
+  # @since 1.20.0
+  def reindex_locks(
+    scan_size: config['lock_release_batch_size'],
+    queue_ttl: config['default_queue_ttl'],
+    lock_index_grace_period: config['lock_index_grace_period']
+  )
+    RedisQueuedLocks::Acquirer::ReindexLocks.reindex_locks(
+      redis_client,
+      scan_size,
+      queue_ttl,
+      lock_index_grace_period
+    )
+  end
 end
 # rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/config.rb

@@ -2,7 +2,7 @@
 
 # @api private
 # @since 1.13.0
-# @version 1.15.1
+# @version 1.20.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Config
   require_relative 'config/dsl'
@@ -27,6 +27,8 @@ class RedisQueuedLocks::Config
   setting('logger', RedisQueuedLocks::Logging::VoidLogger)
   setting('log_lock_try', false)
   setting('dead_request_ttl', 1 * 24 * 60 * 60 * 1000) # NOTE: 1 day in milliseconds)
+  setting('lock_index_enabled', false)
+  setting('lock_index_grace_period', 60_000) # NOTE: in milliseconds)
   setting('is_timed_by_default', false)
   setting('default_conflict_strategy', :wait_for_lock)
   setting('default_access_strategy', :queued)
@@ -90,6 +92,8 @@ class RedisQueuedLocks::Config
   validate('logger') { |val| RedisQueuedLocks::Logging.valid_interface?(val) }
   validate('log_lock_try') { |val| val == true || val == false }
   validate('dead_request_ttl') { |val| val.is_a?(Integer) && val > 0 }
+  validate('lock_index_enabled') { |val| val == true || val == false }
+  validate('lock_index_grace_period') { |val| val.is_a?(Integer) && val >= 0 }
   validate('is_timed_by_default') { |val| val == true || val == false }
   validate('log_sampler') { |val| RedisQueuedLocks::Logging.valid_sampler?(val) }
   validate('log_sampling_enabled') { |val| val == true || val == false }

data/lib/redis_queued_locks/resource.rb

@@ -47,18 +47,49 @@ module RedisQueuedLocks::Resource
   # @since 1.18.0
   READ_LOCK_PATTERN = 'rql:lock_reader:*'
 
+  # Write and read lock queues in one SCAN pass (the keyspace lookup: the disabled lock index).
+  # NOTE:
+  #   - the pattern matches other keys too when the lock name contains `queue:` (for example,
+  #     `rql:lock_readers:my_queue:a`), so callers check the key family (`lock_key_family`);
+  # @return [String]
+  #
+  # @api private
+  # @since 1.20.0
+  ALL_LOCK_QUEUES_PATTERN = 'rql:lock_*queue:*'
+
   # @return [String]
   #
   # @api private
   # @since 1.9.0
   SWARM_KEY = 'rql:swarm:hsts'
 
+  # Lock index: a sorted set of lock names (members) where the score is the upper bound of the
+  # lifetime of all keys of the lock (client time, epoch milliseconds + the index grace period).
+  # It replaces the full keyspace SCAN for the operations that iterate over locks (lock names are
+  # taken from the index, lock keys are derived from the lock names).
+  # NOTE:
+  #   - it is used and maintained only with the enabled lock index (`config['lock_index_enabled']`,
+  #     disabled by default: lock-iterating operations scan the keyspace (`KEY_PATTERN`) then);
+  #   - the key is not matched by `KEY_PATTERN` (`rql:index:` vs `rql:lock`) and can not collide
+  #     with lock keys (`rql:lock:<name>`, `rql:lock_<kind>:<name>`);
+  #   - the index is a superset of the existing locks: a lock name is added (or its score is
+  #     increased) by every command that creates or extends a lock key (in the same pipeline or
+  #     transaction, after the key command) and it is removed only when its score is reached
+  #     (`ZREMRANGEBYSCORE`: all the keys of the lock are expired by that time) or in the same
+  #     transaction with all the keys of the lock (`#unlock`, `#clear_locks`);
+  # @return [String]
+  #
+  # @api private
+  # @since 1.20.0
+  LOCK_INDEX_KEY = 'rql:index:locks'
+
   # @return [Integer] Redis time error (in milliseconds).
   #
   # @api private
   # @since 1.3.0
   REDIS_TIMESHIFT_ERROR = 2
 
+  # rubocop:disable Metrics/ClassLength
   class << self
     # Returns 16-byte unique identifier. It is used for uniquely
     # identify current process between different nodes/pods of your application
@@ -143,8 +174,9 @@ module RedisQueuedLocks::Resource
     end
 
     # Read lock data of the concrete acquirer: a hash with the same structure as the write lock
-    # (acquirer, host, timestamp, ttl, meta, reentrant lock data). It is a data carrier only:
-    # the readers registry is the source of truth for the read lock existence.
+    # (timestamp, ttl, meta, reentrant lock data; acquirer and host are derived from the acquirer
+    # id and are not stored). It is a data carrier only: the readers registry is the source of
+    # truth for the read lock existence.
     #
     # @param lock_name [String]
     # @param acquirer_id [String]
@@ -179,6 +211,70 @@ module RedisQueuedLocks::Resource
       end
     end
 
+    # Family of the given RQL key: one SCAN pass over `KEY_PATTERN` (or `ALL_LOCK_QUEUES_PATTERN`)
+    # returns keys of several families, so callers keep the keys of the families they need.
+    #
+    # @param key [String]
+    # @return [Symbol,NilClass]
+    #   - `:lock` - write lock (`rql:lock:*`);
+    #   - `:lock_queue` - write lock requests (`rql:lock_queue:*`);
+    #   - `:lock_readers` - readers registry (`rql:lock_readers:*`);
+    #   - `:read_lock_queue` - read lock requests (`rql:lock_read_queue:*`);
+    #   - `:read_lock` - read lock data (`rql:lock_reader:*`);
+    #   - `nil` - any other key (for example, `rql:lockX` matched by `KEY_PATTERN`);
+    #
+    # @api private
+    # @since 1.20.0
+    def lock_key_family(key)
+      # NOTE:
+      #   - `start_with?` instead of regexp `when`-matchers: no MatchData allocations;
+      #   - prefixes are unambiguous: `rql:lock_reader:` is not a prefix of `rql:lock_readers:`;
+      case
+      when key.start_with?('rql:lock:') then :lock
+      when key.start_with?('rql:lock_queue:') then :lock_queue
+      when key.start_with?('rql:lock_readers:') then :lock_readers
+      when key.start_with?('rql:lock_read_queue:') then :read_lock_queue
+      when key.start_with?('rql:lock_reader:') then :read_lock
+      end
+    end
+
+    # Lock name of the given RQL key (the member of the lock index).
+    #
+    # @param key [String]
+    # @param key_family [Symbol,NilClass] Family of the key (see `lock_key_family`).
+    # @return [String,NilClass]
+    #   - the lock name for the write lock, the readers registry and the lock queues (both modes);
+    #   - `nil` for the read lock data (`:read_lock`: the lock name can not be separated from
+    #     the acquirer id unambiguously) and for any other key;
+    #
+    # @api private
+    # @since 1.20.0
+    def lock_name_from_key(key, key_family)
+      case key_family
+      when :lock then key.delete_prefix('rql:lock:')
+      when :lock_queue then key.delete_prefix('rql:lock_queue:')
+      when :lock_readers then key.delete_prefix('rql:lock_readers:')
+      when :read_lock_queue then key.delete_prefix('rql:lock_read_queue:')
+      end
+    end
+
+    # Client time for the lock index scores (see `LOCK_INDEX_KEY`).
+    #
+    # @return [Integer] Epoch, in milliseconds.
+    #
+    # @api private
+    # @since 1.20.0
+    def lock_index_time
+      # NOTE:
+      #   - an Integer of milliseconds without Time/Float objects;
+      #   - CLOCK_REALTIME (epoch), not CLOCK_MONOTONIC: the lock index scores are absolute times
+      #     stored in the shared Redis and compared by other hosts (pruning, expired names),
+      #     while monotonic clocks have a per-host origin (boot time) and are not comparable
+      #     between hosts; the wall clock skew between hosts is covered by
+      #     `lock_index_grace_period`;
+      ::Process.clock_gettime(::Process::CLOCK_REALTIME, :millisecond)
+    end
+
     # @param lock_readers_key [String]
     # @return [String]
     #
@@ -347,5 +443,6 @@ module RedisQueuedLocks::Resource
       # steep:ignore:end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end
 # rubocop:enable Metrics/ModuleLength