async-container 0.16.3 → 0.16.8

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

@@ -21,20 +21,29 @@
 # THE SOFTWARE.
 
 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
@@ -42,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)
 					
@@ -56,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
@@ -90,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()
 				
@@ -115,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 = name
+				@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
@@ -134,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
@@ -151,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
@@ -167,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.3"
+		VERSION = "0.16.8"
 	end
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.16.3
+  version: 0.16.8
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-18 00:00:00.000000000 Z
+date: 2020-09-19 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: process-group
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
@@ -67,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: covered
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: covered
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -108,49 +94,12 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: rake
-  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'
-description: "\t\tProvides containers for servers which provide concurrency policies,
-  e.g. threads, processes.\n"
+description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".editorconfig"
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
-- ".yardopts"
-- Gemfile
-- Guardfile
-- README.md
-- Rakefile
-- async-container.gemspec
-- examples/async.rb
-- examples/channel.rb
-- examples/channels/client.rb
-- examples/container.rb
-- examples/isolate.rb
-- examples/minimal.rb
-- examples/test.rb
-- examples/threads.rb
-- examples/title.rb
-- examples/udppipe.rb
 - lib/async/container.rb
 - lib/async/container/best.rb
 - lib/async/container/channel.rb
@@ -172,29 +121,19 @@ files:
 - lib/async/container/thread.rb
 - lib/async/container/threaded.rb
 - lib/async/container/version.rb
-- spec/async/container/controller_spec.rb
-- spec/async/container/forked_spec.rb
-- spec/async/container/hybrid_spec.rb
-- spec/async/container/notify/notify.rb
-- spec/async/container/notify/pipe_spec.rb
-- spec/async/container/notify_spec.rb
-- spec/async/container/shared_examples.rb
-- spec/async/container/threaded_spec.rb
-- spec/async/container_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/socketry/async-container
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 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:
   - - ">="
@@ -202,17 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
-summary: Async is an asynchronous I/O framework based on nio4r.
-test_files:
-- spec/async/container/controller_spec.rb
-- spec/async/container/forked_spec.rb
-- spec/async/container/hybrid_spec.rb
-- spec/async/container/notify/notify.rb
-- spec/async/container/notify/pipe_spec.rb
-- spec/async/container/notify_spec.rb
-- spec/async/container/shared_examples.rb
-- spec/async/container/threaded_spec.rb
-- spec/async/container_spec.rb
-- spec/spec_helper.rb
+summary: Abstract container-based parallelism using threads and processes where appropriate.
+test_files: []