patient_http 1.6.1 → 1.7.0

data/lib/patient_http/completion_executor.rb

@@ -10,13 +10,13 @@ module PatientHttp
   #
   # @api private
   class CompletionExecutor
-    # Initialize the executor and start its worker threads.
+    # Creates the executor and starts its worker threads.
     #
-    # @param threads [Integer] number of worker threads
-    # @param logger [Logger, nil] logger for unexpected job errors
-    # @param thread_name_prefix [String] prefix for worker thread names
-    # @param on_finished [#call, nil] invoked after each job completes, outside
-    #   any executor lock, so the owner can re-check idle conditions
+    # @param threads [Integer] Number of worker threads.
+    # @param logger [Logger, nil] Logger for unexpected job errors.
+    # @param thread_name_prefix [String] Prefix for worker thread names.
+    # @param on_finished [#call, nil] Invoked after each job completes, outside
+    #   any executor lock, so the owner can re-check idle conditions.
     def initialize(threads:, logger: nil, thread_name_prefix: "patient-http-completion", on_finished: nil)
       @queue = Thread::Queue.new
       @logger = logger
@@ -34,10 +34,10 @@ module PatientHttp
       end
     end
 
-    # Enqueue a job for execution.
+    # Enqueues a job for execution.
     #
-    # @param job [#call] the job to run
-    # @raise [ClosedQueueError] if the executor has been shut down
+    # @param job [#call] The job to run.
+    # @raise [ClosedQueueError] If the executor has been shut down.
     # @return [void]
     def enqueue(job)
       @mutex.synchronize { @outstanding += 1 }
@@ -50,30 +50,30 @@ module PatientHttp
       nil
     end
 
-    # Check whether the executor has no queued or running jobs.
+    # Returns whether the executor has no queued or running jobs.
     #
     # @return [Boolean]
     def idle?
       @mutex.synchronize { @outstanding == 0 }
     end
 
-    # Check whether the given thread is one of this executor's workers.
+    # Returns whether the given thread is one of this executor's workers.
     #
-    # @param thread [Thread] the thread to check
+    # @param thread [Thread] The thread to check.
     # @return [Boolean]
     def worker_thread?(thread = Thread.current)
       @threads.include?(thread)
     end
 
-    # Shut down the executor: close the queue so workers drain remaining jobs
-    # and exit, then join them within the timeout. Workers still alive after
-    # the deadline are killed; their tasks remain durably tracked and are
-    # recovered by the owner's re-enqueue logic.
+    # Shuts down the executor. The queue is closed, so the workers run the
+    # remaining jobs and exit. The executor waits for the workers until the
+    # timeout, and then kills the workers that are still alive. Their tasks
+    # stay tracked, and the owner re-enqueues them.
     #
-    # Safe to call more than once and from a worker thread itself (the
-    # current thread is never joined or killed).
+    # You can call this method more than once, and from a worker thread. The
+    # current thread is never joined or killed.
     #
-    # @param timeout [Numeric] seconds to wait for workers to drain
+    # @param timeout [Numeric] Seconds to wait for workers to drain.
     # @return [void]
     def shutdown(timeout: 5)
       @queue.close
@@ -96,7 +96,7 @@ module PatientHttp
 
     private
 
-    # Drop jobs left in the closed queue by workers that were killed at the
+    # Drops jobs left in the closed queue by workers that were killed at the
     # shutdown deadline. Those jobs can never run, so they must stop counting
     # against the outstanding total or the executor would never report itself
     # idle again.