redis_queued_locks 1.16.2 → 1.17.0

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

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

@@ -125,20 +125,16 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   #
   # @api private
   # @since 1.9.0
-  # rubocop:disable Style/RedundantBegin
+  # @version 1.17.0
   def status
     sync.synchronize do
       thread_running = swarmed__alive?
       thread_state = swarmed? ? thread_state(swarm_element) : 'non_initialized' # steep:ignore
 
       main_loop_running = swarmed__running?
-      main_loop_state = begin
-        if main_loop_running
-          swarm_loop__status[:result][:main_loop][:state] # steep:ignore
-        else
-          'non_initialized'
-        end
-      end
+      # NOTE: `nil` when the element is not alive (or has been terminated during the request);
+      loop_status = swarm_loop__status if main_loop_running
+      main_loop_state = loop_status ? loop_status[:state] : 'non_initialized'
 
       {
         enabled: enabled?,
@@ -153,7 +149,6 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
       }
     end
   end
-  # rubocop:enable Style/RedundantBegin
 
   private
 
@@ -169,7 +164,7 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   #
   # @api private
   # @since 1.9.0
-  # rubocop:disable Metrics/MethodLength
+  # @version 1.17.0
   def swarm!
     # NOTE: kill the main loop at start to prevent any async-thread-race-based memory leaks;
     main_loop&.kill
@@ -187,42 +182,37 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
           main_loop_alive = main_loop != nil && main_loop.alive?
           # steep:ignore:end
 
-          # steep:ignore:start
           main_loop_state = (main_loop == nil) ? 'non_initialized' : thread_state(main_loop)
-          # steep:ignore:end
 
           # steep:ignore:start
-          swarm_element_results.push({
-            ok: true,
-            result: { main_loop: { alive: main_loop_alive, state: main_loop_state } }
-          })
+          swarm_element_results.push({ alive: main_loop_alive, state: main_loop_state })
           # steep:ignore:end
         when :is_active
-          is_active = main_loop != nil && main_loop.alive? # steep:ignore
-          swarm_element_results.push({ ok: true, result: { is_active: } }) # steep:ignore
+          swarm_element_results.push(main_loop != nil && main_loop.alive?) # steep:ignore
         when :start
           main_loop&.kill
           @main_loop = spawn_main_loop!.tap { |thread| thread.abort_on_exception = false }
-          swarm_element_results.push({ ok: true, result: nil }) # steep:ignore
+          swarm_element_results.push(true) # steep:ignore
         when :stop
           main_loop&.kill
-          swarm_element_results.push({ ok: true, result: nil }) # steep:ignore
+          swarm_element_results.push(true) # steep:ignore
         end
       end
     end
   end
-  # rubocop:enable Metrics/MethodLength
 
   # @return [Thread] Thread with #abort_onexception == false that wraps loop'ed logic;
   #
   # @api private
   # @since 1.9.0
-  def spawn_main_loop! # steep:ignore
+  # @version 1.17.0
+  def spawn_main_loop!
     # NOTE:
     #   - provide the swarm element looped logic here wrapped into the thread;
     #   - created thread will be reconfigured inside the swarm_element logic with a
     #     `abort_on_exception = false` (cuz the stauts of the thread is
     #     totally controlled by the @swarm_element's logic);
+    raise NotImplementedError, "#{self.class}#spawn_main_loop! is not implemented"
   end
 
   # @return [Boolean]
@@ -261,10 +251,9 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarmed__running?
-    swarmed__alive? && !terminating? && (swarm_loop__is_active.yield_self do |result|
-      result != nil && result[:ok] && result[:result][:is_active] # steep:ignore
-    end)
+    swarmed__alive? && !terminating? && swarm_loop__is_active == true
   end
 
   # @return [Boolean,NilClass]
@@ -284,57 +273,66 @@ class RedisQueuedLocks::Swarm::SwarmElement::Threaded
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarmed__stopped?
-    swarmed__alive? && (terminating? || !(swarm_loop__is_active.yield_self do |result|
-      result && result[:ok] && result[:result][:is_active] # steep:ignore
-    end))
+    # NOTE: `nil` (no answer) is treated as "not active";
+    swarmed__alive? && (terminating? || swarm_loop__is_active != true)
   end
 
-  # @return [Boolean,NilClass]
+  # @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 if idle? || swarmed__dead? || terminating?
-    sync.synchronize do
-      swarm_element_commands.push(:is_active) # steep:ignore
-      swarm_element_results.pop # steep:ignore
-    end
+    swarm_loop__send_command(:is_active) #: bool?
   end
 
-  # @return [Hash,NilClass]
+  # @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? || terminating?
-    sync.synchronize do
-      swarm_element_commands.push(:status) # steep:ignore
-      swarm_element_results.pop # steep:ignore
-    end
+    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? || terminating?
-    sync.synchronize do
-      swarm_element_commands.push(:start) # steep:ignore
-      swarm_element_results.pop # steep:ignore
-    end
+    swarm_loop__send_command(:start)
   end
 
   # @return [void]
   #
   # @api private
   # @since 1.9.0
+  # @version 1.17.0
   def swarm_loop__stop
+    swarm_loop__send_command(:stop)
+  end
+
+  # Sends the command to the control thread 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!) or `nil` if the element is not available.
+  #
+  # @api private
+  # @since 1.17.0
+  def swarm_loop__send_command(command)
     return if idle? || swarmed__dead? || terminating?
     sync.synchronize do
-      swarm_element_commands.push(:stop) # steep:ignore
-      swarm_element_results.pop # steep:ignore
+      commands = swarm_element_commands
+      results = swarm_element_results
+      next if commands == nil || results == nil
+      commands.push(command)
+      results.pop
     end
   end
 

data/lib/redis_queued_locks/version.rb

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

data/redis_queued_locks.gemspec

@@ -3,7 +3,7 @@
 require_relative 'lib/redis_queued_locks/version'
 
 Gem::Specification.new do |spec|
-  spec.required_ruby_version = '>= 3.3'
+  spec.required_ruby_version = '>= 4.0'
 
   spec.name = 'redis_queued_locks'
   spec.version = RedisQueuedLocks::VERSION

data/sig/redis_queued_locks/swarm/flush_zombies.rbs

@@ -7,7 +7,7 @@ module RedisQueuedLocks
       def self.flush_zombies: (RC::client redis_client, Integer zombie_ttl, Integer lock_scan_size, Integer queue_scan_size) -> flushedZombies
 
       def enabled?: () -> bool
-      def swarm!: () -> void
+      def spawn_swarm_element!: (Ractor::Port[SwarmElement::Isolated::resultsPortMessage] swarm_element_results_port) -> Ractor
     end
   end
 end

data/sig/redis_queued_locks/swarm/swarm_element/isolated.rbs

@@ -8,10 +8,14 @@ module RedisQueuedLocks
 
         @rql_client: RQL::Client
         @swarm_element: Ractor?
+        @swarm_element_commands_port: Ractor::Port[Symbol]?
+        @swarm_element_results_port: Ractor::Port[resultsPortMessage]?
         @sync: RQL::Utilities::Lock
 
         attr_reader rql_client: RQL::Client
         attr_reader swarm_element: Ractor?
+        attr_reader swarm_element_commands_port: Ractor::Port[Symbol]?
+        attr_reader swarm_element_results_port: Ractor::Port[resultsPortMessage]?
         attr_reader sync: RQL::Utilities::Lock
 
         def initialize: (RQL::Client rql_client) -> void
@@ -27,25 +31,29 @@ module RedisQueuedLocks
         }
         def status: () -> elementStatus
 
-        def self.swarm_loop: () { () -> Thread } -> void
+        type swarmLoopStatus = { alive: bool, state: String }
+        type swarmLoopReply = swarmLoopStatus | bool
+        type resultsPortMessage = swarmLoopReply | Ractor::Port[Symbol] | Symbol
+        def self.swarm_loop: (Ractor::Port[resultsPortMessage] swarm_element_results_port) { () -> Thread } -> void
+        def self.terminate_thread: (Thread? thread) -> void
 
         private
 
         def swarm!: () -> void
+        def spawn_swarm_element!: (Ractor::Port[resultsPortMessage] swarm_element_results_port) -> Ractor
         def idle?: () -> bool
         def swarmed?: () -> bool
         def swarmed__alive?: () -> bool
         def swarmed__dead?: () -> bool
         def swarmed__running?: () -> bool
         def swarmed__stopped?: () -> bool
-        def swarm_loop__is_active: () -> bool
-
-        type swarmLoopStatus = { main_loop: { alive: bool, state: String } }
+        def swarm_loop__is_active: () -> bool?
         def swarm_loop__status: () -> swarmLoopStatus?
 
         def swarm_loop__start: () -> void
-        def swarm_loop__pause: () -> void
+        def swarm_loop__stop: () -> void
         def swarm_loop__kill: () -> void
+        def swarm_loop__send_command: (Symbol command) -> swarmLoopReply?
       end
     end
   end

data/sig/redis_queued_locks/swarm/swarm_element/threaded.rbs

@@ -10,14 +10,14 @@ module RedisQueuedLocks
         @swarm_element: Thread?
         @main_loop: Thread?
         @swarm_element_commands: Thread::SizedQueue[Symbol]?
-        @swarm_element_results: Thread::SizedQueue[{ ok: bool, result: Hash[untyped,untyped] }]?
+        @swarm_element_results: Thread::SizedQueue[swarmLoopReply]?
         @sync: RQL::Utilities::Lock
 
         attr_reader rql_client: RQL::Client
         attr_reader swarm_element: Thread?
         attr_reader main_loop: Thread?
         attr_reader swarm_element_commands: Thread::SizedQueue[Symbol]?
-        attr_reader swarm_element_results: Thread::SizedQueue[{ ok: bool, result: Hash[untyped,untyped] }]?
+        attr_reader swarm_element_results: Thread::SizedQueue[swarmLoopReply]?
         attr_reader sync: RQL::Utilities::Lock
 
         def initialize: (RQL::Client rql_client) -> void
@@ -46,14 +46,14 @@ module RedisQueuedLocks
         def terminating?: () -> bool?
         def swarmed__stopped?: () -> bool
 
-        type swarmLoopIsActive = { ok: bool, result: { is_active: bool } }
-        def swarm_loop__is_active: () -> swarmLoopIsActive?
-
-        type swarmLoopStatus = { ok: bool, result: { main_loop: { alive: bool, state: String } } }
+        type swarmLoopStatus = { alive: bool, state: String }
+        type swarmLoopReply = swarmLoopStatus | bool
+        def swarm_loop__is_active: () -> bool?
         def swarm_loop__status: () -> swarmLoopStatus?
 
         def swarm_loop__start: () -> void
         def swarm_loop__stop: () -> void
+        def swarm_loop__send_command: (Symbol command) -> swarmLoopReply?
         def swarm_element__termiante: () -> void
       end
     end