async 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: eaeb8a35292eab6b85c49779994816e8d6355427
-  data.tar.gz: a97badcaa4eb6c8cbfa37ca4609d9f45b93b6e71
+SHA256:
+  metadata.gz: c6eb0c5b8b5f8a6b2a05ce7c6a563d7deacb8a3ce0da0f0a7797ecc8080790b4
+  data.tar.gz: b0028ef539d8d11026bad3cc476b4fc2af5122e1ac5485888c456b9894be2084
 SHA512:
-  metadata.gz: d6017907e393996093d196a36434d469acd824958d90ca560cff85ef6c1b8bfbb4e10e96c712d7542f106dcef9beb6e5aeb10d70cd9c4af9b058383b42434949
-  data.tar.gz: 7330ce6f3aa50afcba05c5ec2b90cf8c1653176104c0fdbb4c006315f9ab8409aa8a8daae00dbef0cadb6b11d5867bab7b7df250de7d966cf3b6c1e018a75cf9
+  metadata.gz: bb55a40ee7d6de6c8ed5d32af4ce29c2e8e8395d9cdec05c6a4d8328cb5fe6794e30d743132967a7b5c985b312a8e0ae5daee54ff6766912f2ebfc218f1119ce
+  data.tar.gz: 9b767f9dff4254c65377ffcef840082a3e31dce20d8abdfe85c0aed0e7e3ddce7819fd30eaec0623e7428e51528694dc9208597fc416b79f3b9146357d9a72f9

data/.travis.yml

@@ -2,14 +2,19 @@ language: ruby
 sudo: false
 dist: trusty
 cache: bundler
+addons:
+  apt:
+    packages:
+    - bind9
+
+before_script: sudo sh -c 'echo 0 > /proc/sys/net/ipv6/conf/all/disable_ipv6'
 
 matrix:
   include:
-    - rvm: 2.0
-    - rvm: 2.1
     - rvm: 2.2
     - rvm: 2.3
     - rvm: 2.4
+    - rvm: 2.5
     - rvm: jruby-head
       env: JRUBY_OPTS="--debug -X+O"
     - rvm: ruby-head

data/Rakefile

@@ -3,7 +3,27 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:test)
 
-task :default => :test
+task :default => [:test, :external]
+
+def clone_and_test(name)
+	sh("git clone https://git@github.com/socketry/#{name}")
+	
+	# I tried using `bundle config --local local.async ../` but it simply doesn't work.
+	File.open("#{name}/Gemfile", "a") do |file| 
+		file.puts('gem "async", path: "../"')
+	end
+	
+	sh("cd #{name} && bundle install && bundle exec rake test")
+end
+
+task :external do
+	Bundler.with_clean_env do
+		clone_and_test("async-io")
+		clone_and_test("async-websocket")
+		clone_and_test("async-dns")
+		clone_and_test("falcon")
+	end
+end
 
 task :coverage do
 	ENV['COVERAGE'] = 'y'

data/async.gemspec

@@ -1,4 +1,4 @@
-# -*- encoding: utf-8 -*-
+
 require_relative 'lib/async/version'
 
 Gem::Specification.new do |spec|
@@ -21,9 +21,9 @@ Gem::Specification.new do |spec|
 	spec.require_paths = ["lib"]
 	spec.has_rdoc      = "yard"
 	
-	spec.required_ruby_version = "~> 2.0"
+	spec.required_ruby_version = ">= 2.2.7"
 
-	spec.add_runtime_dependency "nio4r"
+	spec.add_runtime_dependency "nio4r", "~> 2.0"
 	spec.add_runtime_dependency "timers", "~> 4.1"
 	
 	spec.add_development_dependency "async-rspec", "~> 1.1"

