async-container 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2613c963c3efb08cf02c6a6299668b2b9ed83b583bbe84ebc973fa099b62e4a
-  data.tar.gz: 9cc9cd1ac55d85be9684e9a042be6ff3e93dd44e69c2ce212ec5f7441cbf7b1d
+  metadata.gz: 3b5ef8adc5ee828c6c044454180bf3a0de60eca666c4fa00a9c3f6b65c3ddff6
+  data.tar.gz: 778afef1c04f76a74dd03feecc0af119890875bb3dcfcfb4526556615ee789aa
 SHA512:
-  metadata.gz: ca31eb9ecbdd3c343ec77621778bcf7cfba210b5a1b7ba05a02d0e590f3574c8e0e25a4bcb85be5a6af05a601874084a2fab94dd2c422073c588816c899c7f46
-  data.tar.gz: 6ade195ca0f67619dbffee9b6f4dd6d567ccd05b2dd069075a10403c897806c1f33c3f44b06ef91a5ea5212b85c4cbf4c3a8f1ca4e02988a9559781c991e884f
+  metadata.gz: 0736e1e1e2cdbed60648aac53ecf2ab258436f08f44427cc1cbc516a24a584cc9cd82449129faaf6d71a1486a3a781240de2725f6fe57a0d369ec4b6e46df4c3
+  data.tar.gz: 330e8827656fdae8a1943768519a9642f8dccd598e7c036b7b22ecf0043757ddccbb2b5fd1592c26b6112ce43e4aa29541876fe494beca186cadde096e071381

data/lib/async/container/error.rb

@@ -21,6 +21,16 @@ module Async
 			end
 		end
 		
+		# Similar to {Terminate}, but represents `SIGKILL`.
+		class Kill < SignalException
+			SIGKILL = Signal.list["KILL"]
+			
+			# Create a new kill error.
+			def initialize
+				super(SIGKILL)
+			end
+		end
+		
 		# Similar to {Interrupt}, but represents `SIGHUP`.
 		class Restart < SignalException
 			SIGHUP = Signal.list["HUP"]

data/lib/async/container/forked.rb

@@ -231,20 +231,25 @@ module Async
 				# Wait for the child process to exit.
 				# @asynchronous This method may block.
 				#
+				# @parameter timeout [Numeric | Nil] Maximum time to wait before forceful termination.
 				# @returns [::Process::Status] The process exit status.
-				def wait
+				def wait(timeout = 0.1)
 					if @pid && @status.nil?
 						Console.debug(self, "Waiting for process to exit...", pid: @pid)
 						
 						_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
 						
-						while @status.nil?
-							sleep(0.1)
+						if @status.nil?
+							sleep(timeout) if timeout
 							
 							_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
 							
 							if @status.nil?
-								Console.warn(self) {"Process #{@pid} is blocking, has it exited?"}
+								Console.warn(self) {"Process #{@pid} is blocking, sending kill signal..."}
+								self.kill!
+								
+								# Wait for the process to exit:
+								_, @status = ::Process.wait2(@pid)
 							end
 						end
 					end

data/lib/async/container/group.rb

@@ -119,36 +119,78 @@ module Async
 				end
 			end
 			
-			# Stop all child processes using {#terminate}.
-			# @parameter timeout [Boolean | Numeric | Nil] If specified, invoke a graceful shutdown using {#interrupt} first.
-			def stop(timeout = 1)
-				Console.debug(self, "Stopping all processes...", timeout: timeout)
-				# Use a default timeout if not specified:
-				timeout = 1 if timeout == true
+			# Kill all running processes.
+			# This resumes the controlling fiber with an instance of {Kill}.
+			def kill
+				Console.info(self, "Sending kill to #{@running.size} running processes...")
+				@running.each_value do |fiber|
+					fiber.resume(Kill)
+				end
+			end
+			
+			private def wait_for_exit(clock, timeout)
+				while self.any?
+					duration = timeout - clock.total
+					
+					if duration >= 0
+						self.wait_for_children(duration)
+					else
+						self.wait_for_children(0)
+						break
+					end
+				end
+			end
+			
+			# Stop all child processes with a multi-phase shutdown sequence.
+			#
+			# A graceful shutdown performs the following sequence:
+			# 1. Send SIGINT and wait up to `interrupt_timeout` seconds
+			# 2. Send SIGTERM and wait up to `terminate_timeout` seconds  
+			# 3. Send SIGKILL and wait indefinitely for process cleanup
+			#
+			# If `graceful` is false, skips the SIGINT phase and goes directly to SIGTERM → SIGKILL.
+			#
+			# @parameter graceful [Boolean] Whether to send SIGINT first or skip directly to SIGTERM.
+			# @parameter interrupt_timeout [Numeric | Nil] Time to wait after SIGINT before escalating to SIGTERM.
+			# @parameter terminate_timeout [Numeric | Nil] Time to wait after SIGTERM before escalating to SIGKILL.
+			def stop(graceful = true, interrupt_timeout: 1, terminate_timeout: 1)
+				case graceful
+				when true
+					# Use defaults.
+				when false
+					interrupt_timeout = nil
+				when Numeric
+					interrupt_timeout = graceful
+					terminate_timeout = graceful
+				end
 				
