async-container 0.16.6 → 0.16.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cffebcdeda8a463f4bd854a2023b6942dfd56f7c0d4985555c5b2fc8ef6b5f93
-  data.tar.gz: a39ea00fceed362028c189a687372d0214b2c1da0b7b88aa16cbd4375d19b75a
+  metadata.gz: 87218f3196f6535fbb3849b6cb24ee3cc4ba6f59ed3c55ca9374b2889d51aa62
+  data.tar.gz: 3b38ac9e91231d51b0d29d7fab36c5cdae70df84833aa97307d6e4e9462b405d
 SHA512:
-  metadata.gz: b3939f550483a2330876833d50b9e79e604e81ca42160190d15b6bfb9ac213a3b4ee8851fb0f079402ffb32e5c14b29563d6beedc4cdec337d975af2bec15fc9
-  data.tar.gz: 9afebedefb06016327f5f3c88a134dc825cfbd52d1206822d8a430cc7498a6e5a90ebb4996b7157e9388f0c089c2b8135e98f188a57ef71029de190d79b05fa1
+  metadata.gz: 1c0c01247d61f0cdc5f5cf7aa404d2115ffecf853c1c33669dbd25dbed4d7e6f0db20495ffcf6052497156cfd16b41d7ec8319f7b57ee0ba6fda8aa799d28aa3
+  data.tar.gz: 6fa64afb47c7f8a83e79773ed9ca891966bf88e5ba092e304f859ffc2a76cd0525830f96ece65d9b1ca5637fc3527aa1750ff93b2374d807eca7642f68b73714

data/lib/async/container.rb

@@ -23,7 +23,6 @@
 require_relative 'container/controller'
 
 module Async
-	# Containers execute one or more "instances" which typically contain a reactor. A container spawns "instances" using threads and/or processes. Because these are resources that must be cleaned up some how (either by `join` or `waitpid`), their creation is deferred until the user invokes `Container#wait`. When executed this way, the container guarantees that all "instances" will be complete once `Container#wait` returns. Containers are constructs for achieving parallelism, and are not designed to be used directly for concurrency. Typically, you'd create one or more container, add some tasks to it, and then wait for it to complete.
 	module Container
 	end
 end

data/lib/async/container/best.rb

@@ -25,12 +25,16 @@ require_relative 'threaded'
 require_relative 'hybrid'
 
 module Async
-	# Containers execute one or more "instances" which typically contain a reactor. A container spawns "instances" using threads and/or processes. Because these are resources that must be cleaned up some how (either by `join` or `waitpid`), their creation is deferred until the user invokes `Container#wait`. When executed this way, the container guarantees that all "instances" will be complete once `Container#wait` returns. Containers are constructs for achieving parallelism, and are not designed to be used directly for concurrency. Typically, you'd create one or more container, add some tasks to it, and then wait for it to complete.
 	module Container
+		# Whether the underlying process supports fork.
+		# @returns [Boolean]
 		def self.fork?
 			::Process.respond_to?(:fork) && ::Process.respond_to?(:setpgid)
 		end
 		
+		# Determins the best container class based on the underlying Ruby implementation.
+		# Some platforms, including JRuby, don't support fork. Applications which just want a reasonable default can use this method.
+		# @returns [Class]
 		def self.best_container_class
 			if fork?
 				return Forked
@@ -39,8 +43,10 @@ module Async
 			end
 		end
 		
-		def self.new(*arguments)
-			best_container_class.new(*arguments)
+		# Create an instance of the best container class.
+		# @returns [Generic] Typically an instance of either {Forked} or {Threaded} containers.
+		def self.new(*arguments, **options)
+			best_container_class.new(*arguments, **options)
 		end
 	end
 end

data/lib/async/container/channel.rb

@@ -24,27 +24,40 @@ require 'json'
 
 module Async
 	module Container
+		# Provides a basic multi-thread/multi-process uni-directional communication channel.
 		class Channel
+			# Initialize the channel using a pipe.
 			def initialize
 				@in, @out = ::IO.pipe
 			end
 			
+			# The input end of the pipe.
+			# @attribute [IO]
 			attr :in
+			
+			# The output end of the pipe.
+			# @attribute [IO]
 			attr :out
 			
+			# Close the input end of the pipe.
 			def close_read
 				@in.close
 			end
 			
+			# Close the output end of the pipe.
 			def close_write
 				@out.close
 			end
 			
+			# Close both ends of the pipe.
 			def close
 				close_read
 				close_write
 			end
 			
+			# Receive an object from the pipe.
+			# Internally, prefers to receive newline formatted JSON, otherwise returns a hash table with a single key `:line` which contains the line of data that could not be parsed as JSON.
+			# @returns [Hash]
 			def receive
 				if data = @in.gets
 					begin

data/lib/async/container/controller.rb

@@ -28,17 +28,8 @@ require_relative 'notify'
 
 module Async
 	module Container
-		class InitializationError < Error
-			def initialize(container)
-				super("Could not create container!")
-				
-				@container = container
-			end
-			
-			attr :container
-		end
-		
-		# Manages the life-cycle of a container.
+		# Manages the life-cycle of one or more containers in order to support a persistent system.
+		# e.g. a web server, job server or some other long running system.
 		class Controller
 			SIGHUP = Signal.list["HUP"]
 			SIGINT = Signal.list["INT"]
@@ -46,6 +37,8 @@ module Async
 			SIGUSR1 = Signal.list["USR1"]
 			SIGUSR2 = Signal.list["USR2"]
 			
+			# Initialize the controller.
+			# @parameter notify [Notify::Client] A client used for process readiness notifications.
 			def initialize(notify: Notify.open!)
 				@container = nil
 				
@@ -60,6 +53,8 @@ module Async
 				end
 			end
 			
+			# The state of the controller.
+			# @returns [String]
 			def state_string
 				if running?
 					"running"
@@ -68,42 +63,61 @@ module Async
 				end
 			end
 			
+			# A human readable representation of the controller.
+			# @returns [String]
 			def to_s
 				"#{self.class} #{state_string}"
 			end
 			
+			# Trap the specified signal.
+			# @parameters signal [Symbol] The signal to trap, e.g. `:INT`.
+			# @parameters block [Proc] The signal handler to invoke.
 			def trap(signal, &block)
 				@signals[signal] = block
 			end
 			
+			# The current container being managed by the controller.
 			attr :container
 			
+			# Create a container for the controller.
+			# Can be overridden by a sub-class.
+			# @returns [Generic] A specific container instance to use.
 			def create_container
 				Container.new
 			end
 			
+			# Whether the controller has a running container.
+			# @returns [Boolean]
 			def running?
 				!!@container
 			end
 			
+			# Wait for the underlying container to start.
 			def wait
 				@container&.wait
 			end
 			
+			# Spawn container instances into the given container.
+			# Should be overridden by a sub-class.
+			# @parameter container [Generic] The container, generally from {#create_container}.
 			def setup(container)
 				# Don't do this, otherwise calling super is risky for sub-classes:
 				# raise NotImplementedError, "Container setup is must be implemented in derived class!"
 			end
 			
+			# Start the container unless it's already running.
 			def start
 				self.restart unless @container
 			end
 			
+			# Stop the container if it's running.
+			# @parameter graceful [Boolean] Whether to give the children instances time to shut down or to kill them immediately.
 			def stop(graceful = true)
 				@container&.stop(graceful)
 				@container = nil
 			end
 			
+			# Restart the container. A new container is created, and if successful, any old container is terminated gracefully.
 			def restart
 				if @container
 					@notify&.restarting!
@@ -120,7 +134,7 @@ module Async
 				rescue
 					@notify&.error!($!.to_s)
 					
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Wait for all child processes to enter the ready state.
@@ -133,7 +147,7 @@ module Async
 					
 					container.stop
 					
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Make this swap as atomic as possible:
@@ -150,6 +164,7 @@ module Async
 				raise
 			end
 			
+			# Reload the existing container. Children instances will be reloaded using `SIGHUP`.
 			def reload
 				@notify&.reloading!
 				
@@ -158,7 +173,7 @@ module Async
 				begin
 					self.setup(@container)
 				rescue
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Wait for all child processes to enter the ready state.
@@ -169,12 +184,13 @@ module Async
 				if @container.failed?
 					@notify.error!("Container failed!")
 					
-					raise InitializationError, @container
+					raise SetupError, @container
 				else
 					@notify&.ready!
 				end
 			end
 			
+			# Enter the controller run loop, trapping `SIGINT` and `SIGTERM`.
 			def run
 				# I thought this was the default... but it doesn't always raise an exception unless you do this explicitly.
 				interrupt_action = Signal.trap(:INT) do
@@ -194,7 +210,7 @@ module Async
 						if handler = @signals[exception.signo]
 							begin
 								handler.call
-							rescue InitializationError => error
+							rescue SetupError => error
 								Async.logger.error(self) {error}
 							end
 						else

data/lib/async/container/error.rb

@@ -27,6 +27,7 @@ module Async
 		
 		Interrupt = ::Interrupt
 		