data/benchmark/async_vs_lightio.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+
+require 'async'
+require 'lightio'
+
+require 'benchmark/ips'
+
+def run_async(count = 10000)
+	Async::Reactor.run do |task|
+		tasks = count.times.map do
+			# LightIO::Beam is a thread-like executor, use it instead Thread
+			task.async do |subtask|
+				# do some io operations in beam
+				subtask.sleep(0.0001)
+			end
+		end
+		
+		tasks.each(&:wait)
+	end
+end
+
+def run_lightio(count = 10000)
+	beams = count.times.map do
+		# LightIO::Beam is a thread-like executor, use it instead Thread
+		LightIO::Beam.new do
+			# do some io operations in beam
+			LightIO.sleep(0.0001)
+		end
+	end
+
+	beams.each(&:join)
+end
+
+Benchmark.ips do |benchmark|
+	benchmark.report("lightio") do |count|
+		run_lightio(count)
+	end
+	
+	benchmark.report("async") do |count|
+		run_async(count)
+	end
+	
+	benchmark.compare!
+end

data/examples/async_method.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/async'
+
+module Async::Methods
+	def sleep(*args)
+		Async::Task.current.sleep(*args)
+	end
+
+	def async(name)
+		original_method = self.method(name)
+		
+		define_method(name) do |*args|
+			Async::Reactor.run do |task|
+				original_method.call(*args)
+			end
+		end
+	end
+
+	def await(&block)
+		block.call.wait
+	end
+	
+	def barrier!
+		Async::Task.current.children.each(&:wait)
+	end
+end
+
+include Async::Methods
+
+async def count_chickens(area_name)
+	3.times do |i|
+		sleep rand
+		
+		puts "Found a chicken in the #{area_name}!"
+	end
+end
+
+async def find_chicken(areas)
+	puts "Searching for chicken..."
+	
+	sleep rand * 5
+	
+	return areas.sample
+end
+
+async def count_all_chckens
+	# These methods all run at the same time.
+	count_chickens("garden")
+	count_chickens("house")
+	count_chickens("tree")
+	
+	# Wait for all previous async work to complete...
+	barrier!
+	
+	puts "There was a chicken in the #{find_chicken(["garden", "house", "tree"]).wait}"
+end
+
+count_all_chckens

data/examples/sleep_sort.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/async'
+
+def sleep_sort(items)
+	Async::Reactor.run do |task|
+		# Where to save the sorted items:
+		sorted_items = []
+		
+		items.each do |item|
+			# Spawn an async task...
+			task.async do |nested_task|
+				# Which goes to sleep for the specified duration:
+				nested_task.sleep(item)
+				
+				# And then appends the item to the sorted array:
+				sorted_items << item
+			end
+		end
+		
+		# Wait for all children to complete.
+		task.children.each(&:wait)
+		
+		# Return the result:
+		sorted_items
+	end.wait # Wait for the entire process to complete.
+end
+
+# Calling at the top level blocks the thread:
+puts sleep_sort(5.times.collect{rand}).inspect
+
+# Calling in your own reactor allows you to control the asynchronus behaviour:
+Async::Reactor.run do |task|
+	3.times do
+		task.async do
+			puts sleep_sort(5.times.collect{rand}).inspect
+		end
+	end
+end

data/lib/async/reactor.rb

@@ -46,17 +46,15 @@ module Async
 			if current = Task.current?
 				reactor = current.reactor
 				
-				reactor.async(*args, &block)
+				return reactor.async(*args, &block)
 			else
 				reactor = self.new
 				
 				begin
-					reactor.run(*args, &block)
+					return reactor.run(*args, &block)
 				ensure
 					reactor.close
 				end
-				
-				return reactor
 			end
 		end
 		
@@ -103,7 +101,11 @@ module Async
 		end
 		
 		def register(*args)
-			@selector.register(*args)
+			monitor = @selector.register(*args)
+			
+			monitor.value = Fiber.current
+			
+			return monitor
 		end
 	
 		# Stop the reactor at the earliest convenience. Can be called from a different thread safely.
@@ -123,7 +125,7 @@ module Async
 			@stopped = false
 			
 			# Allow the user to kick of the initial async tasks.
