async-container 0.16.4 → 0.16.9

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,27 @@
 # 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 +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)
 					
@@ -56,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
@@ -90,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()
 				
@@ -115,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
@@ -134,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
@@ -151,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
@@ -167,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.4"
+		VERSION = "0.16.9"
 	end
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: async-container
 version: !ruby/object:Gem::Version
-  version: 0.16.4
+  version: 0.16.9
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-03-25 00:00:00.000000000 Z
+date: 2021-05-07 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,51 +121,27 @@ 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/dots.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/signal_spec.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:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.3
+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/dots.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/signal_spec.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: []

data/.editorconfig

@@ -1,6 +0,0 @@
-root = true
-
-[*]
-indent_style = tab
-indent_size = 2
-

data/.github/workflows/development.yml

@@ -1,36 +0,0 @@
-name: Development
-
-on: [push]
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        os:
-          - ubuntu
-          - macos
-        
-        ruby:
-          - 2.4
-          - 2.5
-          - 2.6
-          - 2.7
-        
-        include:
-          - os: 'ubuntu'
-            ruby: '2.6'
-            env: COVERAGE=PartialSummary,Coveralls
-    
-    runs-on: ${{matrix.os}}-latest
-    
-    steps:
-    - uses: actions/checkout@v1
-    - uses: actions/setup-ruby@v1
-      with:
-        ruby-version: ${{matrix.ruby}}
-    - name: Install dependencies
-      run: |
-        command -v bundler || gem install bundler
-        bundle install
-    - name: Run tests
-      run: ${{matrix.env}} bundle exec rspec

data/.gitignore

@@ -1,21 +0,0 @@
-*.gem
-*.rbc
-.bundle
-.config
-.yardoc
-Gemfile.lock
-InstalledFiles
-_yardoc
-coverage
-doc/
-lib/bundler/man
-pkg
-rdoc
-spec/reports
-test/tmp
-test/version_tmp
-tmp
-.tags*
-documentation/run/*
-documentation/public/code/*
-.rspec_status