async-container 0.16.6 → 0.16.11

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

@@ -24,18 +24,24 @@ require_relative 'channel'
 require_relative 'error'
 require_relative 'notify/pipe'
 
-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 +49,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 +66,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 +106,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 +133,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 +159,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 +180,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,9 +202,10 @@ 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}
+					Console.logger.error(self) {error}
 				end
 				
 				@status = Status.new(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.11"
 	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.11
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-06 00:00:00.000000000 Z
+date: 2021-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -52,34 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
-- !ruby/object:Gem::Dependency
-  name: bake-bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bake-modernize
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -159,16 +131,16 @@ require_paths:
 - lib
 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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: Abstract container-based parallelism using threads and processes where appropriate.