redis_queued_locks 1.7.0 → 1.9.0

data/lib/redis_queued_locks/swarm/zombie_info.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.9.0
+module RedisQueuedLocks::Swarm::ZombieInfo
+  class << self
+    # @param redis_client [RedisClient]
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Hash<Symbol,Set<String>>]
+    #   Format: {
+    #     zombie_hosts: <Set<String>>,
+    #     zombie_acquirers: <Set<String>>,
+    #     zombie_locks: <Set<String>>
+    #   }
+    #
+    # @api private
+    # @since 1.9.0
+    def zombies_info(redis_client, zombie_ttl, lock_scan_size)
+      redis_client.with do |rconn|
+        extract_all(rconn, zombie_ttl, lock_scan_size)
+      end
+    end
+
+    # @param redis_client [RedisClient]
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def zombie_locks(redis_client, zombie_ttl, lock_scan_size)
+      redis_client.with do |rconn|
+        extract_zombie_locks(rconn, zombie_ttl, lock_scan_size)
+      end
+    end
+
+    # @param redis_client [RedisClient]
+    # @param zombie_ttl [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def zombie_hosts(redis_client, zombie_ttl)
+      redis_client.with do |rconn|
+        extract_zombie_hosts(rconn, zombie_ttl)
+      end
+    end
+
+    # @param redis_client [RedisClient]
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def zombie_acquiers(redis_client, zombie_ttl, lock_scan_size)
+      redis_client.with do |rconn|
+        extract_zombie_acquiers(rconn, zombie_ttl, lock_scan_size)
+      end
+    end
+
+    private
+
+    # @param rconn [RedisClient] redis connection obtained via `#with` from RedisClient instance;
+    # @param zombie_ttl [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def extract_zombie_hosts(rconn, zombie_ttl)
+      zombie_score = RedisQueuedLocks::Resource.calc_zombie_score(zombie_ttl / 1_000)
+      swarmed_hosts = rconn.call('HGETALL', RedisQueuedLocks::Resource::SWARM_KEY)
+      swarmed_hosts.each_with_object(Set.new) do |(hst_id, ts), zombies|
+        (zombies << hst_id) if (zombie_score > ts.to_f)
+      end
+    end
+
+    # @param rconn [RedisClient] redis connection obtained via `#with` from RedisClient instance;
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def extract_zombie_locks(rconn, zombie_ttl, lock_scan_size)
+      zombie_hosts = extract_zombie_hosts(rconn, zombie_ttl)
+      zombie_locks = Set.new
+      rconn.scan(
+        'MATCH', RedisQueuedLocks::Resource::LOCK_PATTERN, count: lock_scan_size
+      ) do |lock_key|
+        _acquier_id, host_id = rconn.call('HMGET', lock_key, 'acq_id', 'hst_id')
+        zombie_locks << lock_key if zombie_hosts.include?(host_id)
+      end
+      zombie_locks
+    end
+
+    # @param rconn [RedisClient] redis connection obtained via `#with` from RedisClient instance;
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Set<String>]
+    #
+    # @api private
+    # @since 1.9.0
+    def extract_zombie_acquiers(rconn, zombie_ttl, lock_scan_size)
+      zombie_hosts = extract_zombie_hosts(rconn, zombie_ttl)
+      zombie_acquirers = Set.new
+      rconn.scan(
+        'MATCH', RedisQueuedLocks::Resource::LOCK_PATTERN, count: lock_scan_size
+      ) do |lock_key|
+        acquier_id, host_id = rconn.call('HMGET', lock_key, 'acq_id', 'hst_id')
+        zombie_acquirers << acquier_id if zombie_hosts.include?(host_id)
+      end
+      zombie_acquirers
+    end
+
+    # @param rconn [RedisClient] redis connection obtained via `#with` from RedisClient instance;
+    # @param zombie_ttl [Integer]
+    # @param lock_scan_size [Integer]
+    # @return [Hash<Symbol,<Set<String>>]
+    #   Format: {
+    #     zombie_hosts: <Set<String>>,
+    #     zombie_acquirers: <Set<String>>,
+    #     zombie_locks: <Set<String>>
+    #   }
+    #
+    # @api private
+    # @since 1.9.0
+    def extract_all(rconn, zombie_ttl, lock_scan_size)
+      zombie_hosts = extract_zombie_hosts(rconn, zombie_ttl)
+      zombie_locks = Set.new
+      zombie_acquirers = Set.new
+      rconn.scan(
+        'MATCH', RedisQueuedLocks::Resource::LOCK_PATTERN, count: lock_scan_size
+      ) do |lock_key|
+        acquier_id, host_id = rconn.call('HMGET', lock_key, 'acq_id', 'hst_id')
+        if zombie_hosts.include?(host_id)
+          zombie_acquirers << acquier_id
+          zombie_locks << lock_key
+        end
+      end
+      { zombie_hosts:, zombie_acquirers:, zombie_locks: }
+    end
+  end
+end

