main_loop 0.1.4.364822 → 0.1.4.369901

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,12 +54,25 @@ 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 })
@@ -34,6 +84,12 @@ module MainLoop
       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,16 +191,19 @@ module MainLoop
     end
     # :nocov:
 
+    # == Логировать статус
+    #
+    # Логирует текущее состояние обработчиков (DEBUG уровень).
+    # Формат: "Total:N Running:M Finished:K. Success:[] TERM"
+    #
     # :nocov:
     def log_status
       total = handlers.size
       running = handlers.count(&:running?)
       finihsed = handlers.count(&:finished?)
       term_text = terminating? ? 'TERM' : ''
-      logger.debug("Total:#{total} Running:#{running} Finihsed:#{finihsed}. #{term_text}".strip)
+      logger.debug("Total:#{total} Running:#{running} Finished:#{finihsed} Success:#{handlers.map {|h| h.success?}.to_s}. #{term_text}".strip)
     end
     # :nocov:
-
   end
 end
-

data/lib/main_loop/handler.rb

@@ -1,10 +1,37 @@
 require 'logger'
 
+# = MainLoop::Handler
+#
+# Абстрактный базовый класс для обработчиков процессов и потоков.
+#
+# Определяет интерфейс и общую логику:
+# - управление retry_count (количество повторов)
+# - логика handle_retry
+# - предикаты (finished?, success?, running?, terminating?)
+# - обратный вызов on_term
+#
+# == Абстрактные методы (для реализации в подклассах)
+#
+# - {#id} — идентификатор обработчика (pid для процессов, object_id для потоков)
+# - {#term} — отправка сигнала терминации
+# - {#run} — запуск обработчика
+# - {#kill} — принудительное завершение
+# - {#reap(status)} — обработка завершения процесса/потока
+#
+# == См. также
+# - {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,70 +41,116 @@ 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...."
@@ -89,7 +162,5 @@ module MainLoop
         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,9 +70,18 @@ module MainLoop
       # :nocov:
     end
 
-    # TODO поскольку wait всегда равен 5 секунд, то цикл работы 5 секунд, и потому 
-    # timeout для Dispatcher нужно ставить больше 2 циклов, чтобы успели завершиться все потоки или процессы
+    # == Главный цикл обработки событий
+    #
+    # Цикл с ограниченным временем работы (через 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)
@@ -56,6 +107,11 @@ module MainLoop
       end
     end
 
+    # == Установка обработчиков сигналов
+    #
+    # Устанавливает trap для TERM, INT и CLD.
+    # Сигналы отправляются в Bus через отдельные потоки.
+    #
     # :nocov:
     def install_signal_handlers(bus)
       TERM_SIGNALS.each do |sig|
@@ -70,6 +126,9 @@ module MainLoop
     end
     # :nocov:
 
+    # == Обработка сигнала
+    #
+    # @param command [String] команда вида "sig:NAME"
     def signal(command)
       _, sig = command.split(':')
       logger.debug("signal:#{sig}")
@@ -83,19 +142,73 @@ 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 = []
 
@@ -105,6 +218,9 @@ module MainLoop
             results << result
           end
         rescue Errno::ECHILD
+          # Процесс "съеден" другой системой (например, Process.wait вызван в on_term)
+          # или процесс уже завершился и pid больше не существует
+          # Добавляем [pid, nil] чтобы отметить его и продолжить обработку остальных
           results << [pid, nil]
         end
       end
@@ -122,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
-

data/lib/main_loop/process_handler.rb

@@ -1,10 +1,47 @@
 require 'main_loop/handler'
 
+# = MainLoop::ProcessHandler
+#
+# Управляет субпроцессами через Kernel.fork.
+#
+# == Жизненный цикл процесса
+#
+# 1. {#run} вызывает {#start_fork}
+# 2. {#start_fork} создает fork с обработкой ошибок
+# 3. process выполняется и завершается
+# 4. {#reap(status)} получает статус завершения
+# 5. {#handle_retry} решает, повторить или отправить term
+#
+# == Сигналы для процесса
+#
+# При {#term}:
+# - Если не терминация: Process.kill('TERM', pid) + вызовы @runnable.on_term / @on_term
+# - Если терминация: Process.kill('KILL', pid)
+#
+# == Пример использования
+#
+#   MainLoop::ProcessHandler.new dispatcher, 'worker', retry_count: 3, logger: logger do
+#     sleep 2
+#     exit! 0
+#   end
+#
+# == См. также
+# - {MainLoop::Handler} — базовый класс
+# - {MainLoop::ThreadHandler} — обработчики потоков
+
 module MainLoop
   class ProcessHandler < MainLoop::Handler
-
     attr_reader :pid
 
+    # == Инициализация
+    #
+    # @param dispatcher [Dispatcher] ссылка на диспетчер
+    # @param name [String] имя обработчика
+    # @param runnable [Object] объект с методами run и on_term (опционально)
+    # @param retry_count [Integer, :unlimited] количество повторов
+    # @param logger [Logger] логгер
+    # @option runnable [Object] nil
+    # @option retry_count [Integer, :unlimited] 0
     def initialize(dispatcher, name, runnable: nil, **kwargs, &block)
       super
       @handler_type = 'Process'
@@ -23,10 +60,16 @@ module MainLoop
       run
     end
 
+    # == Получить PID процесса
+    #
+    # @return [Integer|nil] PID процесса или nil если не создан
     def id
       @pid
     end
 
+    # == Обработка завершения процесса
+    #
+    # @param status [Process::Status|nil] статус завершения или nil если неизвестен
     def reap(status)
       if status
         logger.info "Process[#{name}] exited: Pid:#{@pid} Status: #{status.exitstatus.inspect} Termsig: #{status.termsig.inspect} Success: #{status.success?}"
@@ -43,10 +86,13 @@ module MainLoop
       handle_retry
     end
 
-    def term
+    # == Отправить сигнал терминации
+    #
+    # @param *_args (Unused)
+    def term(*_args)
       unless @pid
         @terminating_at ||= Time.now
-        logger.debug "Process[#{name}] alredy terminated. Skipped."
+        logger.debug "Process[#{name}] already terminated. Skipped."
         return
       end
 
@@ -65,9 +111,12 @@ module MainLoop
       end
     end
 
-    def kill
+    # == Принудительно завершить процесс
+    #
+    # @param *_args (Unused)
+    def kill(*_args)
       unless @pid
-        logger.debug "Process[#{name}] alredy Killed. Skipped."
+        logger.debug "Process[#{name}] already Killed. Skipped."
         return
       end
 
@@ -76,6 +125,9 @@ module MainLoop
       ::Process.kill('KILL', @pid) rescue nil
     end
 
+    # == Запустить процесс
+    #
+    # Вызывает {#start_fork} с блоком или runnable.
     def run
       return if terminating?
 
@@ -86,6 +138,12 @@ module MainLoop
       end
     end
 
+    # == Fork-блок (protected)
+    #
+    # Создает дочерний процесс и настраивает обработку ошибок.
+    #
+    # @yield выполнить блок кода в дочернем процессе
+    # @return [Integer] PID дочернего процесса
     protected
 
       def start_fork
@@ -98,7 +156,5 @@ module MainLoop
         @finished = false
         logger.info "Process[#{name}] created: Pid:#{@pid}"
       end
-
-
   end
 end