async-container 0.18.3 → 0.20.0

data/lib/async/container/group.rb

@@ -3,17 +3,22 @@
 # Released under the MIT License.
 # Copyright, 2018-2024, by Samuel Williams.
 
-require 'fiber'
-require 'async/clock'
+require "fiber"
+require "async/clock"
 
-require_relative 'error'
+require_relative "error"
 
 module Async
 	module Container
 		# 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,15 +62,43 @@ 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
 			
 			# Interrupt all running processes.
 			# This resumes the controlling fiber with an instance of {Interrupt}.
 			def interrupt
-				Console.logger.debug(self, "Sending interrupt to #{@running.size} running processes...")
+				Console.info(self, "Sending interrupt to #{@running.size} running processes...")
 				@running.each_value do |fiber|
 					fiber.resume(Interrupt)
 				end
@@ -74,7 +107,7 @@ module Async
 			# Terminate all running processes.
 			# This resumes the controlling fiber with an instance of {Terminate}.
 			def terminate
-				Console.logger.debug(self, "Sending terminate to #{@running.size} running processes...")
+				Console.info(self, "Sending terminate to #{@running.size} running processes...")
 				@running.each_value do |fiber|
 					fiber.resume(Terminate)
 				end
@@ -83,6 +116,7 @@ module Async
 			# 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.info(self, "Stopping all processes...", timeout: timeout)
 				# Use a default timeout if not specified:
 				timeout = 1 if timeout == true
 				
@@ -105,7 +139,7 @@ module Async
 				end
 				
 				# Terminate all children:
-				self.terminate
+				self.terminate if any?
 				
 				# Wait for all children to exit:
 				self.wait
@@ -118,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
@@ -137,14 +175,24 @@ module Async
 			protected
 			
 			def wait_for_children(duration = nil)
-				Console.debug(self, "Waiting for children...", duration: duration)
+				Console.debug(self, "Waiting for children...", duration: duration, running: @running)
+				
 				if !@running.empty?
 					# Maybe consider using a proper event loop here:
+					if ready = self.select(duration)
+						ready.each do |io|
+							@running[io].resume
+						end
+					end
+				end
+			end
+			
+			# Wait for a child process to exit OR a signal to be received.
+			def select(duration)
+				::Thread.handle_interrupt(SignalException => :immediate) do
 					readable, _, _ = ::IO.select(@running.keys, nil, nil, duration)
 					
-					readable&.each do |io|
-						@running[io].resume
-					end
+					return readable
 				end
 			end
 			

data/lib/async/container/hybrid.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.
 # Copyright, 2022, by Anton Sozontov.
 
-require_relative 'forked'
-require_relative 'threaded'
+require_relative "forked"
+require_relative "threaded"
 
 module Async
 	module Container

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

@@ -3,9 +3,9 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'client'
+require_relative "client"
 
-require 'console/logger'
+require "console"
 
 module Async
 	module Container
@@ -24,8 +24,8 @@ module Async
 				end
 				
 				# Send a message to the console.
-				def send(level: :debug, **message)
-					@logger.send(level, self) {message}
+				def send(level: :info, **message)
+					@logger.public_send(level, self) {message}
 				end
 				
 				# Send an error message to the console.

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

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 # Copyright, 2020, by Juan Antonio Martín Lucas.
 
-require_relative 'client'
+require_relative "client"
 
-require 'json'
+require "json"
 
 module Async
 	module Container
@@ -14,7 +14,7 @@ module Async
 			# Implements a process readiness protocol using an inherited pipe file descriptor.
 			class Pipe < Client
 				# The environment variable key which contains the pipe file descriptor.
-				NOTIFY_PIPE = 'NOTIFY_PIPE'
+				NOTIFY_PIPE = "NOTIFY_PIPE"
 				
 				# Open a notification client attached to the current {NOTIFY_PIPE} if possible.
 				def self.open!(environment = ENV)
@@ -22,7 +22,7 @@ module Async
 						self.new(::IO.for_fd(descriptor.to_i))
 					end
 				rescue Errno::EBADF => error
-					Console.logger.error(self) {error}
+					Console.error(self) {error}
 					
 					return nil
 				end

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

@@ -4,14 +4,13 @@
 # Copyright, 2020-2024, by Samuel Williams.
 # Copyright, 2020, by Olle Jonsson.
 
-require 'tmpdir'
-require 'securerandom'
+require "tmpdir"
+require "securerandom"
 
 module Async
 	module Container
 		module Notify
 			class Server
-				NOTIFY_SOCKET = 'NOTIFY_SOCKET'
 				MAXIMUM_MESSAGE_SIZE = 4096
 				
 				def self.load(message)
@@ -22,13 +21,17 @@ module Async
 					pairs = lines.map do |line|
 						key, value = line.split("=", 2)
 						
-						if value == '0'
+						key = key.downcase.to_sym
+						
+						if value == "0"
 							value = false
-						elsif value == '1'
+						elsif value == "1"
 							value = true
+						elsif key == :errno and value =~ /\A\-?\d+\z/
+							value = Integer(value)
 						end
 						
-						next [key.downcase.to_sym, value]
+						next [key, value]
 					end
 					
 					return Hash[pairs]
@@ -75,7 +78,11 @@ module Async
 							
 							message = Server.load(data)
 							
-							yield message
+							if block_given?
+								yield message
+							else
+								return message
+							end
 						end
 					end
 				end

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

@@ -3,7 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'client'
+require_relative "client"
+require "socket"
 
 module Async
 	module Container
@@ -12,7 +13,7 @@ module Async
 			# See <https://www.freedesktop.org/software/systemd/man/sd_notify.html> for more details of the underlying protocol.
 			class Socket < Client
 				# The name of the environment variable which contains the path to the notification socket.
-				NOTIFY_SOCKET = 'NOTIFY_SOCKET'
+				NOTIFY_SOCKET = "NOTIFY_SOCKET"
 				
 				# The maximum allowed size of the UDP message.
 				MAXIMUM_MESSAGE_SIZE = 4096
@@ -31,6 +32,9 @@ module Async
 					@address = Addrinfo.unix(path, ::Socket::SOCK_DGRAM)
 				end
 				
+				# @attribute [String] The path to the UNIX socket used for sending messages to the controller.
+				attr :path
+				
 				# Dump a message in the format requied by `sd_notify`.
 				# @parameter message [Hash] Keys and values should be string convertible objects. Values which are `true`/`false` are converted to `1`/`0` respectively.
 				def dump(message)
@@ -56,7 +60,7 @@ module Async
 					data = dump(message)
 					
 					if data.bytesize > MAXIMUM_MESSAGE_SIZE
-						raise ArgumentError, "Message length #{message.bytesize} exceeds #{MAXIMUM_MESSAGE_SIZE}: #{message.inspect}"
+						raise ArgumentError, "Message length #{data.bytesize} exceeds #{MAXIMUM_MESSAGE_SIZE}: #{message.inspect}"
 					end
 					
 					@address.connect do |peer|
@@ -69,7 +73,7 @@ module Async
 				def error!(text, **message)
 					message[:errno] ||= -1
 					
-					send(status: text, **message)
+					super
 				end
 			end
 		end

data/lib/async/container/notify.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2022, by Samuel Williams.
+# Copyright, 2020-2024, by Samuel Williams.
 
-require_relative 'notify/pipe'
-require_relative 'notify/socket'
-require_relative 'notify/console'
+require_relative "notify/pipe"
+require_relative "notify/socket"
+require_relative "notify/console"
 
 module Async
 	module Container

data/lib/async/container/statistics.rb

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

data/lib/async/container/threaded.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 
-require_relative 'generic'
-require_relative 'thread'
+require_relative "generic"
+require_relative "channel"
+require_relative "notify/pipe"
 
 module Async
 	module Container
@@ -15,11 +16,230 @@ module Async
 				false
 			end
 			
+			# Represents a running child thread from the point of view of the parent container.
+			class Child < Channel
+				# Used to propagate the exit status of a child process invoked by {Instance#exec}.
+				class Exit < Exception
+					# Initialize the exit status.
+					# @parameter status [::Process::Status] The process exit status.
+					def initialize(status)
+						@status = status
+					end
+					
+					# The process exit status.
+					# @attribute [::Process::Status]
+					attr :status
+					
+					# The process exit status if it was an error.
+					# @returns [::Process::Status | Nil]
+					def error
+						unless status.success?
+							status
+						end
+					end
+				end
+				
+				# Represents a running child thread from the point of view of the child thread.
+				class Instance < Notify::Pipe
+					# Wrap an instance around the {Thread} instance from within the threaded child.
+					# @parameter thread [Thread] The thread intance to wrap.
+					def self.for(thread)
+						instance = self.new(thread.out)
+						
+						return instance
+					end
+					
+					def initialize(io)
+						@name = nil
+						@thread = ::Thread.current
+						
+						super
+					end
+					
+					# Set the name of the thread.
+					# @parameter value [String] The name to set.
+					def name= value
+						@thread.name = value
+					end
+					
+					# Get the name of the thread.
+					# @returns [String]
+					def name
+						@thread.name
+					end
+					
+					# Execute a child process using {::Process.spawn}. In order to simulate {::Process.exec}, an {Exit} instance is raised to propagage exit status.
+					# This creates the illusion that this method does not return (normally).
+					def exec(*arguments, ready: true, **options)
+						if ready
+							self.ready!(status: "(spawn)")
+						else
+							self.before_spawn(arguments, options)
+						end
+						
+						begin
+							pid = ::Process.spawn(*arguments, **options)
+						ensure
+							_, status = ::Process.wait2(pid)
+							
+							raise Exit, status
+						end
+					end
+				end
+				
+				def self.fork(**options)
+					self.new(**options) do |thread|
+						::Thread.new do
+							# This could be a configuration option (see forked implementation too):
+							::Thread.handle_interrupt(SignalException => :immediate) do
+								yield Instance.for(thread)
+							end
+						end
+					end
+				end
+				
+				# Initialize the thread.
+				# @parameter name [String] The name to use for the child thread.
+				def initialize(name: nil)
+					super()
+					
+					@status = nil
+					
+					@thread = yield(self)
+					@thread.report_on_exception = false
+					@thread.name = name
+					
+					@waiter = ::Thread.new do
+						begin
+							@thread.join
+						rescue Exit => exit
+							finished(exit.error)
+						rescue Interrupt
+							# Graceful shutdown.
+							finished
+						rescue Exception => error
+							finished(error)
+						else
+							finished
+						end
+					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
+					@thread.name = value
+				end
+				
+				# Get the name of the thread.
+				# @returns [String]
+				def name
+					@thread.name
+				end
+				
+				# A human readable representation of the thread.
+				# @returns [String]
+				def to_s
+					"\#<#{self.class} #{@thread.name}>"
+				end
+				
+				# Invoke {#terminate!} and then {#wait} for the child thread to exit.
+				def close
+					self.terminate!
+					self.wait
+				ensure
+					super
+				end
+				
+				# Raise {Interrupt} in the child thread.
+				def interrupt!
+					@thread.raise(Interrupt)
+				end
+				
+				# Raise {Terminate} in the child thread.
+				def terminate!
+					@thread.raise(Terminate)
+				end
+				
+				# Raise {Restart} in the child thread.
+				def restart!
+					@thread.raise(Restart)
+				end
+				
+				# Wait for the thread to exit and return he exit status.
+				# @returns [Status]
+				def wait
+					if @waiter
+						@waiter.join
+						@waiter = nil
+					end
+					
+					return @status
+				end
+				
+				# A pseudo exit-status wrapper.
+				class Status
+					# Initialise the status.
+					# @parameter error [::Process::Status] The exit status of the child thread.
+					def initialize(error = nil)
+						@error = error
+					end
+					
+					# Whether the status represents a successful outcome.
+					# @returns [Boolean]
+					def success?
+						@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"}>"
+					end
+				end
+				
+				protected
+				
+				# Invoked by the @waiter thread to indicate the outcome of the child thread.
+				def finished(error = nil)
+					if error
+						Console.error(self) {error}
+					end
+					
+					@status = Status.new(error)
+					self.close_write
+				end
+			end
+			
 			# Start a named child thread 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)
-				Thread.fork(name: name, &block)
+				Child.fork(name: name, &block)
 			end
 		end
 	end

data/lib/async/container/version.rb

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

data/lib/async/container.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 
-require_relative 'container/controller'
+require_relative "container/controller"
 
 module Async
 	module Container

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2017-2024, by Samuel Williams.  
+Copyright, 2017-2025, by Samuel Williams.  
 Copyright, 2019, by Yuji Yaginuma.  
 Copyright, 2020, by Olle Jonsson.  
 Copyright, 2020, by Juan Antonio Martín Lucas.  

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## Unreleased
+
+  - Improve container signal handling reliability by using `Thread.handle_interrupt` except at known safe points.
+  - Improved logging when child process fails and container startup.