bluepill 0.1.3 → 0.1.4

data/lib/bluepill/process.rb

@@ -5,9 +5,20 @@ require 'state_machine'
 require 'daemons'
 require 'bluepill/system'
 require 'bluepill/process_journal'
+require 'bluepill/process_commands'
 
 module Bluepill
+  # A process that bluepill monitors
+  #
+  # Its state machine moves it between unmonitored, up, down, starting,
+  # stopping and restarting. Every tick checks that it's still running,
+  # runs its watches, and fires the events they ask for.
+  #
+  # @api private
   class Process
+    include ProcessCommands
+
+    # The options a config can set for a process
     CONFIGURABLE_ATTRIBUTES = [
       :pre_start_command,
       :start_command,
@@ -51,9 +62,301 @@ module Bluepill
 
     ].freeze
 
-    attr_accessor :name, :watches, :triggers, :logger, :skip_ticks_until, :process_running
-    attr_accessor(*CONFIGURABLE_ATTRIBUTES)
-    attr_reader :children, :statistics
+    # Return the process's name, which commands and logs use
+    #
+    # @return [String]
+    #
+    # @api private
+    attr_accessor :name
+
+    # Return the checks that run on the process every interval
+    #
+    # @return [Array<ConditionWatch>]
+    #
+    # @api private
+    attr_accessor :watches
+
+    # Return the triggers notified of the process's transitions
+    #
+    # @return [Array<Trigger>]
+    #
+    # @api private
+    attr_accessor :triggers
+
+    # Return the time, in epoch seconds, before which ticks are skipped
+    #
+    # Set while a start, stop or restart command has its grace time to take
+    # effect.
+    #
+    # @return [Integer, nil]
+    #
+    # @api private
+    attr_accessor :skip_ticks_until
+
+    # Return whether the process was running when last checked this tick
+    #
+    # tick clears it, so the first check of each tick signals the process.
+    #
+    # @return [Boolean, nil]
+    #
+    # @api private
+    attr_accessor :process_running
+
+    # Return the command run before every start, if any
+    #
+    # Bluepill waits for it to finish, and starts the process even if it exits
+    # with a non-zero status. It runs in the process's working_dir, with its
+    # environment, uid and gid.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :pre_start_command
+
+    # Return the command that starts the process
+    #
+    # Bluepill splits it into words and runs it without a shell.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :start_command
+
+    # Return the command that stops the process, if any
+    #
+    # <tt>{{PID}}</tt> in it is replaced with the process's pid. Without
+    # one, bluepill sends stop_signals, or TERM.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :stop_command
+
+    # Return the command that restarts the process, if any
+    #
+    # <tt>{{PID}}</tt> in it is replaced with the process's pid. Without
+    # one, bluepill stops the process and starts it again.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :restart_command
+
+    # Return the file a daemonized process's standard output goes to
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :stdout
+
+    # Return the file a daemonized process's standard error goes to
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :stderr
+
+    # Return the file a daemonized process's standard input comes from
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :stdin
+
+    # Return whether bluepill daemonizes the process and writes its pid file
+    #
+    # Set it for a process that doesn't daemonize itself.
+    #
+    # @return [Boolean, nil]
+    #
+    # @api private
+    attr_accessor :daemonize
+
+    # Return the file that holds the process's pid
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :pid_file
+
+    # Return the directory the process's commands run in
+    #
+    # A daemonized process starts in / unless this is set.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :working_dir
+
+    # Return the environment variables the process's commands get
+    #
+    # @return [Hash{#to_s => #to_s}, nil]
+    #
+    # @api private
+    attr_accessor :environment
+
+    # Return how long to wait for the process to start, in seconds
+    #
+    # Bluepill skips ticks for this long after a start. The default is 3.
+    #
+    # @return [Integer, Float]
+    #
+    # @api private
+    attr_accessor :start_grace_time
+
+    # Return how long to wait for the process to stop, in seconds
+    #
+    # Bluepill skips ticks for this long after a stop. The default is 3.
+    #
+    # @return [Integer, Float]
+    #
+    # @api private
+    attr_accessor :stop_grace_time
+
+    # Return how long to wait for the process to restart, in seconds
+    #
+    # Bluepill skips ticks for this long after a restart. The default is 3.
+    #
+    # @return [Integer, Float]
+    #
+    # @api private
+    attr_accessor :restart_grace_time
+
+    # Return the user the process's commands run as
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :uid
+
+    # Return the group the process's commands run as
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :gid
+
+    # Return whether to read the pid file only until it gives a pid
+    #
+    # True by default. Set it to false for a process whose pid changes, such
+    # as one checked for zombies.
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :cache_actual_pid
+
+    # Return whether bluepill also watches the process's children
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :monitor_children
+
+    # Return the factory that makes a Process for each child found
+    #
+    # monitor_children sets it, with the children's checks.
+    #
+    # @return [ProcessFactory, nil]
+    #
+    # @api private
+    attr_accessor :child_process_factory
+
+    # Return the command whose output is the process's pid, if any
+    #
+    # Used instead of pid_file when it's set.
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    attr_accessor :pid_command
+
+    # Return whether bluepill starts the process when it loads
+    #
+    # Only false keeps it from starting: the process is then unmonitored.
+    #
+    # @return [Boolean, nil]
+    #
+    # @api private
+    attr_accessor :auto_start
+
+    # Return the extra groups the process's commands run with
+    #
+    # @return [Array<String>, nil]
+    #
+    # @api private
+    attr_accessor :supplementary_groups
+
+    # Return the signals that stop the process, with the delays between
+    #
+    # A signal, then a delay in seconds and a signal, and so on, such as
+    # [:quit, 30, :term, 5, :kill]. Each later signal is only sent if the
+    # process is still running.
+    #
+    # @return [Array<Symbol, Integer>, nil]
+    #
+    # @api private
+    attr_accessor :stop_signals
+
+    # Return the event to dispatch when the start command takes too long
+    #
+    # The default is start, which tries again.
+    #
+    # @return [String, Symbol]
+    #
+    # @api private
+    attr_accessor :on_start_timeout
+
+    # Return whether a group's start runs without waiting for this process
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :group_start_noblock
+
+    # Return whether a group's restart runs without waiting for this process
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :group_restart_noblock
+
+    # Return whether a group's stop runs without waiting for this process
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :group_stop_noblock
+
+    # Return whether a group's unmonitor runs without waiting for it
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    attr_accessor :group_unmonitor_noblock
+
+    # Return the processes made for the process's children
+    #
+    # Only filled when monitor_children is set.
+    #
+    # @return [Array<Process>]
+    #
+    # @api private
+    attr_reader :children
+
+    # Return the process's recent events
+    #
+    # @return [ProcessStatistics]
+    #
+    # @api private
+    attr_reader :statistics
+
+    # Return the logger, prefixed with the process's name
+    #
+    # @return [Logger]
+    #
+    # @api private
+    attr_reader :logger
 
     state_machine initial: :unmonitored do
       # These are the idle states, i.e. only an event (either external or internal) will trigger a transition.
