Updated implementation and documentation.

Author: ioquatix

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

lib/async/container/best.rb

@@ -25,12 +25,16 @@
 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 @@ def self.best_container_class
 			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

lib/async/container/channel.rb

@@ -24,27 +24,40 @@
 
 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

lib/async/container/controller.rb

@@ -28,24 +28,17 @@
 
 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"]
 			SIGTERM = Signal.list["TERM"]
 			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 @@ def initialize(notify: Notify.open!)
 				end
 			end
 
+			# The state of the controller.
+			# @returns [String]
 			def state_string
 				if running?
 					"running"
@@ -68,42 +63,61 @@ def state_string
 				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 @@ def restart
 				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 @@ def restart
 
 					container.stop
 
-					raise InitializationError, container
+					raise SetupError, container
 				end
 
 				# Make this swap as atomic as possible:
@@ -150,6 +164,7 @@ def restart
 				raise
 			end
 
+			# Reload the existing container. Children instances will be reloaded using `SIGHUP`.
 			def reload
 				@notify&.reloading!
 
@@ -158,7 +173,7 @@ def reload
 				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 @@ def reload
 				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 @@ def run
 						if handler = @signals[exception.signo]
 							begin
 								handler.call
-							rescue InitializationError => error
+							rescue SetupError => error
 								Async.logger.error(self) {error}
 							end
 						else

lib/async/container/error.rb

@@ -27,12 +27,25 @@ class Error < StandardError
 
 		Interrupt = ::Interrupt
 
+		# Similar to {Interrupt}, but represents `SIGTERM`.
 		class Terminate < SignalException
 			SIGTERM = Signal.list['TERM']
 
 			def initialize
 				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

lib/async/container/forked.rb

@@ -24,13 +24,17 @@
 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