main_loop 0.1.3.16874 → 0.1.4.367214

data/lib/main_loop/process_handler.rb

@@ -1,35 +1,95 @@
 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
 
-    def initialize(dispatcher, name, **kwargs, &block)
+    # == Инициализация
+    #
+    # @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'
       @pid = nil
       dispatcher.add_handler(self)
 
-      run(&block) if block_given?
+      if runnable
+        unless runnable.respond_to?(:run) && runnable.respond_to?(:on_term)
+          raise TypeError, "Runnable object must respond to :run and :on_term"
+        end
+      end
+
+      @runnable = runnable
+      @block = block
+
+      run
     end
 
+    # == Получить PID процесса
+    #
+    # @return [Integer|nil] PID процесса или nil если не создан
     def id
       @pid
     end
 
+    # == Обработка завершения процесса
+    #
+    # @param status [Process::Status|nil] статус завершения или nil если неизвестен
     def reap(status)
-      logger.info "Process[#{name}] exited: Pid:#{@pid} Status: #{status.exitstatus.inspect} Termsig: #{status.termsig.inspect} Success: #{status.success?}"
+      if status
+        logger.info "Process[#{name}] exited: Pid:#{@pid} Status: #{status.exitstatus.inspect} Termsig: #{status.termsig.inspect} Success: #{status.success?}"
+        @success = !!status.success?
+      else 
+        logger.info "Process[#{name}] exited: Pid:#{@pid} with unknown status"
+        @success = true # TODO или false?
+      end
       @pid = nil
       @finished = true
-      @success = !!status.success?
 
       return if terminating?
 
       handle_retry
     end
 
-    def term
+    # == Отправить сигнал терминации
+    #
+    # @param *_args (Unused)
+    def term(*_args)
       unless @pid
         @terminating_at ||= Time.now
         logger.debug "Process[#{name}] alredy terminated. Skipped."
@@ -43,12 +103,18 @@ module MainLoop
       else
         @terminating_at ||= Time.now
         logger.info "Process[#{name}] send terminate: Pid:#{@pid}"
+
+        @runnable&.on_term(@pid) rescue nil
         @on_term&.call(@pid) rescue nil
+
         ::Process.kill('TERM', @pid) rescue nil
       end
     end
 
-    def kill
+    # == Принудительно завершить процесс
+    #
+    # @param *_args (Unused)
+    def kill(*_args)
       unless @pid
         logger.debug "Process[#{name}] alredy Killed. Skipped."
         return
@@ -59,24 +125,36 @@ module MainLoop
       ::Process.kill('KILL', @pid) rescue nil
     end
 
-    def run(&block)
+    # == Запустить процесс
+    #
+    # Вызывает {#start_fork} с блоком или runnable.
+    def run
       return if terminating?
 
-      @block = block
-      start_fork(&@block)
+      if @runnable
+        start_fork { @runnable.run }
+      elsif @block
+        start_fork(&@block)
+      end
     end
 
+    # == Fork-блок (protected)
+    #
+    # Создает дочерний процесс и настраивает обработку ошибок.
+    #
+    # @yield执行 блок кода в дочернем процессе
+    # @return [Integer] PID дочернего процесса
     protected
 
       def start_fork
         @pid = Kernel.fork do
           yield
+        rescue StandardError => e
+          logger.error "Process[#{name}] crashed: #{e.message}"
+          exit!(1)
         end
         @finished = false
         logger.info "Process[#{name}] created: Pid:#{@pid}"
       end
-
-
   end
 end
-

data/lib/main_loop/thread_handler.rb

@@ -1,23 +1,72 @@
 require 'main_loop/handler'
 
+# = MainLoop::ThreadHandler
+#
+# Управляет потоками через Thread.new.
+#
+# == Особенности потоков
+#
+# - Потоки не имеют status завершения (как процессы)
+# - Поэтому @success = false для всех завершений (кроме graceful term)
+# - Завершение потока публикуется в ensure блоке
+#
+# == Сигналы для потока
+#
+# При {#term}:
+# - Если не терминация: вызовы @runnable.on_term / @on_term
+# - Если терминация: @thread.kill (FORCE)
+#
+# == Пример использования
+#
+#   MainLoop::ThreadHandler.new dispatcher, 'worker', retry_count: 0, logger: logger do |thread|
+#     loop do
+#       sleep 1
+#     end
+#   end
+#
+# == См. также
+# - {MainLoop::Handler} — базовый класс
+# - {MainLoop::ProcessHandler} — обработчики процессов
+
 module MainLoop
   class ThreadHandler < MainLoop::Handler
-
     attr_reader :thread
 
-    def initialize(dispatcher, name, **kwargs, &block)
+    # == Инициализация
+    #
+    # @param dispatcher [Dispatcher] ссылка на диспетчер
+    # @param name [String] имя обработчика
+    # @param runnable [Object] объект с методами run и on_term (опционально)
+    # @param retry_count [Integer, :unlimited] количество повторов
+    # @param logger [Logger] логгер
+    def initialize(dispatcher, name, runnable: nil, **kwargs, &block)
       super
       @handler_type = 'Thread'
       @thread = nil
       dispatcher.add_handler(self)
 