@@ -109,6 +412,21 @@ module Bluepill
       after_transition any => any, do: :record_transition
     end
 
+    # Create a process from its checks and options
+    #
+    # Each check is a watch, or a trigger if one has its name. Options that
+    # aren't given keep their defaults: 3 second grace times, a cached pid,
+    # and children left alone.
+    #
+    # @param [String] process_name the process's name
+    # @param [Hash{Symbol => Hash{Symbol => Object}}] checks options by
+    #   check name
+    # @param [Hash{Symbol => Object}] options the process's options, such as
+    #   CONFIGURABLE_ATTRIBUTES, :logger and :actual_pid
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(process_name, checks, options = {})
       @name = process_name
       @event_mutex = Monitor.new
@@ -137,15 +455,24 @@ module Bluepill
       @group_start_noblock = @group_stop_noblock = @group_restart_noblock = @group_unmonitor_noblock = true
 
       CONFIGURABLE_ATTRIBUTES.each do |attribute_name|
-        send("#{attribute_name}=", options[attribute_name]) if options.key?(attribute_name)
+        public_send("#{attribute_name}=", options.fetch(attribute_name)) if options.key?(attribute_name)
       end
 
       # Let state_machine do its initialization stuff
       super() # no arguments intentional
     end
 
+    # Check on the process once a tick
+    #
+    # Unless ticks are being skipped, fire the state machine's tick event, and
+    # then, for a process that's up, run its watches and tick its children.
+    #
+    # @return [void]
+    #
+    # @api private
     def tick
       return if skipping_ticks?
+
       self.skip_ticks_until = nil
 
       # clear the memoization per tick
@@ -154,33 +481,61 @@ module Bluepill
       # Deal with thread cleanup here since the stopping state isn't used
       clean_threads if unmonitored?
 
