async-container 0.18.3 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d061fd5261bb0fabc616df89690cddd1c7545d5fc41799bc107050da08bf7635
-  data.tar.gz: 13a9e58f76b560a9f5602da7977739c936aa71732338f802a97d9fc9a6224480
+  metadata.gz: a95321eeaead4fafe8c8db6bfa186d13559c8b39185c566db474ff2111e3add8
+  data.tar.gz: 873a71e53157cf3f5c94908daff4848f88b0bb06c35e10fd89c569fe6a646386
 SHA512:
-  metadata.gz: 1f162eadf2c624ebe86fe174578096ccb473e5f9f031f75d8135ed77cf9911f006e4b3a9957b8402829a67fa480d80c7fdf3a3abdbb02e959ae1c135e99c3c92
-  data.tar.gz: 8201e656ac4f8182380bb08af4290c51bddc62d97214fd39bf0e7761f48f339a859f809dd12539c2a53a85219e4b4b6a68bcb9a81c7ef7c9dd4bab3da563d053
+  metadata.gz: e974514dc85a284427791fffa2299c1541f4330b60f4d1470a64c9d2591d9c9c5a59250d9560e4b61ca43024869681f5f2cdc89ab086b178a391105318691b9d
+  data.tar.gz: 712370e1ea844ede123bb6215422c393109e50133db7991242b748f013e75904494af9300fdcbcd5de490c65c473fb195eac46eabbb5d5f34e1a774235cf5e8e

data/lib/async/container/best.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
-require_relative 'forked'
-require_relative 'threaded'
-require_relative 'hybrid'
+require_relative "forked"
+require_relative "threaded"
+require_relative "hybrid"
 
 module Async
 	module Container

data/lib/async/container/channel.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
-require 'json'
+require "json"
 
 module Async
 	module Container

data/lib/async/container/controller.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 
-require_relative 'error'
-require_relative 'best'
+require_relative "error"
+require_relative "best"
 
-require_relative 'statistics'
-require_relative 'notify'
+require_relative "statistics"
+require_relative "notify"
 
 module Async
 	module Container
@@ -26,13 +26,10 @@ module Async
 				@container = nil
 				@container_class = container_class
 				
-				if @notify = notify
-					@notify.status!("Initializing...")
-				end
-				
+				@notify = notify
 				@signals = {}
 				
-				trap(SIGHUP) do
+				self.trap(SIGHUP) do
 					self.restart
 				end
 				
@@ -93,7 +90,12 @@ module Async
 			
 			# Start the container unless it's already running.
 			def start
-				self.restart unless @container
+				unless @container
+					Console.info(self) {"Controller starting..."}
+					self.restart
+				end
+				
+				Console.info(self) {"Controller started..."}
 			end
 			
 			# Stop the container if it's running.
@@ -109,9 +111,9 @@ module Async
 				if @container
 					@notify&.restarting!
 					
-					Console.logger.debug(self) {"Restarting container..."}
+					Console.debug(self) {"Restarting container..."}
 				else
-					Console.logger.debug(self) {"Starting container..."}
+					Console.debug(self) {"Starting container..."}
 				end
 				
 				container = self.create_container
@@ -125,9 +127,9 @@ module Async
 				end
 				
 				# Wait for all child processes to enter the ready state.
-				Console.logger.debug(self, "Waiting for startup...")
+				Console.debug(self, "Waiting for startup...")
 				container.wait_until_ready
-				Console.logger.debug(self, "Finished startup.")
+				Console.debug(self, "Finished startup.")
 				
 				if container.failed?
 					@notify&.error!("Container failed to start!")
@@ -143,7 +145,7 @@ module Async
 				container = nil
 				
 				if old_container
-					Console.logger.debug(self, "Stopping old container...")
+					Console.debug(self, "Stopping old container...")
 					old_container&.stop(@graceful_stop)
 				end
 				
