async-container 0.24.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8b5dae742b5445c83c515d4745a49df725f9eea920e43340913b19239af8aa6
-  data.tar.gz: b4153930bb6ee37055e5675c921193ec27221c754ced2250975a2ba13fb0fda8
+  metadata.gz: 3b5ef8adc5ee828c6c044454180bf3a0de60eca666c4fa00a9c3f6b65c3ddff6
+  data.tar.gz: 778afef1c04f76a74dd03feecc0af119890875bb3dcfcfb4526556615ee789aa
 SHA512:
-  metadata.gz: 76a94fbd31a24ac6b6dccd52cde65bee5da8ec4e7fedb87493ffa4b67f64de387d88ddf7bff2edcec4e2075d928d52ed0273ffd6315cde69f8350d3e902a7db8
-  data.tar.gz: 424b331952bc76e338c21288fc710575bd651061ebcc8c5522b0c3aa4f3f4603726afdf75febba5e4ca6242d182d07603bed81043af14814ef7b397659ca3961
+  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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 require_relative "error"
 
@@ -189,6 +189,7 @@ module Async
 					"\#<#{self.class} name=#{@name.inspect} status=#{@status.inspect} pid=#{@pid.inspect}>"
 				end
 				
+				# @returns [String] A string representation of the process.
 				alias to_s inspect
 				
 				# Invoke {#terminate!} and then {#wait} for the child process to exit.
@@ -230,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/generic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "etc"
 require "async/clock"

data/lib/async/container/group.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
 require "fiber"
 require "async/clock"
@@ -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/hybrid.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2022, by Anton Sozontov.
 
 require_relative "forked"

data/lib/async/container/keyed.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module Container

data/lib/async/container/notify/client.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 module Async
 	module Container

data/lib/async/container/notify/log.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2025, by Samuel Williams.
 
 require_relative "client"
 require "socket"
@@ -14,9 +14,16 @@ module Async
 				# The name of the environment variable which contains the path to the notification socket.
 				NOTIFY_LOG = "NOTIFY_LOG"
 				
+				# @returns [String] The path to the notification log file.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
+				def self.path(environment = ENV)
+					environment[NOTIFY_LOG]
+				end
+				
 				# Open a notification client attached to the current {NOTIFY_LOG} if possible.
+				# @parameter environment [Hash] The environment variables, defaults to `ENV`.
 				def self.open!(environment = ENV)
-					if path = environment.delete(NOTIFY_LOG)
+					if path = self.path(environment)
 						self.new(path)
 					end
 				end

data/lib/async/container/notify/pipe.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Juan Antonio Martín Lucas.
 
 require_relative "client"
@@ -42,18 +42,18 @@ module Async
 					if notify_pipe = options.delete(:notify_pipe)
 						options[notify_pipe] = @io
 						environment[NOTIFY_PIPE] = notify_pipe.to_s
-					
+						
 					# Use stdout if it's not redirected:
 					# This can cause issues if the user expects stdout to be connected to a terminal.
 					# elsif !options.key?(:out)
 					# 	options[:out] = @io
 					# 	environment[NOTIFY_PIPE] = "1"
-					
+						
 					# Use fileno 3 if it's available:
 					elsif !options.key?(3)
 						options[3] = @io
 						environment[NOTIFY_PIPE] = "3"
-					
+						
 					# Otherwise, give up!
 					else
 						raise ArgumentError, "Please specify valid file descriptor for notify_pipe!"

data/lib/async/container/notify/server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 # Copyright, 2020, by Olle Jonsson.
 
 require "tmpdir"

data/lib/async/container/notify/socket.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "client"
 require "socket"

data/lib/async/container/notify.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "notify/pipe"
 require_relative "notify/socket"

data/lib/async/container/statistics.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 require "async/reactor"
 

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

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 module Async
 	module Container
-		VERSION = "0.24.0"
+		VERSION = "0.26.0"
 	end
 end

data/lib/async/container.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
 require_relative "container/controller"
 

data/readme.md

@@ -18,10 +18,26 @@ Please see the [project documentation](https://socketry.github.io/async-containe
 
   - [Getting Started](https://socketry.github.io/async-container/guides/getting-started/index) - This guide explains how to use `async-container` to build basic scalable systems.
 
+  - [Systemd Integration](https://socketry.github.io/async-container/guides/systemd-integration/index) - This guide explains how to use `async-container` with systemd to manage your application as a service.
+
+  - [Kubernetes Integration](https://socketry.github.io/async-container/guides/kubernetes-integration/index) - This guide explains how to use `async-container` with Kubernetes to manage your application as a containerized service.
+
 ## Releases
 
 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.
+
+### v0.24.0
+
+  - Add support for health check failure metrics.
+
 ### v0.23.0
 
   - [Add support for `NOTIFY_LOG` for Kubernetes readiness probes.](https://socketry.github.io/async-container/releases/index#add-support-for-notify_log-for-kubernetes-readiness-probes.)

data/releases.md

@@ -1,5 +1,25 @@
 # 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.
+
+## v0.24.0
+
+  - Add support for health check failure metrics.
+
 ## v0.23.0
 
 ### Add support for `NOTIFY_LOG` for Kubernetes readiness probes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-03-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -98,14 +98,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.
 test_files: []