main_loop 0.1.3.16874 → 0.1.4.367214

data/lib/main_loop/dispatcher.rb

@@ -1,13 +1,50 @@
 require 'monitor'
 require 'logger'
 
+# = MainLoop::Dispatcher
+#
+# Координирует обработчиков, управляет жизненным циклом, обрабатывает сигнал терминации с таймаутом.
+#
+# Использует {MonitorMixin} для потоко-безопасности. Управляет списком обработчиков ({handlers})
+# и обеспечивает корректное завершение всех обработчиков при получении сигнала терминации.
+#
+# == Жизненный цикл обработчиков
+#
+# 1. Регистрация через {add_handler}
+# 2. Обработка сигнала терминации через {term}
+# 3. Если не завершились за timeout → {kill}
+# 4. {try_exit!} когда все завершены
+#
+# == Пример использования
+#
+#   bus = MainLoop::Bus.new
+#   dispatcher = MainLoop::Dispatcher.new(bus, timeout: 10, logger: logger)
+#
+#   MainLoop::ProcessHandler.new dispatcher, 'worker' do
+#     # код процесса
+#   end
+#
+#   dispatcher.term  # инициировать терминацию
+#
+# == См. также
+# - {MainLoop::Bus} — канал событий
+# - {MainLoop::Handler} — базовый класс обработчиков
+# - {MainLoop::Loop} — координирует Dispatcher
+
 module MainLoop
   class Dispatcher
-
     include MonitorMixin
 
     attr_reader :bus, :handlers, :logger
 
+    # == Инициализация
+    #
+    # @param bus [Bus] канал событий
+    # @param timeout [Integer] таймаут для принудительного завершения в секундах (по умолчанию 5)
+    # @param logger [Logger] логгер (по умолчанию Logger.new(nil))
+    # @option bus [Bus]
+    # @option timeout [Integer] 5
+    # @option logger [Logger] nil
     def initialize(bus, timeout: 5, logger: nil)
       super()
       @bus = bus
@@ -17,23 +54,42 @@ module MainLoop
       @exit_code = 0
     end
 
+    # == Обработка завершения процессов
+    #
+    # Обрабатывает массив завершенных процессов.
+    #
+    # @param statuses [Array<Array>] массив пар (pid, status)
+    # @example
+    #   dispatcher.reap([[123, status], [456, nil]])
     def reap(statuses)
       statuses.each do |(pid, status)|
         reap_by_id(pid, status)
       end
     end
 
+    # == Обработка завершения процесса по ID
+    #
+    # Находит обработчика по ID и вызывает его {Handler#reap}.
+    #
+    # @param id [String] идентификатор обработчика (pid для процессов, object_id для потоков)
+    # @param status [Process::Status|nil] статус завершения или nil если неизвестен
     def reap_by_id(id, status)
       synchronize do
         if (handler = handlers.find {|h| h.id == id })
-          logger.info("Reap handler #{handler.name.inspect}. Status: #{status.inspect}")
+          logger.info("Reap handler #{handler.name.inspect}. Status: #{status&.inspect}")
           handler.reap(status)
         else
-          logger.debug("Reap unknown handler. Status: #{status.inspect}. Skipped")
+          logger.debug("Reap unknown handler. Status: #{status&.inspect}. Skipped")
         end
       end
     end
 
+    # == Регистрация обработчика
+    #
+    # Добавляет обработчик в список. Если уже происходит терминация,
+    # сразу посылает `term` новому обработчику.
+    #
+    # @param handler [Handler] обработчик для регистрации
     def add_handler(handler)
       synchronize do
         handler.term if terminating?
@@ -41,10 +97,24 @@ module MainLoop
       end
     end
 
+    # == Проверка терминации
+    #
+    # @return [Time|nil] момент начала терминации или nil если не терминация
     def terminating?
       @terminating_at
     end
 