@@ -157,7 +159,7 @@ module Async
 			def reload
 				@notify&.reloading!
 				
-				Console.logger.info(self) {"Reloading container: #{@container}..."}
+				Console.info(self) {"Reloading container: #{@container}..."}
 				
 				begin
 					self.setup(@container)
@@ -166,11 +168,11 @@ module Async
 				end
 				
 				# Wait for all child processes to enter the ready state.
-				Console.logger.debug(self, "Waiting for startup...")
+				Console.debug(self, "Waiting for startup...")
 				
 				@container.wait_until_ready
 				
-				Console.logger.debug(self, "Finished startup.")
+				Console.debug(self, "Finished startup.")
 				
 				if @container.failed?
 					@notify.error!("Container failed to reload!")
@@ -183,10 +185,41 @@ module Async
 			
 			# Enter the controller run loop, trapping `SIGINT` and `SIGTERM`.
 			def run
+				@notify&.status!("Initializing...")
+				
+				with_signal_handlers do
+					self.start
+					
+					while @container&.running?
+						begin
+							@container.wait
+						rescue SignalException => exception
+							if handler = @signals[exception.signo]
+								begin
+									handler.call
+								rescue SetupError => error
+									Console.error(self, error)
+								end
+							else
+								raise
+							end
+						end
+					end
+				end
+			rescue Interrupt
+				self.stop
+			rescue Terminate
+				self.stop(false)
+			ensure
+				self.stop(false)
+			end
+			
+			private def with_signal_handlers
 				# I thought this was the default... but it doesn't always raise an exception unless you do this explicitly.
-				# We use `Thread.current.raise(...)` so that exceptions are filtered through `Thread.handle_interrupt` correctly.
+				
 				interrupt_action = Signal.trap(:INT) do
-					# $stderr.puts "Received INT signal, terminating...", caller
+					# We use `Thread.current.raise(...)` so that exceptions are filtered through `Thread.handle_interrupt` correctly.
+					# $stderr.puts "Received INT signal, interrupting...", caller
 					::Thread.current.raise(Interrupt)
 				end
 				
@@ -197,33 +230,13 @@ module Async
 				
 				hangup_action = Signal.trap(:HUP) do
 					# $stderr.puts "Received HUP signal, restarting...", caller
-					::Thread.current.raise(Hangup)
+					::Thread.current.raise(Restart)
 				end
 				
-				self.start
-				
-				while @container&.running?
-					begin
-						@container.wait
-					rescue SignalException => exception
-						if handler = @signals[exception.signo]
-							begin
-								handler.call
-							rescue SetupError => error
-								Console.logger.error(self) {error}
-							end
-						else
-							raise
-						end
-					end
+				::Thread.handle_interrupt(SignalException => :never) do
+					yield
 				end
-			rescue Interrupt
-				self.stop
-			rescue Terminate
-				self.stop(false)
 			ensure
-				self.stop(false)
-				
 				# Restore the interrupt handler:
 				Signal.trap(:INT, interrupt_action)
 				Signal.trap(:TERM, terminate_action)

data/lib/async/container/error.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 
 module Async
 	module Container
@@ -12,15 +12,15 @@ module Async
 		
 		# Similar to {Interrupt}, but represents `SIGTERM`.
 		class Terminate < SignalException
-			SIGTERM = Signal.list['TERM']
+			SIGTERM = Signal.list["TERM"]
 
 			def initialize
 				super(SIGTERM)
 			end
 		end
 		
-		class Hangup < SignalException
-			SIGHUP = Signal.list['HUP']
+		class Restart < SignalException
+			SIGHUP = Signal.list["HUP"]
 			
 			def initialize
 				super(SIGHUP)

data/lib/async/container/forked.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 
-require_relative 'generic'
-require_relative 'process'
+require_relative "error"
+
+require_relative "generic"
+require_relative "channel"
+require_relative "notify/pipe"
 
 module Async
 	module Container
@@ -15,11 +18,208 @@ module Async
 				true
 			end
 			