+		# Similar to {Interrupt}, but represents `SIGTERM`.
 		class Terminate < SignalException
 			SIGTERM = Signal.list['TERM']
 
@@ -34,5 +35,17 @@ module Async
 				super(SIGTERM)
 			end
 		end
+		
+		# Represents the error which occured when a container failed to start up correctly.
+		class SetupError < Error
+			def initialize(container)
+				super("Could not create container!")
+				
+				@container = container
+			end
+			
+			# The container that failed.
+			attr :container
+		end
 	end
 end

data/lib/async/container/forked.rb

@@ -24,13 +24,17 @@ require_relative 'generic'
 require_relative 'process'
 
 module Async
-	# Manages a reactor within one or more threads.
 	module Container
+		# A multi-process container which uses {Process.fork}.
 		class Forked < Generic
+			# Indicates that this is a multi-process container.
 			def self.multiprocess?
 				true
 			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)
 			end

data/lib/async/container/generic.rb

@@ -30,10 +30,12 @@ require_relative 'statistics'
 
 module Async
 	module Container
+		# An environment variable key to override {.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.
-		# @return [Integer] the number of hardware processors which can run threads/processes simultaneously.
+		# 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.
+		# @raises [RuntimeError] If the process count is invalid.
 		def self.processor_count(env = ENV)
 			count = env.fetch(ASYNC_CONTAINER_PROCESSOR_COUNT) do
 				Etc.nprocessors rescue 1
@@ -46,6 +48,7 @@ module Async
 			return count
 		end
 		
+		# A base class for implementing containers.
 		class Generic
 			def self.run(*arguments, **options, &block)
 				self.new.run(*arguments, **options, &block)
@@ -65,27 +68,35 @@ module Async
 			
 			attr :state
 			
+			# A human readable representation of the container.
+			# @returns [String]
 			def to_s
 				"#{self.class} with #{@statistics.spawns} spawns and #{@statistics.failures} failures."
 			end
 			
+			# Look up a child process by key.
+			# A key could be a symbol, a file path, or something else which the child instance represents.
 			def [] key
 				@keyed[key]&.value
 			end
 			
+			# Statistics relating to the behavior of children instances.
+			# @attribute [Statistics]
 			attr :statistics
 			
+			# Whether any failures have occurred within the container.
+			# @returns [Boolean]
 			def failed?
 				@statistics.failed?
 			end
 			
-			# Whether there are running tasks.
+			# Whether the container has running children instances.
 			def running?
 				@group.running?
 			end
 			
 			# Sleep until some state change occurs.
-			# @param duration [Integer] the maximum amount of time to sleep for.
+			# @parameter duration [Numeric] the maximum amount of time to sleep for.
 			def sleep(duration = nil)
 				@group.sleep(duration)
 			end
@@ -95,11 +106,17 @@ module Async
 				@group.wait
 			end
 			
+			# Returns true if all children instances have the specified status flag set.
+			# e.g. `:ready`.
+			# This state is updated by the process readiness protocol mechanism. See {Notify::Client} for more details.
+			# @returns [Boolean]
 			def status?(flag)
 				# This also returns true if all processes have exited/failed:
 				@state.all?{|_, state| state[flag]}
 			end
 			
+			# Wait until all the children instances have indicated that they are ready.
+			# @returns [Boolean] The children all became ready.
 			def wait_until_ready
 				while true
 					Async.logger.debug(self) do |buffer|
@@ -117,6 +134,8 @@ module Async
 				end
 			end
 			
+			# Stop the children instances.
+			# @parameter timeout [Boolean | Numeric] Whether to stop gracefully, or a specific timeout.
 			def stop(timeout = true)
 				@running = false
 				@group.stop(timeout)
@@ -128,6 +147,10 @@ module Async
 				@running = true
 			end
 			
+			# Spawn a child instance into the container.
+			# @parameter name [String] The name of the child instance.
+			# @parameter restart [Boolean] Whether to restart the child instance if it fails.
+			# @parameter key [Symbol] A key used for reloading child instances.
 			def spawn(name: nil, restart: false, key: nil, &block)
 				name ||= UNNAMED
 				
@@ -172,12 +195,8 @@ module Async
 				return true
 			end
 			
-			def async(**options, &block)
-				spawn(**options) do |instance|
-					Async::Reactor.run(instance, &block)
-				end
-			end
-			
+			# Run multiple instances of the same block in the container.
+			# @parameter count [Integer] The number of instances to start.
 			def run(count: Container.processor_count, **options, &block)
 				count.times do
 					spawn(**options, &block)
