Supervisor Lifecycle

lib/solid_queue/cli.rb

@@ -24,6 +24,7 @@ def self.exit_on_failure?
     default_command :start
 
     def start
+      # Supervisor Lifecycle - 1 - The CLI starts the SolidQueue::Supervisor with options.
       SolidQueue::Supervisor.start(**options.symbolize_keys)
     end
   end

lib/solid_queue/processes/interruptible.rb

@@ -25,6 +25,12 @@ def interrupt
       end
 
       def interruptible_sleep(time)
+        # Supervisor Lifecycle - 11.1
+        # Wait for the self-pipe to be readable, which indicates an interrupt
+        # If the time is 0, it will return immediately if the pipe is readable
+        # If the time is greater than 0, it will wait for the specified time
+        # If the pipe is readable, it will read all data from the pipe
+        # to clear it and avoid blocking on future reads.
         if time > 0 && self_pipe[:reader].wait_readable(time)
           loop { self_pipe[:reader].read_nonblock(SELF_PIPE_BLOCK_SIZE) }
         end

lib/solid_queue/supervisor.rb

@@ -9,6 +9,7 @@ class Supervisor < Processes::Base
 
     class << self
       def start(**options)
+        # Supervisor Lifecycle - 2 - Sets configuration and initializes the supervisor:
         SolidQueue.supervisor = true
         configuration = Configuration.new(**options)
 
@@ -29,12 +30,17 @@ def initialize(configuration)
     end
 
     def start
+      # Supervisor Lifecycle - 3 - Boots which runns the boot callbacks
       boot
+      # Supervisor Lifecycle - 4 - Runs the start hooks for logging/hooks
       run_start_hooks
 
+      # Supervisor Lifecycle - 5 - Starts the processes to supervise
       start_processes
+      # Supervisor Lifecycle - 6 - Launches the maintenance task to prune dead processes
       launch_maintenance_task
 
+      # Supervisor Lifecycle - 7 - Enters the main loop to supervise processes
       supervise
     end
 
@@ -55,18 +61,28 @@ def boot
       end
 
       def start_processes
+        # Supervisor Lifecycle - 5.2 - For each configured process, start a process instance.
         configuration.configured_processes.each { |configured_process| start_process(configured_process) }
       end
 
       def supervise
         loop do
+          # Supervisor Lifecycle - 8 - loop untill stopped.
           break if stopped?
 
           set_procline
+          # Supervisor Lifecycle - 9 - Process signal queue to handle signals.
           process_signal_queue
 
           unless stopped?
+            # Supervisor Lifecycle - 10 - Reap terminated forks and replace them.
             reap_and_replace_terminated_forks
+            # Supervisor Lifecycle - 11 - Sleep to avoid busy waiting.  Not using `sleep` directly to allow interruption.
+            # This allows the process to wake up when a signal is received.
+            # This is useful for handling signals like TERM or INT without busy waiting.
+            # It also allows the process to wake up when a fork is terminated.
+            # This is useful for handling the termination of supervised processes.
+            # The sleep time is set to 1 second, but can be adjusted as needed.
             interruptible_sleep(1.second)
           end
         end
@@ -80,6 +96,7 @@ def start_process(configured_process)
           instance.mode = :fork
         end
 
+        # Supervisor Lifecycle - 5.3 - Forks a new process for the configured process.
         pid = fork do
           process_instance.start
         end

lib/solid_queue/supervisor/maintenance.rb

@@ -3,6 +3,7 @@ module Supervisor::Maintenance
     extend ActiveSupport::Concern
 
     included do
+      # Supervisor Lifecycle - 3.1 - Fails orphaned executions.
       after_boot :fail_orphaned_executions
     end
 

lib/solid_queue/supervisor/pidfiled.rb

@@ -6,6 +6,7 @@ module Pidfiled
       extend ActiveSupport::Concern
 
       included do
+        # Supervisor Lifecycle - 3.3 - Manages PID file for the supervisor process.
         before_boot :setup_pidfile
         after_shutdown :delete_pidfile
       end

lib/solid_queue/supervisor/signals.rb

@@ -6,6 +6,7 @@ module Signals
       extend ActiveSupport::Concern
 
       included do
+        # Supervisor Lifecycle - 3.2 - Registers signal handlers to manage process termination.
         before_boot :register_signal_handlers
         after_shutdown :restore_default_signal_handlers
       end
@@ -35,6 +36,7 @@ def process_signal_queue
         end
 
         def handle_signal(signal)
+          # Supervisor Lifecycle - 9.1 - Handles signals to gracefully or immediately stop processes.
           case signal
           when :TERM, :INT
             stop