data/lib/redis_queued_locks/swarm.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+# @api public
+# @since 1.9.0
+# rubocop:disable Metrics/ClassLength
+class RedisQueuedLocks::Swarm
+  require_relative 'swarm/redis_client_builder'
+  require_relative 'swarm/supervisor'
+  require_relative 'swarm/acquirers'
+  require_relative 'swarm/zombie_info'
+  require_relative 'swarm/swarm_element'
+  require_relative 'swarm/probe_hosts'
+  require_relative 'swarm/flush_zombies'
+
+  # @return [RedisQueuedLocks::Client]
+  #
+  # @api private
+  # @since 1.9.0
+  attr_reader :rql_client
+
+  # @return [RedisQueuedLocks::Swarm::Supervisor]
+  #
+  # @api private
+  # @since 1.9.0
+  attr_reader :supervisor
+
+  # @return [RedisQueuedLocks::Swarm::ProbeHosts]
+  #
+  # @api private
+  # @since 1.9.0
+  attr_reader :probe_hosts_element
+
+  # @return [RedisQueuedLocks::Swarm::FlushZombies]
+  #
+  # @api private
+  # @since 1.9.0
+  attr_reader :flush_zombies_element
+
+  # @return [RedisQueuedLocks::Utilities::Lock]
+  #
+  # @api private
+  # @since 1.9.0
+  attr_reader :sync
+
+  # @param rql_client [RedisQueuedLocks::Client]
+  # @return [void]
+  #
+  # @api private
+  # @since 1.9.0
+  def initialize(rql_client)
+    @rql_client = rql_client
+    @sync = RedisQueuedLocks::Utilities::Lock.new
+    @supervisor = RedisQueuedLocks::Swarm::Supervisor.new(rql_client)
+    @probe_hosts_element = RedisQueuedLocks::Swarm::ProbeHosts.new(rql_client)
+    @flush_zombies_element = RedisQueuedLocks::Swarm::FlushZombies.new(rql_client)
+  end
+
+  # @return [Hash<Symbol,Boolean|<Hash<Symbol,Boolean>>]
+  #
+  # @api public
+  # @since 1.9.0
+  def swarm_status
+    sync.synchronize do
+      {
+        auto_swarm: rql_client.config[:swarm][:auto_swarm],
+        supervisor: supervisor.status,
+        probe_hosts: probe_hosts_element.status,
+        flush_zombies: flush_zombies_element.status
+      }
+    end
+  end
+  alias_method :swarm_state, :swarm_status
+
+  # @option zombie_ttl [Integer]
+  # @return [Hash<String,Hash<Symbol,Float|Time>>]
+  #
+  # @api public
+  # @since 1.9.0
+  def swarm_info(zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl])
+    RedisQueuedLocks::Swarm::Acquirers.acquirers(
+      rql_client.redis_client,
+      zombie_ttl
+    )
+  end
+
+  # @return [
+  #   RedisQueuedLocks::Data[
+  #     ok: <Boolean>,
+  #     result: {
+  #       host_id1 <String> => score1 <String>,
+  #       host_id2 <String> => score2 <String>,
+  #       etc...
+  #     }
+  #   ]
+  # ]
+  #
+  # @api public
+  # @since 1.9.0
+  def probe_hosts
+    RedisQueuedLocks::Swarm::ProbeHosts.probe_hosts(
+      rql_client.redis_client,
+      rql_client.uniq_identity
+    )
+  end
+
+  # @option zombie_ttl [Integer]
+  # @option lock_scan_size [Integer]
+  # @option queue_scan_size [Integer]
+  # @return [
+  #   RedisQueuedLocks::Data[
+  #     ok: <Boolean>,
+  #     deleted_zombie_hosts: <Set<String>>,
+  #     deleted_zombie_acquiers: <Set<String>>,
+  #     deleted_zombie_locks: <Set<String>>
+  #   ]
+  # ]
+  #
+  # @api public
+  # @since 1.9.0
+  def flush_zombies(
+    zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl],
+    lock_scan_size: rql_client.config[:swarm][:flush_zombies][:zombie_lock_scan_size],
+    queue_scan_size: rql_client.config[:swarm][:flush_zombies][:zombie_queue_scan_size]
+  )
+    RedisQueuedLocks::Swarm::FlushZombies.flush_zombies(
+      rql_client.redis_client,
+      zombie_ttl,
+      lock_scan_size,
+      queue_scan_size
+    )
+  end
+
+  # @return [Set<String>]
+  #
+  # @api public
+  # @since 1.9.0
+  def zombie_locks(
+    zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl],
+    lock_scan_size: rql_client.config[:swarm][:flush_zombies][:zombie_lock_scan_size]
+  )
+    RedisQueuedLocks::Swarm::ZombieInfo.zombie_locks(
+      rql_client.redis_client,
+      zombie_ttl,
+      lock_scan_size
+    )
+  end
+
+  # @return [Set<String>]
+  #
+  # @api ppublic
+  # @since 1.9.0
+  def zombie_acquiers(
+    zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl],
+    lock_scan_size: rql_client.config[:swarm][:flush_zombies][:zombie_lock_scan_size]
+  )
+    RedisQueuedLocks::Swarm::ZombieInfo.zombie_acquiers(
+      rql_client.redis_client,
+      zombie_ttl,
+      lock_scan_size
+    )
+  end
+
+  # @return [Set<String>]
+  #
+  # @api public
+  # @since 1.9.0
+  def zombie_hosts(zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl])
+    RedisQueuedLocks::Swarm::ZombieInfo.zombie_hosts(rql_client.redis_client, zombie_ttl)
+  end
+
+  # @return [Hash<Symbol,Set<String>>]
+  #   Format: {
+  #     zombie_hosts: <Set<String>>,
+  #     zombie_acquirers: <Set<String>>,
+  #     zombie_locks: <Set<String>>
+  #   }
+  #
+  # @api public
+  # @since 1.9.0
+  def zombies_info(
+    zombie_ttl: rql_client.config[:swarm][:flush_zombies][:zombie_ttl],
+    lock_scan_size: rql_client.config[:swarm][:flush_zombies][:zombie_lock_scan_size]
+  )
+    RedisQueuedLocks::Swarm::ZombieInfo.zombies_info(
+      rql_client.redis_client,
+      zombie_ttl,
+      lock_scan_size
+    )
+  end
+
+  # @option silently [Boolean]
+  # @return [NilClass,Hash<Symbol,Symbol|Boolean>]
+  #
+  # @api public
+  # @since 1.9.0
+  def swarm!
+    sync.synchronize do
+      # Step 0:
+      #   - stop the supervisor (kill internal observer objects if supervisor is alredy running);
+      supervisor.stop!
+
+      # Step 1:
+      #   - initialize swarm elements and start their main loops;
+      probe_hosts_element.try_swarm!
+      flush_zombies_element.try_swarm!
+
+      # Step 2:
+      #   - run supervisor that should keep running created swarm elements and their main loops;
+      unless supervisor.running?
+        supervisor.observe! do
+          probe_hosts_element.reswarm_if_dead!
+          flush_zombies_element.reswarm_if_dead!
+        end
+      end
+
+      # NOTE: need to give a little timespot to initialize ractor objects and their main loops;
+      sleep(0.1)
+
+      RedisQueuedLocks::Data[ok: true, result: :swarming]
+    end
+  end
+
+  # @option silently [Boolean]
+  # @return [NilClass,Hash<Symbol,Symbol|Boolean>]
+  #
+  # @api public
+  # @since 1.9.0
+  def deswarm!
+    sync.synchronize do
+      supervisor.stop!
+      probe_hosts_element.try_kill!
+      flush_zombies_element.try_kill!
+
+      # NOTE: need to give a little timespot to stop ractor objects and their main loops;
+      sleep(0.1)
+
+      RedisQueuedLocks::Data[ok: true, result: :terminating]
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/utilities/lock.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# @api private
+# @since 1.9.0
+class RedisQueuedLocks::Utilities::Lock
+  # @return [void]
+  #
+  # @api private
+  # @since 1.9.0
+  def initialize
+    @lock = ::Mutex.new
+  end
+
+  # @param block [Block]
+  # @return [Any]
+  #
+  # @api private
+  # @since 1.9.0
+  def synchronize(&block)
+    @lock.owned? ? yield : @lock.synchronize(&block)
+  end
+end

