async-container 0.16.3 → 0.16.8

data/lib/async/container/group.rb

@@ -21,7 +21,6 @@
 # THE SOFTWARE.
 
 require 'fiber'
-
 require 'async/clock'
 
 require_relative 'error'
@@ -30,6 +29,7 @@ module Async
 	module Container
 		# Manages a group of running processes.
 		class Group
+			# Initialize an empty group.
 			def initialize
 				@running = {}
 				
@@ -40,19 +40,25 @@ module Async
 			# @attribute [Hash<IO, Fiber>] the running tasks, indexed by IO.
 			attr :running
 			
+			# Whether the group contains any running processes.
+			# @returns [Boolean]
 			def running?
 				@running.any?
 			end
 			
+			# Whether the group contains any running processes.
+			# @returns [Boolean]
 			def any?
 				@running.any?
 			end
 			
+			# Whether the group is empty.
+			# @returns [Boolean]
 			def empty?
 				@running.empty?
 			end
 			
-			# This method sleeps for at most the specified duration.
+			# Sleep for at most the specified duration until some state change occurs.
 			def sleep(duration)
 				self.resume
 				self.suspend
@@ -60,6 +66,7 @@ module Async
 				self.wait_for_children(duration)
 			end
 			
+			# Begin any outstanding queued processes and wait for them indefinitely.
 			def wait
 				self.resume
 				
@@ -68,26 +75,33 @@ module Async
 				end
 			end
 			
+			# Interrupt all running processes.
+			# This resumes the controlling fiber with an instance of {Interrupt}.
 			def interrupt
+				Async.logger.debug(self, "Sending interrupt to #{@running.size} running processes...")
 				@running.each_value do |fiber|
 					fiber.resume(Interrupt)
 				end
 			end
 			
+			# Terminate all running processes.
+			# This resumes the controlling fiber with an instance of {Terminate}.
 			def terminate
+				Async.logger.debug(self, "Sending terminate to #{@running.size} running processes...")
 				@running.each_value do |fiber|
 					fiber.resume(Terminate)
 				end
 			end
 			
+			# Stop all child processes using {#terminate}.
+			# @parameter timeout [Boolean | Numeric | Nil] If specified, invoke a graceful shutdown using {#interrupt} first.
 			def stop(timeout = 1)
-				# Handle legacy `graceful = true` argument:
+				# Use a default timeout if not specified:
+				timeout = 1 if timeout == true
+				
 				if timeout
 					start_time = Async::Clock.now
 					
-					# Use a default timeout if not specified:
-					timeout = 1 if timeout == true
-					
 					self.interrupt
 					
 					while self.any?
@@ -103,14 +117,6 @@ module Async
 					end
 				end
 				
-				# Timeout can also be `graceful = false`:
-				if timeout
-					self.interrupt
-					self.sleep(timeout)
-				end
-				
-				self.wait_for_children(duration)
-				
 				# Terminate all children:
 				self.terminate
 				
@@ -118,6 +124,7 @@ module Async
 				self.wait
 			end
 			
+			# Wait for a message in the specified {Channel}.
 			def wait_for(channel)
 				io = channel.in
 				
@@ -144,6 +151,7 @@ module Async
 			
 			def wait_for_children(duration = nil)
 				if !@running.empty?
+					# Maybe consider using a proper event loop here:
 					readable, _, _ = ::IO.select(@running.keys, nil, nil, duration)
 					
 					readable&.each do |io|

data/lib/async/container/hybrid.rb

@@ -25,7 +25,12 @@ require_relative 'threaded'
 
 module Async
 	module Container
+		# Provides a hybrid multi-process multi-thread container.
 		class Hybrid < Forked
+			# Run multiple instances of the same block in the container.
+			# @parameter count [Integer] The number of instances to start.
+			# @parameter forks [Integer] The number of processes to fork.
+			# @parameter threads [Integer] the number of threads to start.
 			def run(count: nil, forks: nil, threads: nil, **options, &block)
 				processor_count = Container.processor_count
 				count ||= processor_count ** 2
@@ -33,12 +38,21 @@ module Async
 				threads = (count / forks).ceil
 				
 				forks.times do