@@ -186,6 +205,14 @@ module Async
 				return self
 			end
 			
+			# @deprecated Please use {spawn} or {run} instead.
+			def async(**options, &block)
+				spawn(**options) do |instance|
+					Async::Reactor.run(instance, &block)
+				end
+			end
+			
+			# Reload the container's keyed instances.
 			def reload
 				@keyed.each_value(&:clear!)
 				
@@ -200,6 +227,7 @@ module Async
 				return dirty
 			end
 			
+			# Mark the container's keyed instance which ensures that it won't be discarded.
 			def mark?(key)
 				if key
 					if value = @keyed[key]
@@ -212,6 +240,7 @@ module Async
 				return false
 			end
 			
+			# Whether a child instance exists for the given key.
 			def key?(key)
 				if key
 					@keyed.key?(key)

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,6 +75,8 @@ 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|
@@ -75,6 +84,8 @@ module Async
 				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|
@@ -82,6 +93,8 @@ module Async
 				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,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,10 +85,6 @@ module Async
 					@io.flush
 				end
 				
-				def ready!(**message)
-					send(ready: true, **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
@@ -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)

data/lib/async/container/statistics.rb

@@ -24,6 +24,7 @@ require 'async/reactor'
 
 module Async
 	module Container
+		# Tracks various statistics relating to child instances in a container.
 		class Statistics
 			def initialize
 				@spawns = 0
@@ -31,26 +32,41 @@ module Async
 				@failures = 0
 			end
 			
+			# How many child instances have been spawned.
+			# @attribute [Integer]
 			attr :spawns
+			
+			# How many child instances have been restarted.
+			# @attribute [Integer]
 			attr :restarts
+			
+			# How many child instances have failed.
+			# @attribute [Integer]
 			attr :failures
 			
+			# Increment the number of spawns by 1.
 			def spawn!
 				@spawns += 1
 			end
 			
+			# Increment the number of restarts by 1.
 			def restart!
 				@restarts += 1
 			end
 			
+			# Increment the number of failures by 1.
 			def failure!
 				@failures += 1
 			end
 			
+			# Whether there have been any failures.
+			# @returns [Boolean] If the failure count is greater than 0.
 			def failed?
 				@failures > 0
 			end
 			
+			# Append another statistics instance into this one.
+			# @parameter other [Statistics] The statistics to append.
 			def << other
 				@spawns += other.spawns
 				@restarts += other.restarts

data/lib/async/container/thread.rb

@@ -28,14 +28,22 @@ require 'async/logger'
 
 module Async
 	module Container
+		# Represents a running child thread from the point of view of the parent container.
 		class Thread < 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
@@ -43,7 +51,10 @@ module Async
 				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)
 					
@@ -57,14 +68,20 @@ module Async
 					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)") if ready
@@ -91,6 +108,8 @@ module Async
 				end
 			end
 			
+			# Initialize the thread.
+			# @parameter name [String] The name to use for the child thread.
 			def initialize(name: nil)
 				super()
 				
@@ -116,18 +135,25 @@ module Async
 				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
@@ -135,14 +161,18 @@ module Async
 				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
 			
+			# Wait for the thread to exit and return he exit status.
+			# @returns [Status]
 			def wait
 				if @waiter
 					@waiter.join
@@ -152,15 +182,21 @@ module Async
 				return @status
 			end
 			
+			# A pseudo exit-status wrapper.
 			class Status
-				def initialize(result = nil)
-					@result = result
+				# 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?
-					@result.nil?
+					@error.nil?
 				end
 				
+				# A human readable representation of the status.
 				def to_s
 					"\#<#{self.class} #{success? ? "success" : "failure"}>"
 				end
@@ -168,6 +204,7 @@ module Async
 			
 			protected
 			
+			# Invoked by the @waiter thread to indicate the outcome of the child thread.
 			def finished(error = nil)
 				if error
 					Async.logger.error(self) {error}

data/lib/async/container/threaded.rb

@@ -24,13 +24,17 @@ require_relative 'generic'
 require_relative 'thread'
 
 module Async
-	# Manages a reactor within one or more threads.
 	module Container
+		# A multi-thread container which uses {Thread.fork}.
 		class Threaded < Generic
+			# Indicates that this is not a multi-process container.
 			def self.multiprocess?
 				false
 			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)
 			end

data/lib/async/container/version.rb

@@ -22,6 +22,6 @@
 
 module Async
 	module Container
-		VERSION = "0.16.6"
+		VERSION = "0.16.7"
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.16.6
+  version: 0.16.7
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-06 00:00:00.000000000 Z
+date: 2020-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -161,7 +161,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="