data/lib/redis_queued_locks/utilities.rb

@@ -3,8 +3,38 @@
 # @api private
 # @since 1.0.0
 module RedisQueuedLocks::Utilities
+  require_relative 'utilities/lock'
+
   module_function
 
+  # Ractor class has no methods for Ractor object status identification.
+  # The only one approach (without C/FFI extending) to give the status is to check
+  # the status from the `#inspect/#to_s` methods. String representation has the following format:
+  #   Format: "#<Ractor:##{id}#{name ? ' '+name : ''}#{loc ? " " + loc : ''} #{status}>"
+  #   Example: #<Ractor:#2 (irb):2 terminated>
+  # So we need to parse the `status` part of the inspect method and use it for our logic.
+  # Current regexp object provides the pattern for this.
+  #
+  # @return [Regexp]
+  #
+  # @api private
+  # @since 1.9.0
+  RACTOR_LIVENESS_PATTERN = /\A.*?(created|running|blocking).*?\z/i
+
+  # Ractor status as a string extracted from the object string representation.
+  # This way is used cuz the ractor class has no any detailed status extraction API.
+  # Possible statuses (at the moment of Ruby@3.4):
+  #   - "created"
+  #   - "blocking"
+  #   - "running"
+  #   - "terminated"
+  #
+  # @return [Regexp]
+  #
+  # @api private
+  # @since 1.9.0
+  RACTOR_STATUS_PATTERN = /\A.*?\s(?<status>\w+)>\z/i
+
   # @param block [Block]
   # @return [Any]
   #