-      # run state machine transitions
-      super
+      # run state machine transitions. state_machine defines tick in a
+      # module it creates, which the signatures can't name.
+      super # steep:ignore UnexpectedSuper
 
       return unless up?
+
       run_watches
 
       return unless monitor_children?
+
       refresh_children!
       children.each(&:tick)
     end
 
+    # Set the logger, for the process and for its watches and triggers
+    #
+    # @param [Logger] logger the logger to use
+    #
+    # @return [void]
+    #
+    # @api private
     def logger=(logger)
       @logger = logger
       watches.each { |w| w.logger = logger }
       triggers.each { |t| t.logger = logger }
     end
 
-    # State machine methods
+    # Record an event and fire it on the state machine
+    #
+    # @param [Symbol, String] event the event, such as :start or :restart
+    # @param [String, nil] reason why, for the process's event history
+    #
+    # @return [Boolean] whether the state machine made the transition
+    #
+    # @api private
     def dispatch!(event, reason = nil)
       @event_mutex.synchronize do
         @statistics.record_event(event, reason)
-        send(event.to_s)
+        public_send(event)
       end
     end
 
+    # Clear the watches' history after the process changes state
+    #
+    # A process that's monitoring its children also clears their list, so it
+    # finds them again. A loopback, such as up to up, changes nothing.
+    #
+    # @param [#from_name, #to_name, #loopback?] transition the transition
+    #
+    # @return [void]
+    #
+    # @api private
     def record_transition(transition)
       return if transition.loopback?
+
       @transitioned = true
 
       # When a process changes state, we should clear the memory of all the watches
@@ -194,56 +549,105 @@ module Bluepill
       logger.info "Going from #{transition.from_name} => #{transition.to_name}"
     end
 
+    # Tell every trigger about a transition
+    #
+    # @param [#from_name, #to_name, #loopback?] transition the transition
+    #
+    # @return [void]
+    #
+    # @raise [StandardError] what a trigger raised, after logging it
+    #
+    # @api private
     def notify_triggers(transition)
       triggers.each do |trigger|
         begin
           trigger.notify(transition)
-        rescue => e
+        rescue StandardError => e
           logger.err e.backtrace
-          raise e
+          raise
         end
       end
     end
 
-    # Watch related methods
-    def add_watch(name, options = {})
+    # Add a check to run on the process every interval
+    #
+    # @param [Symbol] name the check's name, such as :mem_usage
+    # @param [Hash{Symbol => Object}] options the check's options
+    #
+    # @return [Array<ConditionWatch>] the process's watches
+    #
+    # @api private
+    def add_watch(name, options)
       watches << ConditionWatch.new(name, options.merge(logger: logger))
     end
 
-    def add_trigger(name, options = {})
+    # Add a trigger to notify of the process's transitions
+    #
+    # @param [Symbol] name the trigger's name, such as :flapping
+    # @param [Hash{Symbol => Object}] options the trigger's options
+    #
+    # @return [Array<Trigger>] the process's triggers
+    #
+    # @api private
+    def add_trigger(name, options)
       triggers << Trigger[name].new(self, options.merge(logger: logger))
     end
 
+    # Run every watch, and dispatch the events they fire
+    #
+    # Each watch runs in a thread of its own. Once an event changes the
+    # process's state, the events after it are dropped.
+    #
+    # @return [void]
+    #
+    # @api private
     def run_watches
-      now = Time.now.to_i
+      now = Integer(Time.now)
 
       threads = watches.collect do |watch|
-        [watch, Thread.new { Thread.current[:events] = watch.run(actual_pid, now) }]
+        [watch, Thread.new { watch.run(actual_pid, now) }] #: [ConditionWatch, Thread]
       end
 
       @transitioned = false
 
       threads.each_with_object([]) do |(watch, thread), events|
-        thread.join
-        next if thread[:events].size.zero?
-        logger.info "#{watch.name} dispatched: #{thread[:events].join(',')}"
-        thread[:events].each do |event|
+        watch_events = thread.value #: Array[Symbol]
+        next if watch_events.empty?
+
+        logger.info "#{watch.name} dispatched: #{watch_events.join(',')}"
+        watch_events.each do |event|
           events << [event, watch.to_s]
         end
       end.each do |event, reason| # rubocop:disable Style/MultilineBlockChain
         break if @transitioned
+
         dispatch!(event, reason)
       end
     end
 
