async-container 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a95321eeaead4fafe8c8db6bfa186d13559c8b39185c566db474ff2111e3add8
-  data.tar.gz: 873a71e53157cf3f5c94908daff4848f88b0bb06c35e10fd89c569fe6a646386
+  metadata.gz: 6dd27e02912c5f1258419c9821da1bd97d58f4fd68b4a58512b3ebd5291c5b6b
+  data.tar.gz: 36fc9d2d0ce94a0e2591beac3384d2fba288094a93c1ada7a9000841c1e78a59
 SHA512:
-  metadata.gz: e974514dc85a284427791fffa2299c1541f4330b60f4d1470a64c9d2591d9c9c5a59250d9560e4b61ca43024869681f5f2cdc89ab086b178a391105318691b9d
-  data.tar.gz: 712370e1ea844ede123bb6215422c393109e50133db7991242b748f013e75904494af9300fdcbcd5de490c65c473fb195eac46eabbb5d5f34e1a774235cf5e8e
+  metadata.gz: 162f3604bbaa973b486fc271ccf61106008a5d2259f114134535188349267ee3dfb81cbe857ce7edc49dd2037b5d1f5581dd531955ddbfba264a113638e300cd
+  data.tar.gz: b1ba5f8e3b96976a97b6f81e20a62efbcbde89e4e2f0be43c754954a44924e2553c447cf275121ce74894d0044e7677a144c7f43df5f77d7a55b263f6442eb96

data/lib/async/container/forked.rb

@@ -180,6 +180,13 @@ module Async
 					end
 				end
 				
+				# Send `SIGKILL` to the child process.
+				def kill!
+					unless @status
+						::Process.kill(:KILL, @pid)
+					end
+				end
+				
 				# Send `SIGHUP` to the child process.
 				def restart!
 					unless @status

data/lib/async/container/generic.rb

@@ -39,7 +39,7 @@ module Async
 			UNNAMED = "Unnamed"
 			
 			def initialize(**options)
-				@group = Group.new
+				@group = Group.new(**options)
 				@running = true
 				
 				@state = {}
@@ -48,8 +48,10 @@ module Async
 				@keyed = {}
 			end
 			
+			# @attribute [Group] The group of running children instances.
 			attr :group
 			
+			# @attribute [Hash(Child, Hash)] The state of each child instance.
 			attr :state
 			
 			# A human readable representation of the container.
@@ -170,8 +172,8 @@ module Async
 								when :health_check!
 									if health_check_timeout&.<(age_clock.total)
 										Console.warn(self, "Child failed health check!", child: child, age: age_clock.total, health_check_timeout: health_check_timeout)
-										# If the child has failed the health check, we assume the worst and terminate it (SIGTERM).
-										child.terminate!
+										# If the child has failed the health check, we assume the worst and kill it immediately:
+										child.kill!
 									end
 								else
 									state.update(message)

data/lib/async/container/hybrid.rb

@@ -15,7 +15,8 @@ module Async
 			# @parameter count [Integer] The number of instances to start.
 			# @parameter forks [Integer] The number of processes to fork.
 			# @parameter threads [Integer] the number of threads to start.
-			def run(count: nil, forks: nil, threads: nil, **options, &block)
+			# @parameter health_check_timeout [Numeric] The timeout for health checks, in seconds. Passed into the child {Threaded} containers.
+			def run(count: nil, forks: nil, threads: nil, health_check_timeout: nil, **options, &block)
 				processor_count = Container.processor_count
 				count ||= processor_count ** 2
 				forks ||= [processor_count, count].min
@@ -25,7 +26,7 @@ module Async
 					self.spawn(**options) do |instance|
 						container = Threaded.new
 						
-						container.run(count: threads, **options, &block)
+						container.run(count: threads, health_check_timeout: health_check_timeout, **options, &block)
 						
 						container.wait_until_ready
 						instance.ready!
@@ -34,6 +35,7 @@ module Async
 					rescue Async::Container::Terminate
 						# Stop it immediately:
 						container.stop(false)
+						raise
 					ensure
 						# Stop it gracefully (also code path for Interrupt):
 						container.stop

