async 1.24.2 → 1.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1abae91f943de66c2b76625d034a0b0a16beefbfa1b5d02f920e3b8fe4ee56b0
-  data.tar.gz: 62947ba422281ad590acba11610f4216e9b79c51bcad87407e4aa11fd602e218
+  metadata.gz: 0e483e124943c2ca198118249cfd157307afd86a6e9ead4b376be27ffc95b645
+  data.tar.gz: c460b159f280389b26237c41fd20bac56d9e5b2c525f884402f6170b85fd5053
 SHA512:
-  metadata.gz: de5796a4402ea91aa31dfb5fa24f634cc86855687650d9faa1b088696325d5c807837d981e063dd0b2e5ff1111d763153a9477bc717411afe402217d9ac3cc0e
-  data.tar.gz: cfeca12657ffb34219edd03ce2f1fd335c45fdbd3a661caca5db6972649304b8179850cf2fbe6ce23efa5f8abfd730259cc80dcfb0a4f29c35bd334db0be23a9
+  metadata.gz: 482ff867811aa68736b37a50d83e5850f4a1f9a310274b8993898c5577136e7502f5c369a3c9bf4685380b88a71de2ff4ed04fbd92115e8918472522e92786ea
+  data.tar.gz: 37584a2af7140b2a4efa0fb60879e97ddae99879f97b137add7fb62662139300e280a9126cf24f559172ecb7ba1f2a6c21eb77adc317df9ae54f9ddb8378f928

data/.github/workflows/development.yml

@@ -0,0 +1,55 @@
+name: Development
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{matrix.os}}-latest
+    continue-on-error: ${{matrix.experimental}}
+    
+    strategy:
+      matrix:
+        experimental: [false]
+        
+        os:
+          - ubuntu
+          - macos
+        
+        ruby:
+          - 2.5
+          - 2.6
+          - 2.7
+        
+        include:
+          - experimental: true
+            os: ubuntu
+            ruby: truffleruby
+            env: JRUBY_OPTS="--debug -X+O"
+          - experimental: true
+            os: ubuntu
+            ruby: jruby
+          - experimental: true
+            os: ubuntu
+            ruby: head
+          - experimental: true
+            os: ubuntu
+            ruby: 2.6
+            env: COVERAGE=PartialSummary,Coveralls
+    
+    steps:
+    - uses: actions/checkout@v1
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{matrix.ruby}}
+    
+    - name: Install dependencies
+      run: ${{matrix.env}} bundle install
+    
+    - name: Run tests
+      timeout-minutes: 5
+      run: ${{matrix.env}} bundle exec rspec
+    
+    - name: Run external tests
+      timeout-minutes: 5
+      if: matrix.experimental == false && matrix.os == 'ubuntu'
+      run: ${{matrix.env}} bundle exec bake external

data/README.md