+    # Set the state to up, down or unmonitored when bluepill loads
+    #
+    # A running process is up. Otherwise it's down, so that it starts, unless
+    # auto_start is false.
+    #
+    # @return [void]
+    #
+    # @api private
     def determine_initial_state
       if process_running?(true)
         self.state = 'up'
         return
       end
-      self.state = (auto_start == false) ? 'unmonitored' : 'down' # we need to check for false value
+      self.state = auto_start.equal?(false) ? 'unmonitored' : 'down' # we need to check for false value
     end
 
+    # Carry out a command from the command line
+    #
+    # @param [String] cmd start, stop, restart or unmonitor
+    #
+    # @return [void]
+    #
+    # @api private
     def handle_user_command(cmd)
       case cmd
       when 'start'
@@ -265,209 +669,205 @@ module Bluepill
       end
     end
 
-    # System Process Methods
+    # Return whether the process is running, and forget its pid if not
+    #
+    # The answer is kept for the rest of the tick.
+    #
+    # @param [Boolean] force whether to check again this tick
+    #
+    # @return [Boolean]
+    #
+    # @api private
     def process_running?(force = false)
       @process_running = nil if force # clear existing state if forced
 
       @process_running ||= signal_process(0)
       # the process isn't running, so we should clear the PID
       clear_pid unless @process_running
-      @process_running
-    end
-
-    def start_process
-      ProcessJournal.kill_all_from_journal(name) # be sure nothing else is running from previous runs
-      pre_start_process
-      logger.warning "Executing start command: #{start_command}"
-      if daemonize?
-        daemon_id = System.daemonize(start_command, system_command_options)
-        if daemon_id
-          ProcessJournal.append_pid_to_journal(name, daemon_id)
-          children.each do |child|
-            ProcessJournal.append_pid_to_journal(name, child.actual_pid)
-          end if monitor_children?
-        end
-        daemon_id
-      else
-        # This is a self-daemonizing process
-        with_timeout(start_grace_time, on_start_timeout) do
-          result = System.execute_blocking(start_command, system_command_options)
-
-          unless result[:exit_code].zero?
-            logger.warning 'Start command execution returned non-zero exit code:'
-            logger.warning result.inspect
-          end
-        end
-      end
-
-      skip_ticks_for(start_grace_time)
-    end
-
-    def pre_start_process
-      return unless pre_start_command
-      logger.warning "Executing pre start command: #{pre_start_command}"
-      result = System.execute_blocking(pre_start_command, system_command_options)
-      return if result[:exit_code].zero?
-      logger.warning 'Pre start command execution returned non-zero exit code:'
-      logger.warning result.inspect
-    end
-
-    def stop_process
-      if monitor_children
-        System.get_children(actual_pid).each do |child_pid|
-          ProcessJournal.append_pid_to_journal(name, child_pid)
-        end
-      end
-
-      if stop_command
-        cmd = prepare_command(stop_command)
-        logger.warning "Executing stop command: #{cmd}"
-
-        with_timeout(stop_grace_time, 'stop') do
-          result = System.execute_blocking(cmd, system_command_options)
-
-          unless result[:exit_code].zero?
-            logger.warning 'Stop command execution returned non-zero exit code:'
-            logger.warning result.inspect
-          end
-        end
-        cleanup_process
-      elsif stop_signals
-        # issue stop signals with configurable delay between each
-        logger.warning "Sending stop signals to #{actual_pid}"
-        @threads << Thread.new(self, stop_signals.clone) do |process, stop_signals|
-          signal = stop_signals.shift
-          logger.info "Sending signal #{signal} to #{process.actual_pid}"
-          process.signal_process(signal) # send first signal
-
-          until stop_signals.empty?
-            # we already checked to make sure stop_signals had an odd number of items
-            delay = stop_signals.shift
-            signal = stop_signals.shift
-
-            logger.debug "Sleeping for #{delay} seconds"
-            sleep delay
-            # break unless signal_process(0) #break unless the process can be reached
-            unless process.signal_process(0)
-              logger.debug 'Process has terminated.'
-              break
-            end
-            logger.info "Sending signal #{signal} to #{process.actual_pid}"
-            process.signal_process(signal)
-          end
-          cleanup_process
-        end
-      else
-        logger.warning "Executing default stop command. Sending TERM signal to #{actual_pid}"
-        signal_process('TERM')
-        cleanup_process
-      end
-
-      skip_ticks_for(stop_grace_time)
-    end
-
-    def restart_process
-      if restart_command
-        cmd = prepare_command(restart_command)
-
-        logger.warning "Executing restart command: #{cmd}"
-
-        with_timeout(restart_grace_time, 'restart') do
-          result = System.execute_blocking(cmd, system_command_options)
-
-          unless result[:exit_code].zero?
-            logger.warning 'Restart command execution returned non-zero exit code:'
-            logger.warning result.inspect
-          end
-        end
-
-        skip_ticks_for(restart_grace_time)
-      else
-        logger.warning 'No restart_command specified. Must stop and start to restart'
-        stop_process
-        start_process
-      end
-    end
-
-    def cleanup_process
-      ProcessJournal.kill_all_from_journal(name) # finish cleanup
-      unlink_pid # TODO: we only write the pid file if we daemonize, should we only unlink it if we daemonize?
+      @process_running #: bool
     end
 