-					self.spawn(**options) do
-						container = Threaded::Container.new
+					self.spawn(**options) do |instance|
+						container = Threaded.new
 						
 						container.run(count: threads, **options, &block)
 						
+						container.wait_until_ready
+						instance.ready!
+						
 						container.wait
+					rescue Async::Container::Terminate
+						# Stop it immediately:
+						container.stop(false)
+					ensure
+						# Stop it gracefully (also code path for Interrupt):
+						container.stop
 					end
 				end
 				

data/lib/async/container/keyed.rb

@@ -22,6 +22,8 @@
 
 module Async
 	module Container
+		# Tracks a key/value pair such that unmarked keys can be identified and cleaned up.
+		# This helps implement persistent processes that start up child processes per directory or configuration file. If those directories and/or configuration files are removed, the child process can then be cleaned up automatically, because those key/value pairs will not be marked when reloading the container.
 		class Keyed
 			def initialize(key, value)
 				@key = key
@@ -29,21 +31,31 @@ module Async
 				@marked = true
 			end
 			
+			# The key. Normally a symbol or a file-system path.
+			# @attribute [Object]
 			attr :key
+			
+			# The value. Normally a child instance of some sort.
+			# @attribute [Object]
 			attr :value
 			
+			# Has the instance been marked?
+			# @returns [Boolean]
 			def marked?
 				@marked
 			end
 			
+			# Mark the instance. This will indiciate that the value is still in use/active.
 			def mark!
 				@marked = true
 			end
 			
+			# Clear the instance. This is normally done before reloading a container.
 			def clear!
 				@marked = false
 			end
 			
+			# Stop the instance if it was not marked.
 			def stop?
 				unless @marked
 					@value.stop

data/lib/async/container/notify.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -28,12 +27,12 @@ require_relative 'notify/console'
 module Async
 	module Container
 		module Notify
-			# We cache the client on a per-process basis. Because that's the relevant scope for process readiness protocols.
-			@@client = nil
+			@client = nil
 			
+			# Select the best available notification client.
+			# We cache the client on a per-process basis. Because that's the relevant scope for process readiness protocols.
 			def self.open!