+			# Represents a running child process from the point of view of the parent container.
+			class Child < Channel
+				# Represents a running child process from the point of view of the child process.
+				class Instance < Notify::Pipe
+					# Wrap an instance around the {Process} instance from within the forked child.
+					# @parameter process [Process] The process intance to wrap.
+					def self.for(process)
+						instance = self.new(process.out)
+						
+						# The child process won't be reading from the channel:
+						process.close_read
+						
+						instance.name = process.name
+						
+						return instance
+					end
+					
+					def initialize(io)
+						super
+						
+						@name = nil
+					end
+					
+					# Set the process title to the specified value.
+					# @parameter value [String] The name of the process.
+					def name= value
+						if @name = value
+							::Process.setproctitle(@name)
+						end
+					end
+					
+					# The name of the process.
+					# @returns [String]
+					def name
+						@name
+					end
+					
+					# Replace the current child process with a different one. Forwards arguments and options to {::Process.exec}.
+					# This method replaces the child process with the new executable, thus this method never returns.
+					def exec(*arguments, ready: true, **options)
+						if ready
+							self.ready!(status: "(exec)")
+						else
+							self.before_spawn(arguments, options)
+						end
+						
+						::Process.exec(*arguments, **options)
+					end
+				end
+				
+				# Fork a child process appropriate for a container.
+				# @returns [Process]
+				def self.fork(**options)
+					# $stderr.puts fork: caller
+					self.new(**options) do |process|
+						::Process.fork do
+							# We use `Thread.current.raise(...)` so that exceptions are filtered through `Thread.handle_interrupt` correctly.
+							Signal.trap(:INT) {::Thread.current.raise(Interrupt)}
+							Signal.trap(:TERM) {::Thread.current.raise(Terminate)}
+							Signal.trap(:HUP) {::Thread.current.raise(Restart)}
+							
+							# This could be a configuration option:
+							::Thread.handle_interrupt(SignalException => :immediate) do
+								yield Instance.for(process)
+							rescue Interrupt
+								# Graceful exit.
+							rescue Exception => error
+								Console.error(self, error)
+								
+								exit!(1)
+							end
+						end
+					end
+				end
+				
+				def self.spawn(*arguments, name: nil, **options)
+					self.new(name: name) do |process|
+						Notify::Pipe.new(process.out).before_spawn(arguments, options)
+						
+						::Process.spawn(*arguments, **options)
+					end
+				end
+				
+				# Initialize the process.
+				# @parameter name [String] The name to use for the child process.
+				def initialize(name: nil)
+					super()
+					
+					@name = name
+					@status = nil
+					@pid = nil
+					
+					@pid = yield(self)
+					
+					# The parent process won't be writing to the channel:
+					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
+					@name = value
+					
+					# If we are the child process:
+					::Process.setproctitle(@name) if @pid.nil?
+				end
+				
+				# The name of the process.
+				# @attribute [String]
+				attr :name
+				
+				# @attribute [Integer] The process identifier.
+				attr :pid
+				
+				# A human readable representation of the process.
+				# @returns [String]
+				def inspect
+					"\#<#{self.class} name=#{@name.inspect} status=#{@status.inspect} pid=#{@pid.inspect}>"
+				end
+				
+				alias to_s inspect
+				
+				# Invoke {#terminate!} and then {#wait} for the child process to exit.
+				def close
+					self.terminate!
+					self.wait
+				ensure
+					super
+				end
+				
+				# Send `SIGINT` to the child process.
+				def interrupt!
+					unless @status
+						::Process.kill(:INT, @pid)
+					end
+				end
+				
+				# Send `SIGTERM` to the child process.
+				def terminate!
+					unless @status
+						::Process.kill(:TERM, @pid)
+					end
+				end
+				
+				# Send `SIGHUP` to the child process.
+				def restart!
+					unless @status
+						::Process.kill(:HUP, @pid)
+					end
+				end
+				
+				# Wait for the child process to exit.
+				# @asynchronous This method may block.
+				#
+				# @returns [::Process::Status] The process exit status.
+				def wait
+					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)
+							
+							_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
+							
+							if @status.nil?
+								Console.warn(self) {"Process #{@pid} is blocking, has it exited?"}
+							end
+						end
+					end
+					
+					Console.debug(self, "Process exited.", pid: @pid, status: @status)
+					
+					return @status
+				end
+			end
+			
+			
 			# Start a named child process and execute the provided block in it.
 			# @parameter name [String] The name (title) of the child process.
 			# @parameter block [Proc] The block to execute in the child process.
 			def start(name, &block)