+    # Kill the threads the process's commands left running
+    #
+    # @return [void]
+    #
+    # @api private
     def clean_threads
       @threads.each(&:kill)
       @threads.clear
     end
 
+    # Return whether bluepill daemonizes the process
+    #
+    # @return [Boolean]
+    #
+    # @api private
     def daemonize?
       !!daemonize
     end
 
+    # Return whether bluepill watches the process's children
+    #
+    # @return [Boolean]
+    #
+    # @api private
     def monitor_children?
       !!monitor_children
     end
 
+    # Send a signal to the process
+    #
+    # A process without a pid isn't running, so it gets no signal and nothing
+    # is logged. A failure is logged.
+    #
+    # @param [Integer, String, Symbol] code the signal, such as 0 or :term
+    #
+    # @return [Boolean] whether the signal was sent
+    #
+    # @api private
     def signal_process(code)
-      code = code.to_s.upcase if code.is_a?(String) || code.is_a?(Symbol)
-      ::Process.kill(code, actual_pid)
+      code = code.to_s.upcase if code.is_a?(String) || code.instance_of?(Symbol)
+      pid = actual_pid
+      # Without a pid the process isn't running. That's expected before the
+      # first start, and actual_pid already warns about a missing pid file.
+      return false unless pid
+
+      # kill with a pid of 0 or less signals a whole process group, which
+      # could include bluepill itself, so only signal a real pid
+      raise "invalid pid #{pid}" unless pid > 0
+
+      ::Process.kill(code, pid)
       true
-    rescue => e
-      logger.err "Failed to signal process #{actual_pid} with code #{code}: #{e}"
+    rescue StandardError => e
+      logger.err "Failed to signal process #{pid} with code #{code}: #{e}"
       false
     end
 
+    # Return whether the pid is kept once it's read
+    #
+    # @return [Boolean]
+    #
+    # @api private
     def cache_actual_pid?
       !!@cache_actual_pid
     end
 
+    # Return the process's pid, from pid_command or the pid file
+    #
+    # @return [Integer, nil] the pid, or nil if there's none yet
+    #
+    # @api private
     def actual_pid
       pid_command ? pid_from_command : pid_from_file
     end
 
+    # Return the pid in the pid file, cached unless cache_actual_pid is false
+    #
+    # A missing pid file is logged as a warning.
+    #
+    # @return [Integer, nil] the pid, or nil without a pid file or a pid
+    #
+    # @api private
     def pid_from_file
       return @actual_pid if cache_actual_pid? && @actual_pid
-      @actual_pid = begin
-        if pid_file
-          if File.exist?(pid_file)
-            str = File.read(pid_file)
-            str.to_i unless str.empty?
-          else
-            logger.warning("pid_file #{pid_file} does not exist or cannot be read")
-            nil
-          end
-        end
-      end
-    end
 
+      @actual_pid = if pid_file
+                      if File.exist?(pid_file)
+                        positive_pid(File.read(pid_file).to_i)
+                      else
+                        logger.warning("pid_file #{pid_file} does not exist or cannot be read")
+                        nil
+                      end
+                    end
+    end
+
+    # Return the pid that pid_command prints
+    #
+    # Output that isn't only digits gives no pid.
+    #
+    # @return [Integer, nil] the pid, or nil if the output isn't one
+    #
+    # @api private
     def pid_from_command