+    # == Инициировать терминацию
+    #
+    # Отправляет сигнал терминации всем обработчикам.
+    # Если уже в процессе терминации — принудительное завершение (kill).
+    #
+    # Если это первый вызов:
+    # - Устанавливает @terminating_at = Time.now
+    # - Отправляет term каждому обработчику
+    #
+    # Если уже терминация:
+    # - Отправляет kill каждому обработчику
     def term
       synchronize do
         if terminating?
@@ -58,11 +128,19 @@ module MainLoop
       end
     end
 
+    # == Отправить сигнал аварийного завершения
+    #
+    # Устанавливает 코드 выхода 3 и инициирует терминацию.
+    # Если уже терминация — ничего не делает.
     def crash
       @exit_code = 3
       term unless terminating?
     end
 
+    # == Тик цикла диспетчера
+    #
+    # Вызывается в каждом цикле {MainLoop#start_loop_forever}.
+    # Проверяет необходимость принудительного завершения по timeout.
     def tick
       log_status if logger.debug?
       return unless terminating?
@@ -76,14 +154,30 @@ module MainLoop
       handlers.each(&:kill)
     end
 
+    # == Проверка необходимости принудительного завершения
+    #
+    # Проверяет, превышен ли timeout с момента начала терминации.
+    #
+    # @return [Boolean] true если timeout превышен
     def need_force_kill?
       @terminating_at && (Time.now - @terminating_at) >= @timeout
     end
 
+    # == Получить список PID процессов
+    #
+    # @return [Array<Integer>] массив PID всех процессовых обработчиков
     def pids
       handlers.map{|h| h.pid rescue nil }.compact
     end
 
+    # == Завершить программу
+    #
+    # Если все обработчики завершены, вызывает exit с соответствующим кодом.
+    #
+    # Код выхода:
+    # - @exit_code если все обработчики завершились успешно
+    # - 1 если любой обработчик завершился с ошибкой
+    #
     # :nocov:
     def try_exit!
       synchronize do
@@ -97,6 +191,11 @@ module MainLoop
     end
     # :nocov:
 
+    # == Логировать статус
+    #
+    # Логирует текущее состояние обработчиков (DEBUG уровень).
+    # Формат: "Total:N Running:M Finihsed:K. TERM"
+    #
     # :nocov:
     def log_status
       total = handlers.size
@@ -106,7 +205,5 @@ module MainLoop
       logger.debug("Total:#{total} Running:#{running} Finihsed:#{finihsed}. #{term_text}".strip)
     end
     # :nocov:
-
   end
 end
-

data/lib/main_loop/handler.rb

@@ -1,10 +1,61 @@
 require 'logger'
 
+# = MainLoop::Handler
+#
+# Абстрактный базовый класс для обработчиков процессов и потоков.
+#
+# Определяет интерфейс и общую логику:
+# - управление retry_count (количество повторов)
+# - логика handle_retry
+# - предикаты (finished?, success?, running?, terminating?)
+# - обратный вызов on_term
+#
+# == Абстрактные методы (для реализации в подклассах)
+#
+# - {#id} — идентификатор обработчика (pid для процессов, object_id для потоков)
+# - {#term} — отправка сигнала терминации
+# - {#run} — запуск обработчика
+# - {#kill} — принудительное завершение
+# - {#reap(status)} — обработка завершения процесса/потока
+#
+# == Пример использования
+#
+#   class MyHandler < MainLoop::Handler
+#     def id
+#       @process_id
+#     end
+#
+#     def term
+#       Process.kill('TERM', @process_id)
+#     end
+#
+#     def run
+#       @process_id = Process.fork { yield }
+#     end
+#
+#     def kill
+#       Process.kill('KILL', @process_id)
+#     end
+#
+#     def reap(status)
+#       # обработка завершения
+#     end
+#   end
+#
+# == См. также
+# - {MainLoop::ProcessHandler} — реализация для процессов
+# - {MainLoop::ThreadHandler} — реализация для потоков
+
 module MainLoop
   class Handler
-
     attr_reader :dispatcher, :name, :logger
 