-				# Select the best available client:
-				@@client ||= (
+				@client ||= (
 					Pipe.open! ||
 					Socket.open! ||
 					Console.open!

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -23,12 +22,17 @@
 
 module Async
 	module Container
+		# Handles the details of several process readiness protocols.
 		module Notify
 			class Client
+				# Notify the parent controller that the child has become ready, with a brief status message.
+				# @parameters message [Hash] Additional details to send with the message.
 				def ready!(**message)
 					send(ready: true, **message)
 				end
 				
+				# Notify the parent controller that the child is reloading.
+				# @parameters message [Hash] Additional details to send with the message.
 				def reloading!(**message)
 					message[:ready] = false
 					message[:reloading] = true
@@ -37,6 +41,8 @@ module Async
 					send(**message)
 				end
 				
+				# Notify the parent controller that the child is restarting.
+				# @parameters message [Hash] Additional details to send with the message.
 				def restarting!(**message)
 					message[:ready] = false
 					message[:reloading] = true
@@ -45,14 +51,23 @@ module Async
 					send(**message)
 				end
 				
+				# Notify the parent controller that the child is stopping.
+				# @parameters message [Hash] Additional details to send with the message.
 				def stopping!(**message)
 					message[:stopping] = true
+					
+					send(**message)
 				end
 				
+				# Notify the parent controller of a status change.
+				# @parameters text [String] The details of the status change.
 				def status!(text)
 					send(status: text)
 				end
 				
+				# Notify the parent controller of an error condition.
+				# @parameters text [String] The details of the error condition.
+				# @parameters message [Hash] Additional details to send with the message.
 				def error!(text, **message)
 					send(status: text, **message)
 				end

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -28,39 +27,27 @@ require 'console/logger'
 module Async
 	module Container
 		module Notify
+			# Implements a general process readiness protocol with output to the local console.
 			class Console < Client
+				# Open a notification client attached to the current console.
 				def self.open!(logger = ::Console.logger)
 					self.new(logger)
 				end
 				
+				# Initialize the notification client.
+				# @parameter logger [Console::Logger] The console logger instance to send messages to.
 				def initialize(logger)
 					@logger = logger
 				end
 				
+				# Send a message to the console.
 				def send(level: :debug, **message)
-					@logger.send(level, self) {message[:status]}
-				end
-				
-				def ready!(**message)
-					send(ready: true, **message)
-				end
-				
-				def restarting!(**message)
-					message[:ready] = false
-					message[:reloading] = true
-					message[:status] ||= "Restarting..."
-					
-					send(**message)
-				end
-				
-				def reloading!(**message)
-					message[:ready] = false
-					message[:reloading] = true
-					message[:status] ||= "Reloading..."
-					
-					send(**message)
+					@logger.send(level, self) {message}
 				end
 				
+				# Send an error message to the console.
+				# @parameters text [String] The details of the error condition.
+				# @parameters message [Hash] Additional details to send with the message.
 				def error!(text, **message)
 					send(status: text, level: :error, **message)
 				end

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -28,9 +27,12 @@ require 'json'
 module Async
 	module Container
 		module Notify
+			# 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'
 				
+				# Open a notification client attached to the current {NOTIFY_PIPE} if possible.
 				def self.open!(environment = ENV)
 					if descriptor = environment.delete(NOTIFY_PIPE)
 						self.new(::IO.for_fd(descriptor.to_i))
@@ -41,6 +43,8 @@ module Async
 					return nil
 				end
 				
+				# Initialize the notification client.
+				# @parameter io [IO] An IO instance used for sending messages.
 				def initialize(io)
 					@io = io
 				end
@@ -72,6 +76,8 @@ module Async
 					end
 				end
 				
+				# Formats the message using JSON and sends it to the parent controller.
+				# This is suitable for use with {Channel}.
 				def send(**message)
 					data = ::JSON.dump(message)
 					
@@ -79,26 +85,6 @@ module Async
 					@io.flush
 				end
 				
-				def ready!(**message)
-					send(ready: true, **message)
-				end
-				
-				def restarting!(**message)
-					message[:ready] = false
-					message[:reloading] = true
-					message[:status] ||= "Restarting..."
-					
-					send(**message)
-				end
-				
-				def reloading!(**message)
-					message[:ready] = false
-					message[:reloading] = true
-					message[:status] ||= "Reloading..."
-					
-					send(**message)
-				end
-				
 				private
 				
 				def environment_for(arguments)

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -98,7 +97,7 @@ module Async
 					
 					def receive
 						while true
-							data, address, flags, *controls = @bound.recvmsg(MAXIMUM_MESSAGE_SIZE)
+							data, _address, _flags, *_controls = @bound.recvmsg(MAXIMUM_MESSAGE_SIZE)
 							
 							message = Server.load(data)
 							

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

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-#
 # Copyright, 2020, by Samuel G. D. Williams. <http://www.codeotaku.com>
 # 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -30,21 +29,31 @@ require 'kernel/sync'
 module Async
 	module Container
 		module Notify
+			# Implements the systemd NOTIFY_SOCKET process readiness protocol.
+			# 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'
+				
+				# The maximum allowed size of the UDP message.
 				MAXIMUM_MESSAGE_SIZE = 4096
 				
+				# Open a notification client attached to the current {NOTIFY_SOCKET} if possible.
 				def self.open!(environment = ENV)
 					if path = environment.delete(NOTIFY_SOCKET)
 						self.new(path)
 					end
 				end
 				
+				# Initialize the notification client.
+				# @parameter path [String] The path to the UNIX socket used for sending messages to the process manager.
 				def initialize(path)
 					@path = path
 					@endpoint = IO::Endpoint.unix(path, ::Socket::SOCK_DGRAM)
 				end
 				
+				# 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)
 					buffer = String.new
 					
@@ -62,6 +71,8 @@ module Async
 					return buffer
 				end
 				
+				# Send the given message.
+				# @parameter message [Hash]
 				def send(**message)
 					data = dump(message)
 					
@@ -76,6 +87,8 @@ module Async
 					end
 				end
 				
+				# Send the specified error.
+				# `sd_notify` requires an `errno` key, which defaults to `-1` to indicate a generic error.
 				def error!(text, **message)
 					message[:errno] ||= -1