-      run(&block) if block_given?
+      if runnable
+        unless runnable.respond_to?(:run) && runnable.respond_to?(:on_term)
+          raise TypeError, "Runnable object must respond to :run and :on_term"
+        end
+      end
+
+      @runnable = runnable
+      @block = block
+
+      run
     end
 
+    # == Получить ID потока
+    #
+    # @return [String] object_id потока в виде строки
     def id
       @thread&.object_id.to_s
     end
 
+    # == Обработка завершения потока
+    #
+    # @param status [String] статус завершения (описание)
     def reap(status)
       logger.info "Thread[#{name}] exited: thread:#{@thread} Status:#{status}"
       @thread = nil
@@ -29,7 +78,10 @@ module MainLoop
       handle_retry
     end
 
-    def term
+    # == Терминация потока
+    #
+    # @param *_args (Unused)
+    def term(*_args)
       unless @thread
         @terminating_at ||= Time.now
         logger.debug "Thread[#{name}] alredy terminated. Skipped."
@@ -44,11 +96,16 @@ module MainLoop
         @terminating_at ||= Time.now
         @success = true
         logger.info "Thread[#{name}] send terminate: thread:#{@thread}"
+
+        @runnable&.on_term(@thread) rescue nil
         @on_term&.call(@thread) rescue nil
       end
     end
 
-    def kill
+    # == Принудительно завершить поток
+    #
+    # @param *_args (Unused)
+    def kill(*_args)
       unless @thread
         logger.debug "Thread[#{name}] alredy Killed. Skipped."
         return
@@ -59,26 +116,37 @@ module MainLoop
       @thread.kill rescue nil
     end
 
-    def run(&block)
+    # == Запустить поток
+    #
+    # Вызывает {#start_thread} с блоком или runnable.
+    def run
       return if terminating?
 
-      @block = block
-      start_thread(&@block)
+      if @runnable
+        start_thread { @runnable.run(self) }
+      elsif @block
+        start_thread(&@block)
+      end
     end
 
+    # == Create-thread блок (protected)
+    #
+    # Создает новый поток и настраивает обработку ошибок и завершения.
+    #
+    # @yield执行 блок кода в потоке
+    # @return [Thread] созданный поток
     protected
 
       def start_thread
         @thread = Thread.new do
           yield(self)
+        rescue StandardError => e
+          logger.error "Thread[#{name}] crashed: #{e.message}"
         ensure
           publish("reap:#{id}:exited")
         end
         @finished = false
         logger.info "Thread[#{name}] created: thread:#{@thread}"
-      end
-
-
+    end
   end
 end
-

data/lib/main_loop/version.rb

@@ -1,6 +1,6 @@
 module MainLoop
 
-  VERSION = '0.1.3'.freeze
+  VERSION = '0.1.4'.freeze
 
 end
 

data/lib/main_loop.rb

@@ -1,10 +1,50 @@
+# YARD-документация для main_loop
+# Основной модуль библиотеки для управления субпроцессами и потоками
+
 require 'main_loop/bus'
 require 'main_loop/loop'
 require 'main_loop/dispatcher'
 require 'main_loop/process_handler'
 require 'main_loop/thread_handler'
 
-
+# = MainLoop
+#
+# Главный модуль библиотеки для управления субпроцессами и потоками.
+#
+# Основные компоненты:
+# - {MainLoop::Bus} — канал обмена событиями между компонентами
+# - {MainLoop::Dispatcher} — координация обработчиков и управление жизненным циклом
+# - {MainLoop::Loop} — главный цикл обработки событий и сигналов
+# - {MainLoop::Handler} — абстрактный базовый класс для обработчиков
+# - {MainLoop::ProcessHandler} — управление субпроцессами
+# - {MainLoop::ThreadHandler} — управление потоками
+#
+# == Пример использования
+#
+#   require 'main_loop'
+#   require 'logger'
+#
+#   logger = Logger.new(STDOUT)
+#   logger.level = Logger::DEBUG
+#
+#   bus = MainLoop::Bus.new
+#   dispatcher = MainLoop::Dispatcher.new(bus, timeout: 10, logger: logger)
+#   mainloop = MainLoop::Loop.new(bus, dispatcher, logger: logger)
+#
+#   MainLoop::ProcessHandler.new dispatcher, 'worker', retry_count: 3, logger: logger do
+#     sleep 2
+#     exit! 0
+#   end
+#
+#   mainloop.run
+#
+# == См. также
+# - {MainLoop::Bus}
+# - {MainLoop::Dispatcher}
+# - {MainLoop::Loop}
+# - {MainLoop::Handler}
+# - {MainLoop::ProcessHandler}
+# - {MainLoop::ThreadHandler}
 
 module MainLoop
 
@@ -13,4 +53,3 @@ module MainLoop
   end
 
 end
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: main_loop
 version: !ruby/object:Gem::Version
-  version: 0.1.3.16874
+  version: 0.1.4.367214
 platform: ruby
 authors:
 - Samoilenko Yuri
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2019-09-30 00:00:00.000000000 Z
+date: 2026-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,6 +72,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubycritic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +114,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: timeouter
   requirement: !ruby/object:Gem::Requirement
@@ -135,7 +163,7 @@ homepage: https://github.com/RnD-Soft/main_loop
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -150,8 +178,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.2.33
+signing_key:
 specification_version: 4
 summary: Main Loop implementation to control subprocesses and threads
 test_files: []