async-container 0.16.5 → 0.16.10

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,20 +75,26 @@ 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...")
+				Console.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...")
+				Console.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)
 				# Use a default timeout if not specified:
 				timeout = 1 if timeout == true
@@ -111,6 +124,7 @@ module Async
 				self.wait
 			end
 			
+			# Wait for a message in the specified {Channel}.
 			def wait_for(channel)
 				io = channel.in
 				
@@ -137,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

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}
 				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
-				
+				# 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,19 +27,24 @@ 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))
 					end
 				rescue Errno::EBADF => error
-					Async.logger.error(self) {error}
+					Console.logger.error(self) {error}
 					
 					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

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
 					

data/lib/async/container/process.rb

@@ -27,8 +27,12 @@ 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)
 					
@@ -46,16 +50,22 @@ module Async
 					@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
@@ -63,10 +73,13 @@ module Async
 						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
@@ -78,7 +91,7 @@ module Async
 						rescue Interrupt
 							# Graceful exit.
 						rescue Exception => error
-							Async.logger.error(self) {error}
+							Console.logger.error(self) {error}
 							
 							exit!(1)
 						end
@@ -96,6 +109,8 @@ module Async
 			# 	end
 			# end
 			
+			# Initialize the process.
+			# @parameter name [String] The name to use for the child process.
 			def initialize(name: nil)
 				super()
 				
@@ -109,6 +124,8 @@ module Async
 				self.close_write
 			end
 			
+			# Set the name of the process.
+			# Invokes {::Process.setproctitle} if invoked in the child process.
 			def name= value
 				@name = value
 				
@@ -116,12 +133,17 @@ module Async
 				::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
@@ -129,18 +151,22 @@ module Async
 				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)
@@ -151,7 +177,7 @@ module Async
 					end
 					
 					if @status.nil?
-						Async.logger.warn(self) {"Process #{@pid} is blocking, has it exited?"}
+						Console.logger.warn(self) {"Process #{@pid} is blocking, has it exited?"}
 						_, @status = ::Process.wait2(@pid)
 					end
 				end