async-container 0.16.4 → 0.16.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5d86c65b350b653e621c4f36e8005fc85ba7c6a97569784dc2d5170d1310a27
-  data.tar.gz: 708b959103791bb424fae6c8f32e8a213dc04986c4e33e498069ebcd08b12473
+  metadata.gz: a76bd927dba80c9eb45b6e0c4ba41c463bfcbe1ffa90ff00b1cef7375e522670
+  data.tar.gz: 41aa83bb3be7be3ab3cdd8f2f7065a4960b800acdd39d5c89f2c420d70cc312b
 SHA512:
-  metadata.gz: 5b216348b1514841d813e1455565b41e108a9c284e2b26e2629d8a8cf26acf7c5952bc0e63a2a84ab2c144b6a4c462cbdb1e1b54255ed1ecdbc4107a92d0e66b
-  data.tar.gz: f0afa2fcb3cd7ee73dd67cc92d0b004bc7b467cef2b7f4753ddbd296316d6364e81f7edd22987887957e14fe5bb0971370263e84731b7ebb181a109e635ea5e1
+  metadata.gz: 2c7878995dea584f4c5284214a5d96074ada191a2d54d07cc7f1dc6815e03edbc60ff729bc5f377c11a1ed00f531019aabefe89b13f04e7d305edcd6110a6770
+  data.tar.gz: ac4e0f6e39e315311283a71a8a24cfc64980c352c21bdc0a33fdcfd4217d4564b72229450583000263b814a668bbb1ae81cfa3c420e001ec042da58ccf650d75

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
 				
@@ -55,9 +48,13 @@ module Async
 				
 				@signals = {}
 				
-				trap(SIGHUP, &self.method(:restart))
+				trap(SIGHUP) do
+					self.restart
+				end
 			end
 			
+			# The state of the controller.
+			# @returns [String]
 			def state_string
 				if running?
 					"running"
@@ -66,49 +63,68 @@ 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!
 					
-					Async.logger.debug(self) {"Restarting container..."}
+					Console.logger.debug(self) {"Restarting container..."}
 				else
-					Async.logger.debug(self) {"Starting container..."}
+					Console.logger.debug(self) {"Starting container..."}
 				end
 				
 				container = self.create_container
@@ -118,26 +134,27 @@ module Async
 				rescue
 					@notify&.error!($!.to_s)
 					
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Wait for all child processes to enter the ready state.
-				Async.logger.debug(self, "Waiting for startup...")
+				Console.logger.debug(self, "Waiting for startup...")
 				container.wait_until_ready
-				Async.logger.debug(self, "Finished startup.")
+				Console.logger.debug(self, "Finished startup.")
 				
 				if container.failed?
 					@notify&.error!($!.to_s)
 					
 					container.stop
 					
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Make this swap as atomic as possible:
 				old_container = @container
 				@container = container
 				
+				Console.logger.debug(self, "Stopping old container...")
 				old_container&.stop
 				@notify&.ready!
 			rescue
@@ -147,31 +164,33 @@ module Async
 				raise
 			end
 			
+			# Reload the existing container. Children instances will be reloaded using `SIGHUP`.
 			def reload
 				@notify&.reloading!
 				
-				Async.logger.info(self) {"Reloading container: #{@container}..."}
+				Console.logger.info(self) {"Reloading container: #{@container}..."}
 				
 				begin
 					self.setup(@container)
 				rescue
-					raise InitializationError, container
+					raise SetupError, container
 				end
 				
 				# Wait for all child processes to enter the ready state.
-				Async.logger.debug(self, "Waiting for startup...")
+				Console.logger.debug(self, "Waiting for startup...")
 				@container.wait_until_ready
-				Async.logger.debug(self, "Finished startup.")
+				Console.logger.debug(self, "Finished startup.")
 				
 				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
@@ -182,6 +201,10 @@ module Async
 					raise Terminate
 				end
 				
+				hangup_action = Signal.trap(:HUP) do
+					raise Hangup
+				end
+				
 				self.start
 				
 				while @container&.running?
@@ -191,8 +214,8 @@ module Async
 						if handler = @signals[exception.signo]
 							begin
 								handler.call
-							rescue InitializationError => error
-								Async.logger.error(self) {error}
+							rescue SetupError => error
+								Console.logger.error(self) {error}
 							end
 						else
 							raise
@@ -209,6 +232,7 @@ module Async
 				# Restore the interrupt handler:
 				Signal.trap(:INT, interrupt_action)
 				Signal.trap(:TERM, terminate_action)
+				Signal.trap(:HUP, hangup_action)
 			end
 		end
 	end

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,25 @@ module Async
 				super(SIGTERM)
 			end
 		end
+		
+		class Hangup < SignalException
+			SIGHUP = Signal.list['HUP']
+			
+			def initialize
+				super(SIGHUP)
+			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,13 +30,25 @@ require_relative 'statistics'
 
 module Async
 	module Container
-		# @return [Integer] the number of hardware processors which can run threads/processes simultaneously.
-		def self.processor_count
-			Etc.nprocessors
-		rescue
-			2
+		# 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.
+		# @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
+			end.to_i
+			
+			if count < 1
+				raise RuntimeError, "Invalid processor count #{count}!"
+			end
+			
+			return count
 		end
 		
+		# A base class for implementing containers.
 		class Generic
 			def self.run(*arguments, **options, &block)
 				self.new.run(*arguments, **options, &block)
@@ -56,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
@@ -86,14 +106,20 @@ 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|
+					Console.logger.debug(self) do |buffer|
 						buffer.puts "Waiting for ready:"
 						@state.each do |child, state|
 							buffer.puts "\t#{child.class}: #{state.inspect}"
@@ -108,22 +134,28 @@ 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)
 				
 				if @group.running?
-					Async.logger.warn(self) {"Group is still running after stopping it!"}
+					Console.logger.warn(self) {"Group is still running after stopping it!"}
 				end
 			ensure
 				@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
 				
 				if mark?(key)
-					Async.logger.debug(self) {"Reusing existing child for #{key}: #{name}"}
+					Console.logger.debug(self) {"Reusing existing child for #{key}: #{name}"}
 					return false
 				end
 				
@@ -144,10 +176,10 @@ module Async
 						end
 						
 						if status.success?
-							Async.logger.info(self) {"#{child} exited with #{status}"}
+							Console.logger.info(self) {"#{child} exited with #{status}"}
 						else
 							@statistics.failure!
-							Async.logger.error(self) {status}
+							Console.logger.error(self) {status}
 						end
 						
 						if restart
@@ -157,18 +189,14 @@ module Async
 						end
 					end
 				# ensure
-				# 	Async.logger.error(self) {$!} if $!
+				# 	Console.logger.error(self) {$!} if $!
 				end.resume
 				
 				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)
@@ -177,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!)
 				
@@ -191,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]
@@ -203,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)