async-container 0.18.2 → 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.2"
+		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/readme.md

@@ -28,8 +28,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

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.2
+  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-04-24 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.3
-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,173 +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)") if ready
-					else
-						self.before_spawn(arguments, options)
-					end
-					
-					# TODO prefer **options... but it doesn't support redirections on < 2.7
-					::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