redis_queued_locks 1.16.2 → 1.18.0

data/lib/redis_queued_locks/config/dsl.rb

@@ -6,29 +6,23 @@ module RedisQueuedLocks::Config::DSL
   # @api private
   # @since 1.13.0
   module ClassMethods
-    # NOTE:
-    #   1. Style/DefWithParentheses rubocop's cop incorrectly drops `()` from method definition
-    #   and breaks ruby code syntax. So this cop is disabled here;
-    #   2. attr_reader is not used cuz `steep` can't understand it form inside the class where
+    # NOTE: attr_reader is not used cuz `steep` can't understand it form inside the class where
     #   the current module is mixed;
     #
     # @return [Hash<String,Block>]
     #
     # @api private
     # @since 1.13.0
-    def config_setters()= @config_setters
+    def config_setters = @config_setters
 
-    # NOTE:
-    #   1. Style/DefWithParentheses rubocop's cop incorrectly drops `()` from method definition
-    #   and breaks ruby code syntax. So this cop is disabled here;
-    #   2. attr_reader is not used cuz `steep` can't understand it form inside the class where
+    # NOTE: attr_reader is not used cuz `steep` can't understand it form inside the class where
     #   the current module is mixed;
     #
     # @return [Hash<String,Block>]
     #
     # @api private
     # @since 1.13.0
-    def config_validators()= @config_validators
+    def config_validators = @config_validators
 
     # @param config_key [String]
     # @param validator [Block]

data/lib/redis_queued_locks/resource.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.0.0
+# rubocop:disable Metrics/ModuleLength
 module RedisQueuedLocks::Resource
   # @return [String]
   #
@@ -21,17 +22,30 @@ module RedisQueuedLocks::Resource
   # @since 1.0.0
   LOCK_QUEUE_PATTERN = 'rql:lock_queue:*'
 
+  # NOTE:
+  #   - read/write keys use their own prefixes (not suffixes of the lock name) cuz the lock name
+  #     is an arbitrary string: `rql:lock_queue:<name>:read` collides with the queue of a lock
+  #     named "<name>:read";
+  #   - new prefixes are not matched by LOCK_PATTERN/LOCK_QUEUE_PATTERN
+  #     (`rql:lock_` vs `rql:lock:`) but are matched by KEY_PATTERN;
+  #   - write lock requests use the classic lock queue (LOCK_QUEUE_PATTERN);
   # @return [String]
   #
   # @api private
-  # @since ?.?.?
-  READ_LOCK_QUEUE_PATTERN = 'rql:lock_queue:*:read'
+  # @since 1.18.0
+  READ_LOCK_QUEUE_PATTERN = 'rql:lock_read_queue:*'
 
   # @return [String]
   #
   # @api private
-  # @since ?.?.?
-  WRITE_LOCK_QUEUE_PATTERN = 'rql:lock_queue:*:write'
+  # @since 1.18.0
+  LOCK_READERS_PATTERN = 'rql:lock_readers:*'
+
+  # @return [String]
+  #
+  # @api private
+  # @since 1.18.0
+  READ_LOCK_PATTERN = 'rql:lock_reader:*'
 
   # @return [String]
   #
@@ -105,22 +119,115 @@ module RedisQueuedLocks::Resource
       "rql:lock_queue:#{lock_name}"
     end
 
+    # Queue of read lock requests (write lock requests use the classic lock queue).
+    #
     # @param lock_name [String]
     # @return [String]
     #
     # @api private
-    # @api ?.?.?
+    # @since 1.18.0
     def prepare_read_lock_queue(lock_name)
-      "rql:lock_queue:#{lock_name}:read"
+      "rql:lock_read_queue:#{lock_name}"
     end
 
+    # Registry of read lock holders: a sorted set where the member is an acquirer id and
+    # the score is the read lock expiration time (redis server time, epoch milliseconds).
+    #
     # @param lock_name [String]
     # @return [String]
     #
     # @api private