@@ -13,4 +43,49 @@ module RedisQueuedLocks::Utilities
   def run_non_critical(&block)
     yield rescue nil
   end
+
+  # Possible statuses (at the moment of Ruby@3.4):
+  #   - "created"
+  #   - "blocking"
+  #   - "running"
+  #   - "terminated"
+  #
+  # @param ractor [Ractor]
+  # @return [String]
+  #
+  # @api private
+  # @since 1.9.0
+  def ractor_status(ractor)
+    ractor.to_s.match(RACTOR_STATUS_PATTERN)[:status]
+  end
+
+  # @param ractor [Ractor]
+  # @return [Boolean]
+  #
+  # @api private
+  # @since 1.9.0
+  def ractor_alive?(ractor)
+    ractor.to_s.match?(RACTOR_LIVENESS_PATTERN)
+  end
+
+  # Returns the status of the passed thread object.
+  # Possible statuses:
+  #   - "run" (thread is executing);
+  #   - "sleep" (thread is sleeping or waiting on I/O);
+  #   - "aborting" (thread is aborting)
+  #   - "dead" (thread is terminated normally);
+  #   - "failed" (thread is terminated with an exception);
+  # See Thread#status official documentation.
+  #
+  # @param [Thread]
+  # @return [String]
+  #
+  # @api private
+  # @since 1.9.0
+  def thread_state(thread)
+    status = thread.status
+    return 'dead' if status == false
+    return 'failed' if status == nil
+    status
+  end
 end