-				if timeout
-					start_time = Async::Clock.now
+				Console.debug(self, "Stopping all processes...", interrupt_timeout: interrupt_timeout, terminate_timeout: terminate_timeout)
+				
+				# If a timeout is specified, interrupt the children first:
+				if interrupt_timeout
+					clock = Async::Clock.start
 					
+					# Interrupt the children:
 					self.interrupt
 					
-					while self.any?
-						duration = Async::Clock.now - start_time
-						remaining = timeout - duration
-						
-						if remaining >= 0
-							self.wait_for_children(duration)
-						else
-							self.wait_for_children(0)
-							break
-						end
-					end
+					# Wait for the children to exit:
+					self.wait_for_exit(clock, interrupt_timeout)
 				end
 				
-				# Terminate all children:
-				self.terminate if any?
+				if terminate_timeout
+					clock = Async::Clock.start
+					
+					# If the children are still running, terminate them:
+					self.terminate
+					
+					# Wait for the children to exit:
+					self.wait_for_exit(clock, terminate_timeout)
+				end
 				
-				# Wait for all children to exit:
-				self.wait
+				if any?
+					self.kill
+					self.wait
+				end
 			end
 			
 			# Wait for a message in the specified {Channel}.
@@ -165,6 +207,8 @@ module Async
 						channel.interrupt!
 					elsif result == Terminate
 						channel.terminate!
+					elsif result == Kill
+						channel.kill!
 					elsif result
 						yield result
 					elsif message = channel.receive
@@ -184,7 +228,7 @@ module Async
 				# This log is a big noisy and doesn't really provide a lot of useful information.
 				# Console.debug(self, "Waiting for children...", duration: duration, running: @running)
 				
-				if !@running.empty?
+				unless @running.empty?
 					# Maybe consider using a proper event loop here:
 					if ready = self.select(duration)
 						ready.each do |io|

data/lib/async/container/threaded.rb

@@ -216,10 +216,20 @@ module Async
 				end
 				
 				# Wait for the thread to exit and return he exit status.
+				# @asynchronous This method may block.
+				#
+				# @parameter timeout [Numeric | Nil] Maximum time to wait before forceful termination.
 				# @returns [Status]
-				def wait
+				def wait(timeout = 0.1)
 					if @waiter
-						@waiter.join
+						Console.debug(self, "Waiting for thread to exit...", timeout: timeout)
+						
+						unless @waiter.join(timeout)
+							Console.warn(self) {"Thread #{@thread} is blocking, sending kill signal..."}
+							self.kill!
+							@waiter.join
+						end
+						
 						@waiter = nil
 					end
 					

data/lib/async/container/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.25.0"
+		VERSION = "0.26.0"
 	end
 end

data/readme.md

@@ -26,6 +26,10 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
 Please see the [project releases](https://socketry.github.io/async-container/releases/index) for all releases.
 
+### v0.26.0
+
+  - [Production Reliability Improvements](https://socketry.github.io/async-container/releases/index#production-reliability-improvements)
+
 ### v0.25.0
 
   - Introduce `async:container:notify:log:ready?` task for detecting process readiness.

data/releases.md

@@ -1,5 +1,17 @@
 # Releases
 
+## v0.26.0
+
+### Production Reliability Improvements
+
+This release significantly improves container reliability by eliminating production hangs caused by unresponsive child processes.
+
+**SIGKILL Fallback Support**: Containers now automatically escalate to SIGKILL when child processes ignore SIGINT and SIGTERM signals. This prevents the critical production issue where containers would hang indefinitely waiting for uncooperative processes to exit.
+
+**Hang Prevention**: Individual child processes now have timeout-based hang prevention. If a process closes its notification pipe but doesn't actually exit, the container will detect this and escalate to SIGKILL after a reasonable timeout instead of hanging forever.
+
+**Improved Three-Phase Shutdown**: The `Group#stop()` method now uses a cleaner interrupt → terminate → kill escalation sequence with configurable timeouts for each phase, giving well-behaved processes multiple opportunities to shut down gracefully while ensuring unresponsive processes are eventually terminated.
+
 ## v0.25.0
 
   - Introduce `async:container:notify:log:ready?` task for detecting process readiness.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -105,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.
 test_files: []