-    # @api ?.?.?
-    def prepare_write_lock_queue(lock_name)
-      "rql:lock_queue:#{lock_name}:write"
+    # @since 1.18.0
+    def prepare_lock_readers(lock_name)
+      "rql:lock_readers:#{lock_name}"
+    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.
+    #
+    # @param lock_name [String]
+    # @param acquirer_id [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 1.18.0
+    def prepare_read_lock_key(lock_name, acquirer_id)
+      "rql:lock_reader:#{lock_name}:#{acquirer_id}"
+    end
+
+    # Mode of the lock requests stored in the given lock queue.
+    #
+    # @param lock_queue [String]
+    #   Write lock queue (`rql:lock_queue:*`) or read lock queue (`rql:lock_read_queue:*`).
+    # @return [String,NilClass]
+    #   - `'write'` for the write lock queue, `'read'` for the read lock queue;
+    #   - `nil` for any other key (unreachable: lock queues are always passed consistently);
+    #
+    # @api private
+    # @since 1.18.0
+    def lock_queue_rw_mode(lock_queue)
+      # NOTE:
+      #   - `start_with?` instead of regexp `when`-matchers: no MatchData allocations;
+      #   - write lock queues are checked first: they are met more often than read lock queues;
+      case
+      when lock_queue.start_with?('rql:lock_queue:') then 'write'
+      when lock_queue.start_with?('rql:lock_read_queue:') then 'read'
+      else
+        # NOTE: unreachable: the logic always passes a consistent lock queue (read or write)
+        nil
+      end
+    end
+
+    # @param lock_readers_key [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 1.18.0
+    def lock_name_from_readers(lock_readers_key)
+      lock_readers_key.delete_prefix('rql:lock_readers:')
+    end
+
+    # @param lock_readers_key [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 1.18.0
+    def lock_key_from_readers(lock_readers_key)
+      "rql:lock:#{lock_readers_key.delete_prefix('rql:lock_readers:')}"
+    end
+
+    # Host identifier of the given acquirer
+    # (acquirer and host identifiers are built from the same process/thread/ractor/identity data):
+    #   - acquirer id: `rql:acq:<pid>/<thread>/<fiber>/<ractor>/<identity>`;
+    #   - host id: `rql:hst:<pid>/<thread>/<ractor>/<identity>` (the same as `host_identifier`);
+    #
+    # @param acquirer_id [String]
+    # @return [String]
+    #
+    # @api private
+    # @since 1.18.0
+    def host_identifier_from_acquirer(acquirer_id)
+      # NOTE:
+      #   - the host id is the acquirer id with another prefix and without the fiber part, so it is
+      #     built in place from the acquirer id copy (one allocation: no intermediate strings and
+      #     arrays of `delete_prefix`/`split`, no substrings);
+      #   - 8 is the size of the `rql:acq:` prefix;
+      #   - byte positions are used cuz identity can contain any (multibyte) symbols;
+      thread_end = acquirer_id.byteindex('/', acquirer_id.byteindex('/', 8).to_i + 1).to_i
+      fiber_end = acquirer_id.byteindex('/', thread_end + 1).to_i
+      host_id = acquirer_id.dup
+      host_id.bytesplice(thread_end, fiber_end - thread_end, '') # NOTE: drop "/<fiber>"
+      host_id.bytesplice(0, 8, 'rql:hst:')
+    end
+
+    # @param redis_time [Array<String>] Result of the redis `TIME` command (seconds, microseconds).
+    # @return [Integer] Redis server time (epoch, in milliseconds).
+    #
+    # @api private
+    # @since 1.18.0
+    def redis_time_ms(redis_time)
+      (Integer(redis_time[0]) * 1_000) + (Integer(redis_time[1]) / 1_000)
     end
 
     # @return [Float] Redis's <Set> score that is calculated from the time (epoch) as a float.
@@ -241,3 +348,4 @@ module RedisQueuedLocks::Resource
     end
   end
 end
+# rubocop:enable Metrics/ModuleLength

data/lib/redis_queued_locks/swarm/flush_zombies.rb

@@ -2,6 +2,7 @@
 
 # @api private
 # @since 1.9.0
+# rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElement::Isolated
   class << self
     # @param redis_client [RedisClient]
@@ -18,6 +19,7 @@ class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElem
     #
     # @api private
     # @since 1.9.0
+    # @version 1.18.0
     # rubocop:disable Metrics/MethodLength
     def flush_zombies(
       redis_client,
@@ -65,6 +67,32 @@ class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElem
         # NOTE: (steep) steep can't use <Set>s for splats
         rconn.call('DEL', *zombie_locks) if zombie_locks.any? # steep:ignore
 
+        # Step 3 (RW): find zombie read locks (read locks of zombie hosts) and drop them
+        #   - read locks store acquirer ids only (the host is a part of the acquirer id);
+        #   - readers registry is reported as a zombie lock if any of its read locks is dropped;
+        rconn.scan(
+          'MATCH', RedisQueuedLocks::Resource::LOCK_READERS_PATTERN, count: lock_scan_size
+        ) do |lock_readers_key|
+          # @type var read_lock_acquirers: Array[String]
+          read_lock_acquirers = rconn.call('ZRANGE', lock_readers_key, '0', '-1')
+          zombie_readers = read_lock_acquirers.select do |acquirer_id|
+            zombie_hosts.include?(RedisQueuedLocks::Resource.host_identifier_from_acquirer(acquirer_id))
+          end
+          next if zombie_readers.empty?
+
+          rconn.call('ZREM', lock_readers_key, *zombie_readers)
+          # NOTE: drop the zombie read lock data
+          lock_name = RedisQueuedLocks::Resource.lock_name_from_readers(lock_readers_key)
+          rconn.call(
+            'DEL',
+            *zombie_readers.map do |acquirer_id|
+              RedisQueuedLocks::Resource.prepare_read_lock_key(lock_name, acquirer_id)
+            end
+          )
+          zombie_locks << lock_readers_key
+          zombie_acquirers.merge(zombie_readers)
+        end
+
         # Step 4: find zombie requests => and drop them
         # TODO: indexing (in order to prevent full database scan);
         # NOTE: original redis does not support indexing so we need to use
@@ -77,6 +105,15 @@ class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElem
           end
         end
 
+        # Step 4 (RW): drop zombie requests from the queues of read lock requests
+        rconn.scan(
+          'MATCH', RedisQueuedLocks::Resource::READ_LOCK_QUEUE_PATTERN, count: queue_scan_size
+        ) do |read_lock_queue|
+          zombie_acquirers.each do |zombie_acquirer|
+            rconn.call('ZREM', read_lock_queue, zombie_acquirer)
+          end
+        end
+
         # Step 5: drop zombies from the swarm
         rconn.call('HDEL', RedisQueuedLocks::Resource::SWARM_KEY, *zombie_hosts)
 
@@ -100,19 +137,21 @@ class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElem
     rql_client.config['swarm.flush_zombies.enabled_for_swarm']
   end
 
-  # @return [void]
+  # @param swarm_element_results_port [Ractor::Port] Results port of the main Ractor.
+  # @return [Ractor]
   #
   # @api private
-  # @since 1.9.0
-  def swarm!
-    @swarm_element = Ractor.new(
+  # @since 1.17.0
+  def spawn_swarm_element!(swarm_element_results_port)
+    Ractor.new(
+      swarm_element_results_port,
       rql_client.config.slice('swarm.flush_zombies.redis_config'),
       rql_client.config['swarm.flush_zombies.zombie_ttl'],
       rql_client.config['swarm.flush_zombies.zombie_lock_scan_size'],
       rql_client.config['swarm.flush_zombies.zombie_queue_scan_size'],
       rql_client.config['swarm.flush_zombies.zombie_flush_period']
-    ) do |rc, z_ttl, z_lss, z_qss, z_fl_prd|
-      RedisQueuedLocks::Swarm::FlushZombies.swarm_loop do
+    ) do |r_res_p, rc, z_ttl, z_lss, z_qss, z_fl_prd|
+      RedisQueuedLocks::Swarm::FlushZombies.swarm_loop(r_res_p) do
         Thread.new do
           redis_client = RedisQueuedLocks::Swarm::RedisClientBuilder.build(
             pooled: rc['pooled'],
@@ -132,3 +171,4 @@ class RedisQueuedLocks::Swarm::FlushZombies < RedisQueuedLocks::Swarm::SwarmElem
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/redis_queued_locks/swarm/supervisor.rb

@@ -89,7 +89,7 @@ class RedisQueuedLocks::Swarm::Supervisor
 
     {
       running: running?,
-      state: (visor == nil) ? 'non_initialized' : thread_state(visor), # steep:ignore
+      state: (visor == nil) ? 'non_initialized' : thread_state(visor),
       observable: (observable == nil) ? 'non_initialized' : 'initialized'
     }
   end

data/lib/redis_queued_locks/swarm/swarm_element/isolated.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
+# Swarm element isolated inside its own Ractor. Communication works via `Ractor::Port`s:
+# - `swarm_element_results_port`: created in the main Ractor (where the Swarm and its Supervisor
+#   live), receives element replies and the element ractor termination notice (`:exited`/`:aborted`,
+#   registered via `Ractor#monitor`);
+# - `swarm_element_commands_port`: created inside the element ractor (only the creator ractor can
+#   receive from a port) and handed over to the main Ractor during the element startup;
+# Each element instance owns its own pair of ports, so any number of isolated elements can work
+# side by side.
+#
 # @api private
 # @since 1.9.0
+# @version 1.17.0
 # rubocop:disable Metrics/ClassLength
 class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   # @since 1.9.0
@@ -19,6 +29,22 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   # @since 1.9.0
   attr_reader :swarm_element
 
+  # Port of the element ractor that receives commands (created inside the element ractor).
+  #
+  # @return [Ractor::Port,NilClass]
+  #
+  # @api private
+  # @since 1.17.0
+  attr_reader :swarm_element_commands_port
+
+  # Port of the main Ractor that receives element replies and the element termination notice.
+  #
+  # @return [Ractor::Port,NilClass]
+  #
+  # @api private
+  # @since 1.17.0
+  attr_reader :swarm_element_results_port
+
   # @return [RedisQueuedLocks::Utilities::Lock]
   #
   # @api private
@@ -30,9 +56,12 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def initialize(rql_client)
     @rql_client = rql_client
     @swarm_element = nil
+    @swarm_element_commands_port = nil
+    @swarm_element_results_port = nil
     @sync = RedisQueuedLocks::Utilities::Lock.new
   end
 
@@ -100,19 +129,18 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def status
     sync.synchronize do
       ractor_running = swarmed__alive?
       ractor_state = swarmed? ? ractor_status(swarm_element) : 'non_initialized' # steep:ignore
 
-      begin
-        main_loop_running = swarmed__running?
-        # steep:ignore:start
-        main_loop_state =
-          main_loop_running ? swarm_loop__status[:main_loop][:state] : 'non_initialized'
-        # steep:ignore:end
-      rescue Ractor::ClosedError
-        # NOTE: it can happend when you running RedisQueuedLocks::Swarm#deswarm!
+      # NOTE: `nil` when the element ractor is not alive (or has died during the request);
+      loop_status = swarm_loop__status
+      if loop_status && loop_status[:alive]
+        main_loop_running = true
+        main_loop_state = loop_status[:state]
+      else
         main_loop_running = false
         main_loop_state = 'non_initialized'
       end
@@ -134,38 +162,79 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   private
 
   # Swarm element lifecycle have the following scheme:
-  # => 1) init (swarm!): create a ractor, main loop is not started;
-  # => 2) start (swarm_loop__start!): run main lopp inside the ractor;
-  # => 3) stop (swarm_loop__stop!): stop the main loop inside a ractor;
-  # => 4) kill (swarm_loop__kill!): kill the main loop inside teh ractor and kill a ractor;
+  # => 1) init (swarm!): create a results port and a ractor (main loop is not started),
+  #       receive the ractor's command port;
+  # => 2) start (swarm_loop__start): run the main loop inside the ractor;
+  # => 3) stop (swarm_loop__stop): stop the main loop inside the ractor;
+  # => 4) kill (swarm_loop__kill): kill the main loop inside the ractor and finish the ractor;
   #
   # @return [void]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm!
-    # IMPORTANT №1: initialize @swarm_element here with Ractor;
-    # IMPORTANT №2: your Ractor should invoke .swarm_loop inside (see below);
-    # IMPORTANT №3: you should pass the main loop logic as a block to .swarm_loop;
+    # NOTE: the results port is created in the current (main) Ractor: only it can receive from it;
+    results = Ractor::Port.new
+    element = spawn_swarm_element!(results)
+    @swarm_element_results_port = results
+    @swarm_element = element
+    # NOTE: `:exited`/`:aborted` will be sent to the results port when the ractor is finished
+    #   (immediately if it is already finished), so no request can wait for a reply forever;
+    element.monitor(results)
+    # NOTE: the first message from the element ractor is its command port (see .swarm_loop),
+    #   any other message is the termination notice (the ractor has died during the startup);
+    handshake = results.receive
+    @swarm_element_commands_port = handshake.is_a?(Ractor::Port) ? handshake : nil
+  end
+
+  # @param swarm_element_results_port [Ractor::Port] Results port of the main Ractor.
+  # @return [Ractor]
+  #
+  # @api private
+  # @since 1.17.0
+  def spawn_swarm_element!(swarm_element_results_port)
+    # IMPORTANT №1: create and return a Ractor here (pass `swarm_element_results_port` and all
+    #   required configs into `Ractor.new` as shareable/copyable values);
+    # IMPORTANT №2: your Ractor should invoke .swarm_loop(swarm_element_results_port) inside
+    #   (see below);
+    # IMPORTANT №3: you should pass the main loop logic as a block to .swarm_loop
+    #   (the block should return a Thread that wraps the looped logic);
+    raise NotImplementedError, "#{self.class}#spawn_swarm_element! is not implemented"
   end
 
+  # Internal protocol (bare scalars/primitives, no `{ ok:, result: }` wrapper):
+  #   - handshake: the command port itself (the first message on the results port);
+  #   - `:status` => `{ alive: <Boolean>, state: <String> }`;
+  #   - `:is_active` => `true`/`false`;
+  #   - `:start`, `:stop`, `:kill` => `true` (ack);
+  #   - Symbol messages on the results port are reserved for the Ractor#monitor notice;
+  #
+  # @param swarm_element_results_port [Ractor::Port] Results port of the main Ractor.
   # @param main_loop_spawner [Block]
   # @return [void]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   # rubocop:disable Layout/ClassStructure, Lint/IneffectiveAccessModifier, Metrics/MethodLength
-  def self.swarm_loop(&main_loop_spawner)
+  def self.swarm_loop(swarm_element_results_port, &main_loop_spawner)
     # NOTE:
     #   This self.-related part of code is placed in the middle of class in order
     #   to provide better code readability (it is placed next to the method inside
-    #   wich it should be called (see #swarm!)). That's why some rubocop cops are disabled.
+    #   wich it should be called (see #spawn_swarm_element!)). That's why some rubocop
+    #   cops are disabled.
+
+    # NOTE: the command port should be created inside the element ractor (only the creator
+    #   ractor can receive from the port), so it is handed over to the main Ractor at startup;
+    swarm_element_commands_port = Ractor::Port.new
+    swarm_element_results_port << swarm_element_commands_port
 
     # @type var main_loop: Thread?
     main_loop = nil
 
     loop do
-      command = Ractor.receive
+      command = swarm_element_commands_port.receive
 
       case command
       when :status
@@ -177,25 +246,46 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
             # @type var main_loop: Thread
             RedisQueuedLocks::Utilities.thread_state(main_loop)
           end
-        # NOTE: (will be reworked with Ractor::Port in the next RQL release (~1.17))
-        Ractor.yield({ # steep:ignore
-          main_loop: { alive: main_loop_alive, state: main_loop_state }
-        })
+        swarm_element_results_port << { alive: main_loop_alive, state: main_loop_state }
       when :is_active
-        Ractor.yield(main_loop != nil && main_loop.alive?) # steep:ignore
+        swarm_element_results_port << (main_loop != nil && main_loop.alive?) # steep:ignore
       when :start
-        main_loop.kill if main_loop != nil # steep:ignore
-        main_loop = yield # REFERENCE: `main_loop_spawner.call`
+        terminate_thread(main_loop)
+        # REFERENCE: `main_loop_spawner.call`
+        main_loop = yield.tap { |thread| thread.abort_on_exception = false }
+        swarm_element_results_port << true
       when :stop
-        main_loop.kill if main_loop != nil # steep:ignore
+        terminate_thread(main_loop)
+        swarm_element_results_port << true
       when :kill
-        main_loop.kill if main_loop != nil # steep:ignore
-        exit
+        # NOTE: terminate the main loop and all auxiliary threads it may have left behind (for
+        #   example, socket connection helper threads when the loop is killed during connection):
+        #   the ractor stays alive while it has unfinished threads;
+        (::Thread.list - [::Thread.current]).each { |thread| terminate_thread(thread) }
+        swarm_element_results_port << true
+        break
       end
     end
   end
   # rubocop:enable Layout/ClassStructure, Lint/IneffectiveAccessModifier, Metrics/MethodLength
 
+  # Kills the thread and waits for its termination: the ractor can not finish
+  # (and its status stays "running") while it has unfinished threads.
+  #
+  # @param thread [Thread,NilClass]
+  # @return [void]
+  #
+  # @api private
+  # @since 1.17.0
+  # rubocop:disable Lint/IneffectiveAccessModifier
+  def self.terminate_thread(thread)
+    return if thread == nil
+    thread.kill
+    # NOTE: join re-raises the exception that has failed the thread: it is not our case here;
+    thread.join rescue nil
+  end
+  # rubocop:enable Lint/IneffectiveAccessModifier
+
   # @return [Boolean]
   #
   # @api private
@@ -232,61 +322,93 @@ class RedisQueuedLocks::Swarm::SwarmElement::Isolated
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarmed__running?
-    swarm_element != nil && ractor_alive?(swarm_element) && swarm_loop__is_active # steep:ignore
+    swarmed__alive? && swarm_loop__is_active == true
   end
 
   # @return [Boolean]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarmed__stopped?
-    swarm_element != nil && ractor_alive?(swarm_element) && !swarm_loop__is_active # steep:ignore
+    # NOTE: `nil` (the element ractor has died during the request) is neither active nor stopped;
+    swarmed__alive? && swarm_loop__is_active == false
   end
 
-  # @return [Boolean]
+  # @return [Boolean,NilClass] Is the main loop alive (`nil` when the element is not available).
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm_loop__is_active
-    return false if idle? || swarmed__dead?
-    sync.synchronize { swarm_element.send(:is_active).take }
+    swarm_loop__send_command(:is_active) #: bool?
   end
 
-  # @return [Hash]
+  # @return [Hash<Symbol,Boolean|String>,NilClass]
+  #   Format: `{ alive: <Boolean>, state: <String> }` (`nil` when the element is not available).
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm_loop__status
-    return if idle? || swarmed__dead?
-    sync.synchronize { swarm_element.send(:status).take }
+    swarm_loop__send_command(:status) #: swarmLoopStatus?
   end
 
   # @return [void]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm_loop__start
-    return if idle? || swarmed__dead?
-    sync.synchronize { swarm_element.send(:start) }
+    swarm_loop__send_command(:start)
   end
 
   # @return [void]
   #
   # @api private
-  # @since 1.9.0
-  def swarm_loop__pause
-    return if idle? || swarmed__dead?
-    sync.synchronize { swarm_element.send(:stop) }
+  # @since 1.17.0
+  def swarm_loop__stop
+    swarm_loop__send_command(:stop)
   end
 
   # @return [void]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm_loop__kill
-    return if idle? || swarmed__dead?
-    sync.synchronize { swarm_element.send(:kill) }
+    sync.synchronize do
+      # NOTE: wait for the ractor finish only when it has confirmed the kill command;
+      killed = swarm_loop__send_command(:kill) == true
+      @swarm_element_commands_port = nil
+      swarm_element.join if killed # steep:ignore
+    end
+  rescue Ractor::RemoteError
+    # NOTE: the element ractor has been finished with an exception: it is dead anyway;
+  end
+
+  # Sends the command to the element ractor and waits for its reply. Replies are received
+  # strictly one by one under the lock, so each reply belongs to the sent command.
+  #
+  # @param command [Symbol]
+  # @return [Boolean,Hash<Symbol,Boolean|String>,NilClass]
+  #   The bare reply value (see .swarm_loop) or `nil` if the element is dead.
+  #
+  # @api private
+  # @since 1.17.0
+  def swarm_loop__send_command(command)
+    return if idle? || swarmed__dead? || swarm_element_commands_port == nil
+    sync.synchronize do
+      swarm_element_commands_port << command
+      reply = swarm_element_results_port.receive # steep:ignore
+      # NOTE: Symbol replies are reserved for the Ractor#monitor notice (`:exited`/`:aborted`);
+      reply.is_a?(Symbol) ? nil : reply
+    end
+  rescue Ractor::ClosedError
+    # NOTE: the command port is closed together with the finished element ractor;
+    nil
   end
 end
 # rubocop:enable Metrics/ClassLength