main_loop 0.1.4.364822 → 0.1.4.369901

data/lib/main_loop/thread_handler.rb

@@ -1,10 +1,49 @@
 require 'main_loop/handler'
 
+# = MainLoop::ThreadHandler
+#
+# Управляет потоками через Thread.new.
+#
+# == Особенности потоков
+#
+# - Потоки не имеют status завершения (как процессы)
+# - Если завершение graceful term, то @success отражает, завершился ли он после вызова on_term (true) или после нашего kill
+# - Внутри on_term поток может быть завершен так, как считает нужным разработчик метода, например
+#     @stopped = true
+#     @thread&.wakeup
+#     @thread&.kill unless @thread&.join(2)
+# - Если поток завершился сам, то смотрим на Thread.current[:exit_reason]
+# - Завершение потока публикуется в ensure блоке и обрабатывается в MainLoop#start_loop_forever
+#
+# == Сигналы для потока
+#
+# При {#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
 
+    # == Инициализация
+    #
+    # @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'
@@ -23,25 +62,35 @@ module MainLoop
       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}"
+      exit_reason = @thread[:exit_reason] if @thread
       @thread = nil
       @finished = true
 
       return if terminating?
-      @success = false
 
+      @success = (exit_reason == :normal)
       handle_retry
     end
 
-    def term
+    # == Терминация потока
+    #
+    # @param *_args (Unused)
+    def term(*_args)
       unless @thread
         @terminating_at ||= Time.now
-        logger.debug "Thread[#{name}] alredy terminated. Skipped."
+        logger.debug "Thread[#{name}] already terminated. Skipped."
         return
       end
 
@@ -59,9 +108,12 @@ module MainLoop
       end
     end
 
-    def kill
+    # == Принудительно завершить поток
+    #
+    # @param *_args (Unused)
+    def kill(*_args)
       unless @thread
-        logger.debug "Thread[#{name}] alredy Killed. Skipped."
+        logger.debug "Thread[#{name}] already Killed. Skipped."
         return
       end
 
@@ -70,6 +122,9 @@ module MainLoop
       @thread.kill rescue nil
     end
 
+    # == Запустить поток
+    #
+    # Вызывает {#start_thread} с блоком или runnable.
     def run
       return if terminating?
 
@@ -80,20 +135,27 @@ module MainLoop
       end
     end
 
+    # == Create-thread блок (protected)
+    #
+    # Создает новый поток и настраивает обработку ошибок и завершения.
+    #
+    # @yield выполнить блок кода в потоке
+    # @return [Thread] созданный поток
     protected
 
       def start_thread
         @thread = Thread.new do
           yield(self)
+          Thread.current[:exit_reason] = :normal
         rescue StandardError => e
+          Thread.current[:exit_reason] = :exception
           logger.error "Thread[#{name}] crashed: #{e.message}"
         ensure
+          Thread.current[:exit_reason] ||= :killed
           publish("reap:#{id}:exited")
         end
         @finished = false
         logger.info "Thread[#{name}] created: thread:#{@thread}"
       end
-
-
   end
 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.4.364822
+  version: 0.1.4.369901
 platform: ruby
 authors:
 - Samoilenko Yuri
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler