async-container 0.18.3 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d061fd5261bb0fabc616df89690cddd1c7545d5fc41799bc107050da08bf7635
-  data.tar.gz: 13a9e58f76b560a9f5602da7977739c936aa71732338f802a97d9fc9a6224480
+  metadata.gz: 2edeb6fa679f328736bb4a65c3b342b4aea94f2fc79557d4fc6e9e84bee77a2e
+  data.tar.gz: 5c1c52a4f90c8710efebb411d97e5a8342ea99d1bbe09082deed562b8acdce99
 SHA512:
-  metadata.gz: 1f162eadf2c624ebe86fe174578096ccb473e5f9f031f75d8135ed77cf9911f006e4b3a9957b8402829a67fa480d80c7fdf3a3abdbb02e959ae1c135e99c3c92
-  data.tar.gz: 8201e656ac4f8182380bb08af4290c51bddc62d97214fd39bf0e7761f48f339a859f809dd12539c2a53a85219e4b4b6a68bcb9a81c7ef7c9dd4bab3da563d053
+  metadata.gz: ee365ff16248e3064b136cdfeddec8e0f01ef77decbd514b94fc4a3bce1a38c2c51ffa5ba1e071b2fcd6bad6b7c4d4e322f26e8e5a530e4f45a68266d67429da
+  data.tar.gz: 171a93c5855cad3a112622232bbc7e93b880d4c77223cb8a17c7772a0687a0be40af3143a0ecad2b14a9e9aa656010cdf47eb42f80e14b08148cd02f4a4eaa6c

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,190 @@ 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
+				
+				# 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,16 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require 'async'
+require "etc"
 
-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 +102,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 +131,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
@@ -140,7 +145,7 @@ module Async
 				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
 				
@@ -161,10 +166,10 @@ module Async
 						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 +195,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
 			

data/lib/async/container/group.rb

@@ -3,10 +3,10 @@
 # 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
@@ -65,7 +65,7 @@ module Async
 			# 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 +74,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 +83,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 +106,7 @@ module Async
 				end
 				
 				# Terminate all children:
-				self.terminate
+				self.terminate if any?
 				
 				# Wait for all children to exit:
 				self.wait
@@ -137,14 +138,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.