+    # == Инициализация
+    #
+    # @param dispatcher [Dispatcher] ссылка на диспетчер
+    # @param name [String] имя обработчика
+    # @param retry_count [Integer, :unlimited] количество повторов после завершения
+    # @param logger [Logger] логгер (по умолчанию Logger.new(nil))
     def initialize(dispatcher, name, *_args, retry_count: 0, logger: nil, **_kwargs)
       @dispatcher = dispatcher
       @name = name
@@ -14,82 +65,126 @@ module MainLoop
       @handler_type = 'Unknown'
     end
 
+    # == Идентификатор (абстрактный)
+    #
+    # @return [String] идентификатор обработчика
+    # @raise [RuntimeError] если не реализован в подклассе
     # :nocov:
     def id(*_args)
       raise 'not implemented!'
     end
     # :nocov:
 
+    # == Терминация (абстрактный)
+    #
+    # Отправляет сигнал терминации обработчику.
+    # @raise [RuntimeError] если не реализован в подклассе
     # :nocov:
     def term(*_args)
       raise 'not implemented!'
     end
     # :nocov:
 
+    # == Запуск (абстрактный)
+    #
+    # Запускает обработчик.
+    # @raise [RuntimeError] если не реализован в подклассе
     # :nocov:
     def run(*_args)
       raise 'not implemented!'
     end
     # :nocov:
 
+    # == Принудительное завершение (абстрактный)
+    #
+    # Принудительно завершает обработчик.
+    # @raise [RuntimeError] если не реализован в подклассе
     # :nocov:
     def kill(*_args)
       raise 'not implemented!'
     end
     # :nocov:
 
+    # == Обработка завершения (абстрактный)
+    #
+    # @param status [Process::Status|nil] статус завершения
+    # @raise [RuntimeError] если не реализован в подклассе
     # :nocov:
     def reap(*_args)
       raise 'not implemented!'
     end
     # :nocov:
 
-    # :nocov:
+    # == Публикация события
+    #
+    # Отправляет событие в канал событий диспетчера.
+    #
+    # @param event [String, Symbol] событие для отправки
     def publish(event)
       dispatcher.bus.puts(event)
     end
-    # :nocov:
 
+    # == Установить обратный вызов терминации
+    #
+    # @param block [Proc] блок кода, который будет вызван при терминации
     def on_term &block
       @on_term = block
     end
 
+    # == Проверка завершения
+    #
+    # @return [Boolean] true если обработчик завершен
     # :nocov:
     def finished?
       @finished
     end
     # :nocov:
 
+    # == Проверка успешного завершения
+    #
+    # @return [Boolean] true если завершен и успешно
     # :nocov:
     def success?
       finished? && @success
     end
     # :nocov:
 
+    # == Проверка запущенности
+    #
+    # @return [Boolean] true если обработчик работает
     # :nocov:
     def running?
       !finished?
     end
     # :nocov:
 
+    # == Проверка терминации
+    #
+    # @return [Time|nil] момент начала терминации или nil
     # :nocov:
     def terminating?
       @terminating_at
     end
     # :nocov:
 
+    # == Логика повторов
+    #
+    # Управляет повторами после завершения:
+    # - :unlimited — бесконечные повторы
+    # - Integer >= 0 — декремент и повтор
+    # - иначе — отправляет term через bus
+    #
+    # @return void
     def handle_retry
       if @retry_count == :unlimited
         logger.info "#{@handler_type}[#{name}] retry...."
-        self.run(&@block)
+        self.run
       elsif @retry_count && (@retry_count -= 1) >= 0
         logger.info "#{@handler_type}[#{name}] retry...."
-        self.run(&@block)
+        self.run
       else
         publish(:term)
       end
     end
-
   end
 end
-

data/lib/main_loop/loop.rb

@@ -2,13 +2,49 @@ require 'logger'
 require 'timeouter'
 
 module MainLoop
-
+  # Сигналы для терминации
+  # @return [Array<String>]
   TERM_SIGNALS = %w[INT TERM].freeze
 