@@ -5,7 +5,7 @@ Async is a composable asynchronous I/O framework for Ruby based on [nio4r] and [
 [timers]: https://github.com/socketry/timers
 [nio4r]: https://github.com/socketry/nio4r
 
-[![Build Status](https://travis-ci.com/socketry/async.svg?branch=master)](https://travis-ci.com/socketry/async)
+[![Actions Status](https://github.com/socketry/async/workflows/Development/badge.svg)](https://github.com/socketry/async/actions?workflow=Development)
 [![Code Climate](https://codeclimate.com/github/socketry/async.svg)](https://codeclimate.com/github/socketry/async)
 [![Coverage Status](https://coveralls.io/repos/socketry/async/badge.svg)](https://coveralls.io/r/socketry/async)
 [![Gitter](https://badges.gitter.im/join.svg)](https://gitter.im/socketry/async)

data/Rakefile

@@ -15,6 +15,8 @@ def clone_and_test(name)
 	sh("git clone https://git@github.com/socketry/#{name} #{path}")
 	
 	# I tried using `bundle config --local local.async ../` but it simply doesn't work.
+	# system("bundle", "config", "--local", "local.async", __dir__, chdir: path)
+	
 	File.open("#{path}/Gemfile", "a") do |file| 
 		file.puts('gem "async", path: "../../"')
 	end

data/async.gemspec

@@ -2,25 +2,24 @@
 require_relative 'lib/async/version'
 
 Gem::Specification.new do |spec|
-	spec.name          = "async"
-	spec.version       = Async::VERSION
-	spec.authors       = ["Samuel Williams"]
-	spec.email         = ["samuel.williams@oriontransfer.co.nz"]
-	spec.description   = <<-EOF
-		Async provides a modern asynchronous I/O framework for Ruby, based
-		on nio4r. It implements the reactor pattern, providing both IO and timer
-		based events.
+	spec.name = "async"
+	spec.version = Async::VERSION
+	spec.authors = ["Samuel Williams"]
+	spec.email = ["samuel.williams@oriontransfer.co.nz"]
+	spec.description = <<-EOF
+		Async is a modern concurrency framework for Ruby. It implements the
+		reactor pattern, providing both non-blocking I/O and timer events.
 	EOF
-	spec.summary       = "Async is an asynchronous I/O framework based on nio4r."
-	spec.homepage      = "https://github.com/socketry/async"
-	spec.license       = "MIT"
-
-	spec.files         = `git ls-files`.split($/)
-	spec.executables   = spec.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
-	spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+	spec.summary = "Async is an concurrency framework based for Ruby."
+	spec.homepage = "https://github.com/socketry/async"
+	spec.license = "MIT"
+	
+	spec.files = `git ls-files`.split($/)
+	spec.executables = spec.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+	spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
 	spec.require_paths = ["lib"]
 	
-	spec.required_ruby_version = ">= 2.2.7"
+	spec.required_ruby_version = ">= 2.5.0"
 	
 	spec.add_runtime_dependency "nio4r", "~> 2.3"
 	spec.add_runtime_dependency "timers", "~> 4.1"
@@ -29,8 +28,7 @@ Gem::Specification.new do |spec|
 	spec.add_development_dependency "async-rspec", "~> 1.1"
 	
 	spec.add_development_dependency "covered", "~> 0.10"
-	
 	spec.add_development_dependency "bundler"
 	spec.add_development_dependency "rspec", "~> 3.6"
-	spec.add_development_dependency "rake"
+	spec.add_development_dependency "bake-bundler"
 end

data/bake.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+def external
+	require 'bundler'
+	
+	Bundler.with_clean_env do
+		clone_and_test("async-io")
+		clone_and_test("async-websocket")
+		clone_and_test("async-dns")
+		clone_and_test("async-http")
+		clone_and_test("falcon")
+		clone_and_test("async-rest")
+	end
+end
+
+private
+
+def clone_and_test(name)
+	path = "external/#{name}"
+	FileUtils.rm_rf path
+	FileUtils.mkdir_p path
+	
+	system("git clone https://git@github.com/socketry/#{name} #{path}")
+	
+	# I tried using `bundle config --local local.async ../` but it simply doesn't work.
+	# system("bundle", "config", "--local", "local.async", __dir__, chdir: path)
+	
+	File.open("#{path}/Gemfile", "a") do |file| 
+		file.puts('gem "async", path: "../../"')
+	end
+	
+	system("cd #{path} && bundle install && bundle exec rspec")
+end

data/lib/async.rb

@@ -25,10 +25,11 @@ require_relative "async/logger"
 require_relative "async/reactor"
 
 require_relative "kernel/async"
+require_relative "kernel/sync"
 
 module Async
 	# Invoke `Reactor.run` with all arguments/block.
 	def self.run(*arguments, &block)
 		Reactor.run(*arguments, &block)
 	end
-end
+end

data/lib/async/node.rb

@@ -27,13 +27,18 @@ module Async
 	class Node
 		# Create a new node in the tree.
 		# @param parent [Node, nil] This node will attach to the given parent.
-		def initialize(parent = nil)
+		def initialize(parent = nil, annotation: nil, transient: false)
 			@children = nil
 			@parent = nil
 			
-			@annotation = nil
+			# The number of transient children:
+			@transients = 0
+			
+			@annotation = annotation
 			@object_name = nil
 			
+			@transient = transient
+			
 			if parent
 				self.parent = parent
 			end
@@ -48,6 +53,16 @@ module Async
 		# A useful identifier for the current node.
 		attr :annotation
 		
+		# Is this node transient?
+		def transient?
+			@transient
+		end
+		
+		# Does this node have (direct) transient children?
+		def transients?
+			@transients > 0
+		end
+		
 		def annotate(annotation)
 			if block_given?
 				previous_annotation = @annotation
@@ -60,7 +75,7 @@ module Async
 		end
 		
 		def description
-			@object_name ||= "#{self.class}:0x#{object_id.to_s(16)}"
+			@object_name ||= "#{self.class}:0x#{object_id.to_s(16)}#{@transient ? ' transient' : nil}"
 			
 			if @annotation
 				"#{@object_name} #{@annotation}"
@@ -73,10 +88,6 @@ module Async
 			"\#<#{description}>"
 		end
 		
-		def inspect
-			to_s
-		end
-		
 		# Change the parent of this node.
 		# @param parent [Node, nil] the parent to attach to, or nil to detach.
 		# @return [self]
@@ -96,23 +107,36 @@ module Async
 			return self
 		end
 		
+		protected def set_parent parent
+			@parent = parent
+		end
+		
 		protected def add_child child
 			@children ||= Set.new
 			@children << child
+			
+			if child.transient?
+				@transients += 1
+			end
 		end
 		
 		# Whether the node can be consumed safely. By default, checks if the
 		# children set is empty.
 		# @return [Boolean]
 		def finished?
-			@children.nil? or @children.empty?
+			@children.nil? || @children.empty? || (@children.size == @transients)
 		end
 		
 		# If the node has a parent, and is {finished?}, then remove this node from
 		# the parent.
 		def consume
-			if @parent and finished?
+			if @parent && finished?
 				@parent.reap(self)
+				
+				# After reaping self, children are all moved elsewhere.
+				@children = nil
+				@transients = 0
+				
 				@parent.consume
 				@parent = nil
 			end
@@ -122,6 +146,19 @@ module Async
 		# @param child [Node]
 		def reap(child)
 			@children.delete(child)
+			
+			if child.transient?
+				@transients -= 1
+			end
+			
+			child.children&.each do |grand_child|
+				if grand_child.finished?
+					grand_child.set_parent(nil)
+				else
+					grand_child.set_parent(self)
+					add_child(grand_child)
+				end
+			end
 		end
 		
 		# Traverse the tree.

data/lib/async/reactor.rb

@@ -164,7 +164,7 @@ module Async
 		# @param timeout [Float | nil] the maximum timeout, or if nil, indefinite.
 		# @return [Boolean] whether there is more work to do.
 		def run_once(timeout = nil)
-			logger.debug(self) {"@ready = #{@ready} @running = #{@running}"}
+			# logger.debug(self) {"@ready = #{@ready} @running = #{@running}"}
 			
 			if @ready.any?
 				# running used to correctly answer on `finished?`, and to reuse Array object.
@@ -184,13 +184,13 @@ module Async
 				interval = 0
 			end
 			
+			# If we are finished, we stop the task tree and exit:
+			if self.finished?
+				return false
+			end
+			
 			# If there is no interval to wait (thus no timers), and no tasks, we could be done:
 			if interval.nil?
-				if self.finished?
-					# If there is nothing to do, then finish:
-					return false
-				end
-				
 				# Allow the user to specify a maximum interval if we would otherwise be sleeping indefinitely:
 				interval = timeout
 			elsif interval < 0
@@ -200,7 +200,7 @@ module Async
 				interval = timeout
 			end
 			
-			logger.debug(self) {"Selecting with #{@children&.size} children with interval = #{interval ? interval.round(2) : 'infinite'}..."}
+			# logger.debug(self) {"Selecting with #{@children&.size} children with interval = #{interval ? interval.round(2) : 'infinite'}..."}
 			if monitors = @selector.select(interval)
 				monitors.each do |monitor|
 					monitor.value.resume
@@ -215,11 +215,10 @@ module Async
 					@interrupted = false
 				end
 				
-				self.stop
-				
 				return false
 			end
 			
+			# The reactor still has work to do:
 			return true
 		end
 		
@@ -244,9 +243,9 @@ module Async
 		# 
 		# @return [void]
 		def close
+			# This is a critical step. Because tasks could be stored as instance variables, and since the reactor is (probably) going out of scope, we need to ensure they are stopped. Otherwise, the tasks will belong to a reactor that will never run again and are not stopped.
 			self.stop
 			
-			# TODO Should we also clear all timers?
 			@selector.close
 			@selector = nil
 		end

data/lib/async/task.rb

@@ -72,8 +72,8 @@ module Async
 		# Create a new task.
 		# @param reactor [Async::Reactor] the reactor this task will run within.
 		# @param parent [Async::Task] the parent task.
-		def initialize(reactor, parent = Task.current?, logger: nil, &block)
-			super(parent || reactor)
+		def initialize(reactor, parent = Task.current?, logger: nil, **options, &block)
+			super(parent || reactor, **options)
 			
 			@reactor = reactor
 			

data/lib/async/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module Async
-	VERSION = "1.24.2"
+	VERSION = "1.25.0"
 end

data/lib/kernel/sync.rb

@@ -26,7 +26,7 @@ module Kernel
 	# Run the given block of code synchronously, but within a reactor if not already in one.
 	def Sync(&block)
 		if task = ::Async::Task.current?
-			yield
+			yield task
 		else
 			::Async::Reactor.run(&block).wait
 		end

data/spec/async/barrier_spec.rb

@@ -55,7 +55,7 @@ RSpec.describe Async::Barrier do
 			
 			duration = Async::Clock.measure{subject.wait}
 			
-			expect(duration).to be < (delay * 2)
+			expect(duration).to be < (delay * 2 * Q)
 			expect(finished).to be == repeats
 			expect(subject).to be_empty
 		end

data/spec/async/clock_spec.rb

@@ -28,7 +28,7 @@ RSpec.describe Async::Clock do
 			sleep 0.1
 		end
 		
-		expect(duration).to be_within(0.01).of(0.1)
+		expect(duration).to be_within(0.01 * Q).of(0.1)
 	end
 	
 	it "can get current offset" do

data/spec/async/node_spec.rb

@@ -20,7 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'benchmark'
+require 'async/node'
 
 RSpec.describe Async::Node do
 	describe '#parent=' do
@@ -95,4 +95,81 @@ RSpec.describe Async::Node do
 			expect(subject.annotation).to be == annotation
 		end
 	end
+	
+	describe '#transient' do
+		it 'can move transient child to parent' do
+			# This example represents a persistent web connection (middle) with a background reader (child). We look at how when that connection goes out of scope, what happens to the child.
+			
+			# subject -> middle -> child (transient)
+			
+			middle = Async::Node.new(subject)
+			child = Async::Node.new(middle, transient: true)
+			
+			expect(child).to be_transient
+			expect(middle).to be_finished
+			
+			allow(child).to receive(:finished?).and_return(false)
+			
+			middle.consume
+			
+			# subject -> child (transient)
+			expect(child.parent).to be subject
+			expect(subject.children).to include(child)
+			expect(subject.children).to_not include(middle)
+			
+			expect(child).to_not be_finished
+			expect(subject).to be_finished
+			
+			expect(child).to receive(:stop)
+			subject.stop
+		end
+		
+		it 'can move transient sibling to parent' do
+			# This example represents a server task (middle) which has a single task listening on incoming connections (child2), and a transient task which is monitoring those connections/some shared resource (child1). We look at what happens when the server listener finishes.
+			
+			# subject -> middle -> child1 (transient)
+			#                   -> child2
+			middle = Async::Node.new(subject)
+			child1 = Async::Node.new(middle, transient: true)
+			child2 = Async::Node.new(middle)
+			
+			allow(child1).to receive(:finished?).and_return(false)
+			
+			middle.consume
+			
+			# subject -> middle -> child1 (transient)
+			#                   -> child2
+			expect(child1.parent).to be middle
+			expect(child2.parent).to be middle
+			expect(middle.parent).to be subject
+			expect(subject.children).to include(middle)
+			expect(middle.children).to include(child1)
+			expect(middle.children).to include(child2)
+			
+			child2.consume
+			
+			# subject -> child1 (transient)
+			expect(child1.parent).to be subject
+			expect(child2.parent).to be_nil
+			expect(middle.parent).to be_nil
+			expect(subject.children).to include(child1)
+			expect(middle.children).to be_nil
+		end
+		
+		it 'ignores non-transient children of transient parent' do
+			# subject -> middle (transient) -> child
+			middle = Async::Node.new(subject, transient: true)
+			child = Async::Node.new(middle)
+			
+			allow(middle).to receive(:finished?).and_return(false)
+			
+			child.consume
+			
+			# subject -> middle (transient)
+			expect(child.parent).to be_nil
+			expect(middle.parent).to be subject
+			expect(subject.children).to include(middle)
+			expect(middle.children).to be_empty
+		end
+	end
 end

data/spec/async/task_spec.rb

@@ -58,7 +58,7 @@ RSpec.describe Async::Task do
 			
 			expect(parent).to_not be_nil
 			expect(child).to_not be_nil
-			expect(child.parent).to be parent
+			expect(child.parent).to_not be_nil
 		end
 		
 		it "can pass in arguments" do
@@ -69,6 +69,12 @@ RSpec.describe Async::Task do
 			end.wait
 		end
 		
+		it "can set initial annotation" do
+			reactor.async(annotation: "Hello World") do |task|
+				expect(task.annotation).to be == "Hello World"
+			end.wait
+		end
+		
 		it "can raise exceptions" do
 			expect do
 				reactor.async do |task|
@@ -316,11 +322,11 @@ RSpec.describe Async::Task do
 				task.with_timeout(0.2) do |timer|
 					task.sleep(0.1)
 					
-					expect(timer.fires_in).to be_within(10).percent_of(0.1)
+					expect(timer.fires_in).to be_within(10 * Q).percent_of(0.1)
 					
 					timer.reset
 					
-					expect(timer.fires_in).to be_within(10).percent_of(0.2)
+					expect(timer.fires_in).to be_within(10 * Q).percent_of(0.2)
 				end
 			end
 			

data/spec/kernel/sync_spec.rb

@@ -20,6 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'kernel/async'
 require 'kernel/sync'
 
 RSpec.describe Kernel do
@@ -27,8 +28,9 @@ RSpec.describe Kernel do
 		let(:value) {10}
 		
 		it "can run a synchronous task" do
-			result = Sync do
+			result = Sync do |task|
 				expect(Async::Task.current).to_not be nil
+				expect(Async::Task.current).to be task
 				
 				next value
 			end
@@ -38,9 +40,10 @@ RSpec.describe Kernel do
 		
 		it "can run inside reactor" do
 			Async do |task|
-				result = Sync do
+				result = Sync do |sync_task|
 					expect(Async::Task.current).to be task
-					
+					expect(sync_task).to be task
+
 					next value
 				end
 				

data/spec/spec_helper.rb

@@ -2,6 +2,12 @@
 
 require "covered/rspec"
 
+if RUBY_PLATFORM =~ /darwin/
+	Q = 10
+else
+	Q = 1
+end
+
 RSpec.configure do |config|
 	# Enable flags like --only-failures and --next-failure
 	config.example_status_persistence_file_path = ".rspec_status"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.24.2
+  version: 1.25.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-02-01 00:00:00.000000000 Z
+date: 2020-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nio4r
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.6'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: bake-bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -122,9 +122,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: "\t\tAsync provides a modern asynchronous I/O framework for Ruby, based\n\t\ton
-  nio4r. It implements the reactor pattern, providing both IO and timer\n\t\tbased
-  events.\n"
+description: "\t\tAsync is a modern concurrency framework for Ruby. It implements
+  the\n\t\treactor pattern, providing both non-blocking I/O and timer events.\n"
 email:
 - samuel.williams@oriontransfer.co.nz
 executables: []
@@ -132,16 +131,16 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
-- ".github/workflows/tests.yml"
+- ".github/workflows/development.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
 - ".yardopts"
 - Gemfile
 - Guardfile
 - README.md
 - Rakefile
 - async.gemspec
+- bake.rb
 - benchmark/async_vs_lightio.rb
 - benchmark/fiber_count.rb
 - benchmark/rubies/README.md
@@ -211,7 +210,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.7
+      version: 2.5.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -221,7 +220,7 @@ requirements: []
 rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Async is an asynchronous I/O framework based on nio4r.
+summary: Async is an concurrency framework based for Ruby.
 test_files:
 - spec/async/barrier_spec.rb
 - spec/async/chainable_async_examples.rb

data/.github/workflows/tests.yml

@@ -1,37 +0,0 @@
-name: Tests
-
-on: [push]
-
-jobs:
-  build:
-    strategy:
-      matrix:
-        os: 
-          - ubuntu
-          # - macos
-        
-        ruby: 
-          - 2.4
-          - 2.5
-          - 2.6
-        
-        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: |
-        gem install bundler
-        bundle install
-    - name: Run tests
-      run: ${{matrix.env}} bundle exec rspec
-    - name: Run external tests
-      run: bundle exec rake external

data/.travis.yml

@@ -1,35 +0,0 @@
-language: ruby
-dist: xenial
-cache: bundler
-
-addons:
-  apt:
-    packages:
-    - bind9
-
-before_script:
-  - sudo sh -c 'echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6'
-
-after_success:
-  - unset COVERAGE
-  - bundle exec rake external
-
-matrix:
-  include:
-    - rvm: 2.3
-    - rvm: 2.4
-    - rvm: 2.5
-    - rvm: 2.6
-    - rvm: 2.7
-    - rvm: 2.6
-      gemfile: gems/event.gemfile
-    - rvm: 2.6
-      env: COVERAGE=PartialSummary,Coveralls
-    - rvm: jruby-head
-      env: JRUBY_OPTS="--debug -X+O"
-    - rvm: truffleruby
-    - rvm: ruby-head
-  allow_failures:
-    - rvm: truffleruby
-    - rvm: ruby-head
-    - rvm: jruby-head