-				Process.fork(name: name, &block)
+				Child.fork(name: name, &block)
 			end
 		end
 	end

data/lib/async/container/generic.rb

@@ -3,18 +3,17 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require 'async'
+require "etc"
+require "async/clock"
 
-require 'etc'
-
-require_relative 'group'
-require_relative 'keyed'
-require_relative 'statistics'
+require_relative "group"
+require_relative "keyed"
+require_relative "statistics"
 
 module Async
 	module Container
 		# An environment variable key to override {.processor_count}.
-		ASYNC_CONTAINER_PROCESSOR_COUNT = 'ASYNC_CONTAINER_PROCESSOR_COUNT'
+		ASYNC_CONTAINER_PROCESSOR_COUNT = "ASYNC_CONTAINER_PROCESSOR_COUNT"
 		
 		# The processor count which may be used for the default number of container threads/processes. You can override the value provided by the system by specifying the `ASYNC_CONTAINER_PROCESSOR_COUNT` environment variable.
 		# @returns [Integer] The number of hardware processors which can run threads/processes simultaneously.
@@ -104,16 +103,23 @@ module Async
 			# @returns [Boolean] The children all became ready.
 			def wait_until_ready
 				while true
-					Console.logger.debug(self) do |buffer|
+					Console.debug(self) do |buffer|
 						buffer.puts "Waiting for ready:"
 						@state.each do |child, state|
-							buffer.puts "\t#{child.class}: #{state.inspect}"
+							buffer.puts "\t#{child.inspect}: #{state}"
 						end
 					end
 					
 					self.sleep
 					
 					if self.status?(:ready)
+						Console.logger.debug(self) do |buffer|
+							buffer.puts "All ready:"
+							@state.each do |child, state|
+								buffer.puts "\t#{child.inspect}: #{state}"
+							end
+						end
+						
 						return true
 					end
 				end
@@ -126,7 +132,7 @@ module Async
 				@group.stop(timeout)
 				
 				if @group.running?
-					Console.logger.warn(self) {"Group is still running after stopping it!"}
+					Console.warn(self) {"Group is still running after stopping it!"}
 				end
 			ensure
 				@running = true
@@ -136,11 +142,12 @@ 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)
-					Console.logger.debug(self) {"Reusing existing child for #{key}: #{name}"}
+					Console.debug(self) {"Reusing existing child for #{key}: #{name}"}
 					return false
 				end
 				
@@ -152,19 +159,34 @@ 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)
 						end
 						
 						if status.success?
-							Console.logger.debug(self) {"#{child} exited with #{status}"}
+							Console.debug(self) {"#{child} exited with #{status}"}
 						else
 							@statistics.failure!
-							Console.logger.error(self) {status}
+							Console.error(self, status: status)
 						end
 						
 						if restart
@@ -190,8 +212,12 @@ module Async
 			
 			# @deprecated Please use {spawn} or {run} instead.
 			def async(**options, &block)
+				# warn "#{self.class}##{__method__} is deprecated, please use `spawn` or `run` instead.", uplevel: 1
+				
+				require "async"
+				
 				spawn(**options) do |instance|
-					Async::Reactor.run(instance, &block)
+					Async(instance, &block)
 				end
 			end