-			async(*args, &block) if block_given?
+			initial_task = async(*args, &block) if block_given?
 			
 			@timers.wait do |interval|
 				# - nil: no timers
@@ -137,7 +139,7 @@ module Async
 				
 				# If there is nothing to do, then finish:
 				# Async.logger.debug{"[#{self}] @children.empty? = #{@children.empty?} && interval #{interval.inspect}"}
-				return if @children.empty? && interval.nil?
+				return initial_task if @children.empty? && interval.nil?
 				
 				# Async.logger.debug{"Selecting with #{@children.count} fibers interval = #{interval.inspect}..."}
 				if monitors = @selector.select(interval)
@@ -149,7 +151,7 @@ module Async
 				end
 			end until @stopped
 			
-			return self
+			return initial_task
 		ensure
 			Async.logger.debug{"[#{self} Ensure] Exiting run-loop (stopped: #{@stopped} exception: #{$!.inspect})..."}
 			@stopped = true

data/lib/async/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Async
-	VERSION = "1.2.2"
+	VERSION = "1.3.0"
 end

data/lib/async/wrapper.rb

@@ -29,16 +29,25 @@ module Async
 		def initialize(io, reactor = nil)
 			@io = io
 			
-			@reactor = reactor || Task.current.reactor
+			@reactor = reactor
 			@monitor = nil
 		end
 		
 		# The underlying native `io`.
 		attr :io
 		
-		# The reactor this wrapper is associated with.
+		# The reactor this wrapper is associated with, if any.
 		attr :reactor
 		
+		# Bind this wrapper to a different reactor. Assign nil to convert to an unbound wrapper (can be used from any reactor/task but with slightly increased overhead.)
+		# Binding to a reactor is purely a performance consideration. Generally, I don't like APIs that exist only due to optimisations. This is borderline, so consider this functionality semi-private.
+		def reactor= reactor
+			@monitor.close if @monitor
+			
+			@reactor = reactor
+			@monitor = nil
+		end
+		
 		# Wait for the io to become readable.
 		def wait_readable(duration = nil)
 			wait_any(:r, duration)
@@ -53,50 +62,46 @@ module Async
 		# @param interests [:r | :w | :rw] what events to wait for.
 		# @param duration [Float] timeout after the given duration if not `nil`.
 		def wait_any(interests = :rw, duration = nil)
-			monitor(interests, duration)
+			# There is value in caching this monitor - if you can reuse it, you will get about 2x the throughput, because you avoid calling Reactor#register and Monitor#close for every call. That being said, by caching it, you also introduce lifetime issues. I'm going to accept this overhead into the wrapper design because it's pretty convenient, but if you want faster IO, take a look at the performance spec which compares this method with a more direct alternative.
+			if @reactor
+				unless @monitor
+					@monitor = @reactor.register(@io, interests)
+				else
+					@monitor.interests = interests
+					@monitor.value = Fiber.current
+				end
+				
+				begin
+					wait_for(@reactor, @monitor, duration)
+				ensure
+					@monitor.remove_interest(@monitor.interests)
+					@monitor.value = nil
+				end
+			else
+				reactor = Task.current.reactor
+				monitor = reactor.register(@io, interests)
+				
+				begin
+					wait_for(reactor, monitor, duration)
+				ensure
+					monitor.close
+				end
+			end
 		end
 		
-		# Close the monitor.
+		# Close the io and monitor.
 		def close
-			close_monitor
+			@monitor.close if @monitor
 			
-			@io.close if @io
+			@io.close
 		end
 		
 		private
 		