-  class Loop
+  # = MainLoop::Loop
+  #
+  # Главный цикл управления, запускает обработку сигналов, обрабатывает события из Bus.
+  #
+  # == Жизненный цикл
+  #
+  # 1. {#run} устанавливает {#install_signal_handlers}
+  # 2. {#start_loop_forever} запускает цикл обработки событий
+  # 3. События из Bus обрабатываются через case:
+  #    - 'term' → {#term}
+  #    - 'crash' → {#crash}
+  #    - /sig:/ → {#signal}
+  #    - /reap:/ → {#reap}
+  #    - nil → reap_children (timeout)
+  # 4. {Dispatcher#reap} получает завершенные процессы
+  # 5. {Dispatcher#tick} проверяет необходимость принудительного завершения
+  #
+  # == Пример использования
+  #
+  #   bus = MainLoop::Bus.new
+  #   dispatcher = MainLoop::Dispatcher.new(bus, timeout: 10)
+  #   loop = MainLoop::Loop.new(bus, dispatcher)
+  #
+  #   loop.run(30)  # запуск с таймаутом 30 секунд
+  #
+  # == См. также
+  # - {MainLoop::Bus} — канал событий
+  # - {MainLoop::Dispatcher} — координирует обработчики
+  # - {MainLoop::ProcessHandler} — обработчики процессов
+  # - {MainLoop::ThreadHandler} — обработчики потоков
 
+  class Loop
     attr_reader :logger
 
+    # == Инициализация
+    #
+    # @param bus [Bus] канал событий
+    # @param dispatcher [Dispatcher] диспетчер обработчиков
+    # @param logger [Logger] логгер (по умолчанию Logger.new(nil))
     def initialize(bus, dispatcher, logger: nil)
       STDOUT.sync = true
       STDERR.sync = true
@@ -17,6 +53,12 @@ module MainLoop
       @logger = logger || Logger.new(nil)
     end
 
+    # == Запуск цикла
+    #
+    # Устанавливает обработчики сигналов и запускает {#start_loop_forever}.
+    #
+    # @param timeout [Numeric] таймаут цикла в секундах (0 = бесконечный)
+    # @raise [StandardError] если произошла ошибка в цикле
     def run(timeout = 0)
       install_signal_handlers(@bus)
 
@@ -28,7 +70,18 @@ module MainLoop
       # :nocov:
     end
 
+    # == Главный цикл обработки событий
+    #
+    # Цикл с ограниченным временем работы (через Timeouter).
+    #
+    # Интервал ожидания событий:
+    #   wait = [[(timeout / 2.5), 5].min, 5].max
+    # Минимум 5 секунд (даже при timeout = 0)
+    #
+    # @param timeout [Numeric] таймаут цикла в секундах (0 = бесконечный)
     def start_loop_forever(timeout = 0)
+      # TODO поскольку wait всегда равен 5 секунд, то цикл работы 5 секунд, и потому 
+      # timeout для Dispatcher нужно ставить больше 2 циклов, чтобы успели завершиться все потоки или процессы
       wait = [[(timeout / 2.5), 5].min, 5].max
       Timeouter.loop(timeout) do
         event = @bus.gets(wait)
@@ -54,6 +107,11 @@ module MainLoop
       end
     end
 
+    # == Установка обработчиков сигналов
+    #
+    # Устанавливает trap для TERM, INT и CLD.
+    # Сигналы отправляются в Bus через отдельные потоки.
+    #
     # :nocov:
     def install_signal_handlers(bus)
       TERM_SIGNALS.each do |sig|
@@ -68,6 +126,9 @@ module MainLoop
     end
     # :nocov:
 
+    # == Обработка сигнала
+    #
+    # @param command [String] команда вида "sig:NAME"
     def signal(command)
       _, sig = command.split(':')
       logger.debug("signal:#{sig}")
@@ -81,25 +142,86 @@ module MainLoop
       end
     end
 
