async-container 0.18.3 → 0.19.0

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,202 @@ 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
+							yield Instance.for(thread)
+						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
+				
+				# 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
+					
+					# 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.19.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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.18.3
+  version: 0.19.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -9,7 +9,6 @@ authors:
 - Anton Sozontov
 - Juan Antonio Martín Lucas
 - Yuji Yaginuma
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -41,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-09-04 00:00:00.000000000 Z
+date: 2025-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -57,8 +56,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.10'
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -79,20 +76,18 @@ files:
 - lib/async/container/notify/pipe.rb
 - lib/async/container/notify/server.rb
 - lib/async/container/notify/socket.rb
-- lib/async/container/process.rb
 - lib/async/container/statistics.rb
-- lib/async/container/thread.rb
 - lib/async/container/threaded.rb
 - lib/async/container/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async-container
 licenses:
 - MIT
 metadata:
   documentation_uri: https://socketry.github.io/async-container/
   source_code_uri: https://github.com/socketry/async-container.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -107,8 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.
 test_files: []

data/lib/async/container/process.rb

@@ -1,172 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
-
-require_relative 'channel'
-require_relative 'error'
-
-require_relative 'notify/pipe'
-
-module Async
-	module Container
-		# Represents a running child process from the point of view of the parent container.
-		class Process < 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)
-				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)}
-						
-						begin
-							yield Instance.for(process)
-						rescue Interrupt
-							# Graceful exit.
-						rescue Exception => error
-							Console.logger.error(self) {error}
-							
-							exit!(1)
-						end
-					end
-				end
-			end
-			
-			# def self.spawn(*arguments, name: nil, **options)
-			# 	self.new(name: name) do |process|
-			# 		unless options.key?(:out)
-			# 			options[:out] = process.out
-			# 		end
-			# 
-			# 		::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
-			
-			# A human readable representation of the process.
-			# @returns [String]
-			def to_s
-				"\#<#{self.class} #{@name}>"
-			end
-			
-			# 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
-			
-			# Wait for the child process to exit.
-			# @returns [::Process::Status] The process exit status.
-			def wait
-				if @pid && @status.nil?
-					_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
-					
-					if @status.nil?
-						sleep(0.01)
-						_, @status = ::Process.wait2(@pid, ::Process::WNOHANG)
-					end
-					
-					if @status.nil?
-						Console.logger.warn(self) {"Process #{@pid} is blocking, has it exited?"}
-						_, @status = ::Process.wait2(@pid)
-					end
-				end
-				
-				return @status
-			end
-		end
-	end
-end