-      pid = `#{pid_command}`.strip
-      (pid =~ /\A\d+\z/) ? pid.to_i : nil
-    end
-
+      # Output that is not just digits reads as nil, so as 0
+      positive_pid(`#{pid_command}`.strip[/\A\d+\z/].to_i)
+    end
+
+    # Return the pid, unless it's 0 or less
+    #
+    # An empty or garbled pid file reads as 0, which is never a real process.
+    #
+    # @param [Integer] pid the pid that was read
+    #
+    # @return [Integer, nil] the pid, or nil if it's not a real one
+    #
+    # @api private
+    def positive_pid(pid)
+      pid if pid > 0
+    end
+
+    # Set the pid, and add it to the process's journal
+    #
+    # @param [Integer] pid the process's pid
+    #
+    # @return [void]
+    #
+    # @api private
     def actual_pid=(pid)
       ProcessJournal.append_pid_to_journal(name, pid) # be sure to always log the pid
       @actual_pid = pid
     end
 
+    # Forget the process's pid
+    #
+    # @return [nil]
+    #
+    # @api private
     def clear_pid
       @actual_pid = nil
     end
 
+    # Delete the pid file, if there is one
+    #
+    # @return [void]
+    #
+    # @api private
     def unlink_pid
       System.delete_if_exists(pid_file)
     end
 
-    # Internal State Methods
+    # Skip ticks for a while, such as for a command's grace time
+    #
+    # The times add up, so a stop followed by a start, which is how
+    # restart_process works without a restart_command, waits out both grace
+    # times.
+    #
+    # @param [Integer, Float] seconds how long to skip ticks for
+    #
+    # @return [Integer] when ticks resume, in epoch seconds
+    #
+    # @api private
     def skip_ticks_for(seconds)
-      # TODO: should this be addative or longest wins?
-      #       i.e. if two calls for skip_ticks_for come in for 5 and 10, should it skip for 10 or 15?
-      self.skip_ticks_until = (skip_ticks_until || Time.now.to_i) + seconds.to_i
+      self.skip_ticks_until = (skip_ticks_until || Integer(Time.now)) + Integer(seconds)
     end
 
+    # Return whether ticks are being skipped
+    #
+    # @return [Boolean, nil]
+    #
+    # @api private
     def skipping_ticks?
-      skip_ticks_until && skip_ticks_until > Time.now.to_i
+      skip_ticks_until && skip_ticks_until > Integer(Time.now)
     end
 
+    # Update the list of children from the tick's ps table
+    #
+    # Children that are no longer running are dropped, and a Process is made
+    # for each new one, with the checks monitor_children gave.
+    #
+    # @return [void]
+    #
+    # @api private
     def refresh_children!
       # First prune the list of dead children
       @children.delete_if { |child| !child.process_running?(true) }
@@ -475,48 +875,19 @@ module Bluepill
       # Add new found children to the list
       new_children_pids = System.get_children(actual_pid) - @children.collect(&:actual_pid)
 
-      unless new_children_pids.empty?
-        logger.info "Existing children: #{@children.collect(&:actual_pid).join(',')}. Got new children: #{new_children_pids.inspect} for #{actual_pid}"
-      end
+      logger.info "Existing children: #{@children.collect(&:actual_pid).join(',')}. Got new children: #{new_children_pids} for #{actual_pid}" unless new_children_pids.empty?
 
       # Construct a new process wrapper for each new found children
+      # monitor_children sets the factory
+      factory = child_process_factory #: ProcessFactory
       new_children_pids.each do |child_pid|
         ProcessJournal.append_pid_to_journal(name, child_pid) if daemonize?
         child_name = "<child(pid:#{child_pid})>"
-        logger = self.logger.prefix_with(child_name)
+        child_logger = logger.prefix_with(child_name)
 
-        child = child_process_factory.create_child_process(child_name, child_pid, logger)
+        child = factory.create_child_process(child_name, child_pid, child_logger)
         @children << child
       end
     end
-
-    def prepare_command(command)
-      command.to_s.gsub('{{PID}}', actual_pid.to_s)
-    end
-
-    def system_command_options
-      {
-        uid: uid,
-        gid: gid,
-        working_dir: working_dir,
-        environment: environment,
-        pid_file: pid_file,
-        logger: logger,
-        stdin: stdin,
-        stdout: stdout,
-        stderr: stderr,
-        supplementary_groups: supplementary_groups,
-      }
-    end
-
-    def with_timeout(secs, next_state = nil, &blk)
-      # Attempt to execute the passed block. If the block takes
-      # too long, transition to the indicated next state.
-      Timeout.timeout(secs.to_f, &blk)
-    rescue Timeout::Error
-      logger.err 'Execution is taking longer than expected.'
-      logger.err 'Did you forget to tell bluepill to daemonize this process?'
-      dispatch!(next_state)
-    end
   end
 end