data/lib/async/container/threaded.rb

@@ -11,6 +11,9 @@ module Async
 	module Container
 		# A multi-thread container which uses {Thread.fork}.
 		class Threaded < Generic
+			class Kill < Exception
+			end
+			
 			# Indicates that this is not a multi-process container.
 			def self.multiprocess?
 				false
@@ -178,6 +181,14 @@ module Async
 					@thread.raise(Terminate)
 				end
 				
+				# Invoke {Thread#kill} on the child thread.
+				def kill!
+					# Killing a thread does not raise an exception in the thread, so we need to handle the status here:
+					@status = Status.new(:killed)
+					
+					@thread.kill
+				end
+				
 				# Raise {Restart} in the child thread.
 				def restart!
 					@thread.raise(Restart)
@@ -230,7 +241,7 @@ module Async
 						Console.error(self) {error}
 					end
 					
-					@status = Status.new(error)
+					@status ||= Status.new(error)
 					self.close_write
 				end
 			end

data/lib/async/container/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.20.0"
+		VERSION = "0.21.0"
 	end
 end

data/readme.md

@@ -14,7 +14,28 @@ Provides containers which implement parallelism for clients and servers.
 
 ## Usage
 
-Please see the [project documentation](https://socketry.github.io/async-container/).
+Please see the [project documentation](https://socketry.github.io/async-container/) for more details.
+
+  - [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.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-container/releases/index) for all releases.
+
+### v0.21.0
+
+  - Use `SIGKILL`/`Thread#kill` when the health check fails. In some cases, `SIGTERM` may not be sufficient to terminate a process because the signal can be ignored or the process may be in an uninterruptible state.
+
+### v0.20.1
+
+  - Fix compatibility between <code class="language-ruby">Async::Container::Hybrid</code> and the health check.
+  - <code class="language-ruby">Async::Container::Generic\#initialize</code> passes unused arguments through to <code class="language-ruby">Async::Container::Group</code>.
+
+### v0.20.0
+
+  - Improve container signal handling reliability by using `Thread.handle_interrupt` except at known safe points.
+  - Improved logging when child process fails and container startup.
+  - [Add `health_check_timeout` for detecting hung processes.](https://socketry.github.io/async-container/releases/index#add-health_check_timeout-for-detecting-hung-processes.)
 
 ## Contributing
 

data/releases.md

@@ -1,6 +1,51 @@
 # Releases
 
-## Unreleased
+## v0.21.0
+
+  - Use `SIGKILL`/`Thread#kill` when the health check fails. In some cases, `SIGTERM` may not be sufficient to terminate a process because the signal can be ignored or the process may be in an uninterruptible state.
+
+## v0.20.1
+
+  - Fix compatibility between {ruby Async::Container::Hybrid} and the health check.
+  - {ruby Async::Container::Generic\#initialize} passes unused arguments through to {ruby Async::Container::Group}.
+
+## v0.20.0
 
   - Improve container signal handling reliability by using `Thread.handle_interrupt` except at known safe points.
   - Improved logging when child process fails and container startup.
+
+### Add `health_check_timeout` for detecting hung processes.
+
+In order to detect hung processes, a `health_check_timeout` can be specified when spawning children workers. If the health check does not complete within the specified timeout, the child process is killed.
+
+``` ruby
+require "async/container"
+
+container = Async::Container.new
+
+container.run(count: 1, restart: true, health_check_timeout: 1) do |instance|
+	while true
+		# This example will fail sometimes:
+		sleep(0.5 + rand)
+		instance.ready!
+	end
+end
+
+container.wait
+```
+
+If the health check does not complete within the specified timeout, the child process is killed:
+
+``` 
+ 3.01s     warn: Async::Container::Forked [oid=0x1340] [ec=0x1348] [pid=27100] [2025-02-20 13:24:55 +1300]
+               | Child failed health check!
+               | {
+               |   "child": {
+               |     "name": "Unnamed",
+               |     "pid": 27101,
+               |     "status": null
+               |   },
+               |   "age": 1.0612829999881797,
+               |   "health_check_timeout": 1
+               | }
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-07 00:00:00.000000000 Z
+date: 2025-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async