+    # == Инициировать терминацию
+    #
+    # Передает команду терминации диспетчеру (если не уже терминация).
+    #
+    # @param _command [String] команда (Unused)
     def term(_command)
       @dispatcher.term unless @dispatcher.terminating?
     end
 
+    # == Отправить сигнал аварийного завершения
+    #
+    # Передает команду crash диспетчеру.
+    #
+    # @param _command [String] команда (Unused)
     def crash(_command)
       @dispatcher.crash
     end
 
+    # == Обработка завершения процесса
+    #
+    # Парсит команду "reap:id:status" и отправляет в диспетчер.
+    #
+    # @param command [String] команда вида "reap:id:status"
     def reap(command)
       _, id, status = command.split(':')
       @dispatcher.reap_by_id(id, status)
     end
 
+    # == Сбор завершенных процессов
+    #
+    # Проходит по всем PID обработчиков и собирает их статусы через wait2.
+    # Дополнительно собирает все оставшиеся дочерние процессы (wait2(-1)).
+    #
+    # == Особенности обработки ECHILD
+    #
+    # Если процесс завершился и был "съеден" другой системой (например, родительский процесс
+    # вызвал Process.wait в on_term обработчике), то Process.wait2(pid) вызовет Errno::ECHILD.
+    # Это нормальное поведение в Unix/Linux когда PID больше не существует в таблице процессов.
+    #
+    # В этом случае:
+    # - Мы добавляем [pid, nil] в результат, чтобы отметить, что процесс не найден
+    # - Обработка продолжается для остальных процессов в списке
+    # - Это предотвращает "зависание" обработки всех остальных процессов
+    #
+    # Пример сценария (см. test_process.rb):
+    # 1. ProcessHandler запускает процесс с PID 123
+    # 2. При терминации вызывается on_term(pid) в обработчике
+    # 3. on_term вызывает Process.wait(pid) и "съедает" статус
+    # 4. Позже reap_children пытается wait2(123) и получает ECHILD
+    # 5. Обработка продолжается для других процессов, а 123 помечается как [123, nil]
+    #
+    # == Логика обработки
+    #
+    # Метод проходит по каждому PID из @dispatcher.pids:
+    # - wait2(pid) возвращает [pid, status] если процесс найден
+    # - wait2(pid) возвращает nil если процесс еще не завершился
+    # - wait2(pid) вызывает Errno::ECHILD если PID уже не существует
+    #
+    # Для каждого случая:
+    # - Нам возвращается [pid, status] -> добавляем в results
+    # - Возвращается nil -> ничего не добавляем (не завершился)
+    # - ECHILD -> добавляем [pid, nil] (PID не найден, съеден другой системой)
+    #
+    # После обработки всех известных PID, делается wait2(-1) для сбора
+    # любых оставшихся дочерних процессов (с таймаутом 2 секунды).
+    #
+    # @return [Array<Array>] массив пар (pid, status)
     def reap_children
       results = []
 
       @dispatcher.pids.each do |pid|
-        if (result = self.wait2(pid))
-          results << result
+        begin
+          if (result = self.wait2(pid))
+            results << result
+          end
+        rescue Errno::ECHILD
+          # Процесс "съеден" другой системой (например, Process.wait вызван в on_term)
+          # или процесс уже завершился и pid больше не существует
+          # Добавляем [pid, nil] чтобы отметить его и продолжить обработку остальных
+          results << [pid, nil]
         end
       end
 
@@ -116,13 +238,16 @@ module MainLoop
       results
     end
 
+    # == Ожидание завершения процесса
+    #
+    # Обертка для Process.wait2 с флагом WNOHANG.
+    #
+    # @param pid [Integer] PID процесса для ожидания
+    # @return [Array<Integer, Process::Status>|nil] пара (pid, status) или nil если нет завершенных
     # :nocov:
     def wait2(pid)
       Process.wait2(pid, ::Process::WNOHANG)
     end
     # :nocov:
-
   end
-
 end
-