-		def close_monitor
-			if @monitor
-				@monitor.close
-				@monitor = nil
-			end
-		end
-		
-		if ::NIO::VERSION >= "2.0"
-			def clear_monitor
-				if @monitor
-					# Alas, @monitor.interests = nil does not yet work.
-					@monitor.value = nil
-					@monitor.remove_interest(@monitor.interests)
-				end
-			end
-		else
-			alias clear_monitor close_monitor
-		end
-		
-		# Monitor the io for the given events
-		def monitor(interests, duration = nil)
-			unless @monitor
-				@monitor = @reactor.register(@io, interests)
-			else
-				@monitor.interests = interests
-			end
-			
-			@monitor.value = Fiber.current
-			
+		def wait_for(reactor, monitor, duration)
 			# If the user requested an explicit timeout for this operation:
 			if duration
-				@reactor.timeout(duration) do
+				reactor.timeout(duration) do
 					Task.yield
 				end
 			else
@@ -104,8 +109,6 @@ module Async
 			end
 			
 			return true
-		ensure
-			clear_monitor
 		end
 	end
 end

data/spec/async/performance_spec.rb

@@ -0,0 +1,44 @@
+
+require 'benchmark/ips'
+
+RSpec.describe Async::Wrapper do
+	let(:pipe) {IO.pipe}
+	
+	let(:input) {described_class.new(pipe.first)}
+	let(:output) {described_class.new(pipe.last)}
+		
+	it "should be fast to parse large documents" do
+		Benchmark.ips do |x|
+			x.report('Wrapper#wait_readable') do |repeats|
+				Async::Reactor.run do |task|
+					input = Async::Wrapper.new(pipe.first, task.reactor)
+					output = pipe.last
+					
+					repeats.times do
+						output.write(".")
+						input.wait_readable
+						input.io.read(1)
+					end
+				end
+			end
+			
+			x.report('Reactor#register') do |repeats|
+				Async::Reactor.run do |task|
+					input = pipe.first
+					monitor = task.reactor.register(input, :r)
+					output = pipe.last
+					
+					repeats.times do
+						output.write(".")
+						Async::Task.yield
+						input.read(1)
+					end
+					
+					monitor.close
+				end
+			end
+			
+			x.compare!
+		end
+	end
+end

data/spec/async/reactor_spec.rb

@@ -60,7 +60,10 @@ RSpec.describe Async::Reactor do
 	end
 	
 	it "is closed after running" do
-		reactor = Async::Reactor.run do
+		reactor = nil
+		
+		Async::Reactor.run do |task|
+			reactor = task.reactor
 		end
 		
 		expect(reactor).to be_closed
@@ -68,6 +71,13 @@ RSpec.describe Async::Reactor do
 		expect{reactor.run}.to raise_error(RuntimeError, /closed/)
 	end
 	
+	it "should return a task" do
+		result = Async::Reactor.run do |task|
+		end
+		
+		expect(result).to be_kind_of(Async::Task)
+	end
+	
 	describe '#async' do
 		include_context Async::RSpec::Reactor
 		

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-02 00:00:00.000000000 Z
+date: 2018-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nio4r
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: timers
   requirement: !ruby/object:Gem::Requirement
@@ -113,6 +113,9 @@ files:
 - README.md
 - Rakefile
 - async.gemspec
+- benchmark/async_vs_lightio.rb
+- examples/async_method.rb
+- examples/sleep_sort.rb
 - lib/async.rb
 - lib/async/condition.rb
 - lib/async/logger.rb
@@ -124,8 +127,11 @@ files:
 - lib/async/wrapper.rb
 - logo.png
 - logo.svg
+- papers/1982 Grossman.pdf
+- papers/1987 ODell.pdf
 - spec/async/condition_spec.rb
 - spec/async/node_spec.rb
+- spec/async/performance_spec.rb
 - spec/async/reactor/nested_spec.rb
 - spec/async/reactor_spec.rb
 - spec/async/task_spec.rb
@@ -141,9 +147,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: 2.2.7
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -151,13 +157,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Async is an asynchronous I/O framework based on nio4r.
 test_files:
 - spec/async/condition_spec.rb
 - spec/async/node_spec.rb
+- spec/async/performance_spec.rb
 - spec/async/reactor/nested_spec.rb
 - spec/async/reactor_spec.rb
 - spec/async/task_spec.rb