data/lib/redis_queued_locks/version.rb

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

data/lib/redis_queued_locks.rb

@@ -5,6 +5,7 @@ require 'qonfig'
 require 'timeout'
 require 'securerandom'
 require 'logger'
+require 'objspace'
 
 # @api public
 # @since 1.0.0
@@ -18,6 +19,7 @@ module RedisQueuedLocks
   require_relative 'redis_queued_locks/resource'
   require_relative 'redis_queued_locks/acquier'
   require_relative 'redis_queued_locks/instrument'
+  require_relative 'redis_queued_locks/swarm'
   require_relative 'redis_queued_locks/client'
 
   # @since 1.0.0

data/redis_queued_locks.gemspec

@@ -15,21 +15,17 @@ Gem::Specification.new do |spec|
     'capabilities based on the Redis Database.'
 
   spec.description =
-    'Distributed locks with "prioritized lock acquisition queue" capabilities ' \
+    '|> 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 it's own queue separately from other queues) and processed " \
+    '|> Each lock request is put into the request queue ' \
+    '(each lock is hosted by it\'s own queue separately from other queues) and processed ' \
     'in order of their priority (FIFO). ' \
-    # ---
-    'Each lock request lives some period of time (RTTL) ' \
+    '|> 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 ' \
+    '|> 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. ' \
-    # ---
-    'Provides flexible invocation flow, parametrized limits ' \
+    '|> Provides flexible invocation flow, parametrized limits ' \
     '(lock request ttl, lock ttl, queue ttl, lock attempts limit, fast failing, etc), ' \
     'logging and instrumentation.'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis_queued_locks
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Rustam Ibragimov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-06-12 00:00:00.000000000 Z
+date: 2024-07-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-client
@@ -38,8 +38,16 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.28'
-description: 'Distributed locks with "prioritized lock acquisition queue" capabilities
-  based on the Redis Database. '
+description: '|> 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 it''s own queue separately from other queues) and processed
+  in order of their priority (FIFO). |> 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. |> Provides flexible invocation
+  flow, parametrized limits (lock request ttl, lock ttl, queue ttl, lock attempts
+  limit, fast failing, etc), logging and instrumentation.'
 email:
 - iamdaiver@gmail.com
 executables: []
@@ -91,9 +99,19 @@ files:
 - lib/redis_queued_locks/logging/sampler.rb
 - lib/redis_queued_locks/logging/void_logger.rb
 - lib/redis_queued_locks/resource.rb
+- lib/redis_queued_locks/swarm.rb
+- lib/redis_queued_locks/swarm/acquirers.rb
+- lib/redis_queued_locks/swarm/flush_zombies.rb
+- lib/redis_queued_locks/swarm/probe_hosts.rb
+- lib/redis_queued_locks/swarm/redis_client_builder.rb
+- lib/redis_queued_locks/swarm/supervisor.rb
+- lib/redis_queued_locks/swarm/swarm_element.rb
+- lib/redis_queued_locks/swarm/swarm_element/isolated.rb
+- lib/redis_queued_locks/swarm/swarm_element/threaded.rb
+- lib/redis_queued_locks/swarm/zombie_info.rb
 - lib/redis_queued_locks/utilities.rb
+- lib/redis_queued_locks/utilities/lock.rb
 - lib/redis_queued_locks/version.rb
-- lib/redis_queued_locks/watcher.rb
 - redis_queued_locks.gemspec
 homepage: https://github.com/0exp/redis_queued_locks
 licenses:
@@ -117,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Distributed locks with "prioritized lock acquisition queue" capabilities

data/lib/redis_queued_locks/watcher.rb

@@ -1 +0,0 @@
-# frozen_string_literal: true