async-container 0.19.0 → 0.20.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2edeb6fa679f328736bb4a65c3b342b4aea94f2fc79557d4fc6e9e84bee77a2e
-  data.tar.gz: 5c1c52a4f90c8710efebb411d97e5a8342ea99d1bbe09082deed562b8acdce99
+  metadata.gz: 2435dd48259ab4b6bbad01780c21dc91bdf2946485f1dd682c8388b9ee68410d
+  data.tar.gz: c8e3564e5c889f469658eb044444bc6884575090ed38e73f07bcffdfe893f823
 SHA512:
-  metadata.gz: ee365ff16248e3064b136cdfeddec8e0f01ef77decbd514b94fc4a3bce1a38c2c51ffa5ba1e071b2fcd6bad6b7c4d4e322f26e8e5a530e4f45a68266d67429da
-  data.tar.gz: 171a93c5855cad3a112622232bbc7e93b880d4c77223cb8a17c7772a0687a0be40af3143a0ecad2b14a9e9aa656010cdf47eb42f80e14b08148cd02f4a4eaa6c
+  metadata.gz: fa56a0207d1bab96685c25ca8f3617a5e5aefeb673998d836780baf75e1ff9ee9618ac4e506f893de206f425277a7abb0dc12f748850d59e037f5f155763b9d9
+  data.tar.gz: 1198eaa52f0ea7dfe3b411c1e6cf6866f720f9aa4b5b1913fee2fbb535144115b4e2e3e21e313fa01faa64e724e7e786e32732c0889d2c8601c8ccce72dfe967

data/lib/async/container/forked.rb

@@ -116,6 +116,24 @@ module Async
 					self.close_write
 				end
 				
+				# Convert the child process to a hash, suitable for serialization.
+				#
+				# @returns [Hash] The request as a hash.
+				def as_json(...)
+					{
+						name: @name,
+						pid: @pid,
+						status: @status&.to_i,
+					}
+				end
+				
+				# Convert the request to JSON.
+				#
+				# @returns [String] The request as JSON.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
 				# Set the name of the process.
 				# Invokes {::Process.setproctitle} if invoked in the child process.
 				def name= value

data/lib/async/container/generic.rb

@@ -4,6 +4,7 @@
 # Copyright, 2019-2024, by Samuel Williams.
 
 require "etc"
+require "async/clock"
 
 require_relative "group"
 require_relative "keyed"
@@ -38,7 +39,7 @@ module Async
 			UNNAMED = "Unnamed"
 			
 			def initialize(**options)
-				@group = Group.new
+				@group = Group.new(**options)
 				@running = true
 				
 				@state = {}
@@ -47,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.
@@ -141,7 +144,8 @@ module Async
 			# @parameter name [String] The name of the child instance.
 			# @parameter restart [Boolean] Whether to restart the child instance if it fails.
 			# @parameter key [Symbol] A key used for reloading child instances.
-			def spawn(name: nil, restart: false, key: nil, &block)
+			# @parameter health_check_timeout [Numeric | Nil] The maximum time a child instance can run without updating its state, before it is terminated as unhealthy.
+			def spawn(name: nil, restart: false, key: nil, health_check_timeout: nil, &block)
 				name ||= UNNAMED
 				
 				if mark?(key)
@@ -157,9 +161,24 @@ module Async
 						
 						state = insert(key, child)
 						
+						# If a health check is specified, we will monitor the child process and terminate it if it does not update its state within the specified time.
+						if health_check_timeout
+							age_clock = state[:age] = Clock.start
+						end
+						
 						begin
 							status = @group.wait_for(child) do |message|
-								state.update(message)
+								case message
+								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!
+									end
+								else
+									state.update(message)
+									age_clock&.reset!
+								end
 							end
 						ensure
 							delete(key, child)

data/lib/async/container/group.rb

@@ -13,7 +13,12 @@ module Async
 		# Manages a group of running processes.
 		class Group
 			# Initialize an empty group.
-			def initialize
+			#
+			# @parameter health_check_interval [Numeric | Nil] The (biggest) interval at which health checks are performed.
+			def initialize(health_check_interval: 1.0)
+				@health_check_interval = health_check_interval
+				
+				# The running fibers, indexed by IO:
 				@running = {}
 				
 				# This queue allows us to wait for processes to complete, without spawning new processes as a result.
@@ -57,8 +62,36 @@ module Async
 			def wait
 				self.resume
 				
-				while self.running?
-					self.wait_for_children
+				with_health_checks do |duration|
+					self.wait_for_children(duration)
+				end
+			end
+			
+			private def with_health_checks
+				if @health_check_interval
+					health_check_clock = Clock.start
+					
+					while self.running?
+						duration = [@health_check_interval - health_check_clock.total, 0].max
+						
+						yield duration
+						
+						if health_check_clock.total > @health_check_interval
+							self.health_check!
+							health_check_clock.reset!
+						end
+					end
+				else
+					while self.running?
+						yield nil
+					end
+				end
+			end
+			
+			# Perform a health check on all running processes.
+			def health_check!
+				@running.each_value do |fiber|
+					fiber.resume(:health_check!)
 				end
 			end
 			
@@ -119,15 +152,19 @@ module Async
 				@running[io] = Fiber.current
 				
 				while @running.key?(io)
+					# Wait for some event on the channel:
 					result = Fiber.yield
 					
 					if result == Interrupt
 						channel.interrupt!
 					elsif result == Terminate
 						channel.terminate!
+					elsif result
+						yield result
 					elsif message = channel.receive
 						yield message
 					else
+						# Wait for the channel to exit:
 						return channel.wait
 					end
 				end

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

@@ -90,7 +90,10 @@ module Async
 				def self.fork(**options)
 					self.new(**options) do |thread|
 						::Thread.new do
-							yield Instance.for(thread)
+							# This could be a configuration option (see forked implementation too):
+							::Thread.handle_interrupt(SignalException => :immediate) do
+								yield Instance.for(thread)
+							end
 						end
 					end
 				end
@@ -122,6 +125,23 @@ module Async
 					end
 				end
 				
+				# Convert the child process to a hash, suitable for serialization.
+				#
+				# @returns [Hash] The request as a hash.
+				def as_json(...)
+					{
+						name: @thread.name,
+						status: @status&.as_json,
+					}
+				end
+				
+				# Convert the request to JSON.
+				#
+				# @returns [String] The request as JSON.
+				def to_json(...)
+					as_json.to_json(...)
+				end
+				
 				# Set the name of the thread.
 				# @parameter value [String] The name to set.
 				def name= value
@@ -188,6 +208,14 @@ module Async
 						@error.nil?
 					end
 					
+					def as_json(...)
+						if @error
+							@error.inspect
+						else
+							true
+						end
+					end
+					
 					# A human readable representation of the status.
 					def to_s
 						"\#<#{self.class} #{success? ? "success" : "failure"}>"

data/lib/async/container/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Container
-		VERSION = "0.19.0"
+		VERSION = "0.20.1"
 	end
 end

data/readme.md

@@ -14,7 +14,24 @@ 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.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,47 @@
 # Releases
 
-## Unreleased
+## 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.19.0
+  version: 0.20.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-04 00:00:00.000000000 Z
+date: 2025-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -48,14 +48,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.10'
+        version: '2.22'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.10'
+        version: '2.22'
 executables: []
 extensions: []
 extra_rdoc_files: []