async 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6eb0c5b8b5f8a6b2a05ce7c6a563d7deacb8a3ce0da0f0a7797ecc8080790b4
-  data.tar.gz: b0028ef539d8d11026bad3cc476b4fc2af5122e1ac5485888c456b9894be2084
+  metadata.gz: c4f42d14b27e2c7835cd745cae1e3fed8cea3ab36e4e919676b38673fc8adf32
+  data.tar.gz: 8944fd0464f0f1ef8135440bf4caa5a0235a0ef03de5e115609794c2a880ef76
 SHA512:
-  metadata.gz: bb55a40ee7d6de6c8ed5d32af4ce29c2e8e8395d9cdec05c6a4d8328cb5fe6794e30d743132967a7b5c985b312a8e0ae5daee54ff6766912f2ebfc218f1119ce
-  data.tar.gz: 9b767f9dff4254c65377ffcef840082a3e31dce20d8abdfe85c0aed0e7e3ddce7819fd30eaec0623e7428e51528694dc9208597fc416b79f3b9146357d9a72f9
+  metadata.gz: 3843d40191f22c646adfd596bb0360431dcca7152127fb90154932b430d2cbcee4e6a6479b804b34ebceef0b92535bf46d7c856a0c3aed6c3b9843c5973c2a09
+  data.tar.gz: cc595c9163bf0819bdb5f2029685bc4839faa569f88cb6cb969662d89732f2a0c25da0f7b78f297eb061e4c54d68e50ae6a5ed079a13a781f846cfee47edcea6

data/Gemfile

@@ -1,6 +1,5 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in utopia.gemspec
 gemspec
 
 group :development do

data/Rakefile

@@ -3,7 +3,7 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:test)
 
-task :default => [:test, :external]
+task :default => :test
 
 def clone_and_test(name)
 	sh("git clone https://git@github.com/socketry/#{name}")

data/benchmark/async_vs_lightio.rb

@@ -5,39 +5,78 @@ require 'lightio'
 
 require 'benchmark/ips'
 
-def run_async(count = 10000)
+#
+# It's hard to know exactly how to interpret these results. When running parallel
+# instances, resource contention is more likely to be a problem, and yet with
+# async, the performance between a single task and several tasks is roughly the
+# same, while in the case of lightio, there is an obvious performance gap.
+# 
+# The main takeaway is that contention causes issues and if systems are not
+# designed with that in mind, it will impact performance.
+#
+# $ ruby async_vs_lightio.rb
+# Warming up --------------------------------------
+# lightio (synchronous)
+#                          2.439k i/100ms
+#  async (synchronous)     2.115k i/100ms
+#   lightio (parallel)   211.000  i/100ms
+#     async (parallel)   449.000  i/100ms
+# Calculating -------------------------------------
+# lightio (synchronous)
+#                          64.502k (± 3.9%) i/s -    643.896k in  10.002151s
+#  async (synchronous)    161.195k (± 1.6%) i/s -      1.612M in  10.000976s
+#   lightio (parallel)     49.827k (±17.5%) i/s -    477.704k in   9.999579s
+#     async (parallel)    166.862k (± 6.2%) i/s -      1.662M in  10.000365s
+# 
+# Comparison:
+#     async (parallel):   166862.3 i/s
+#  async (synchronous):   161194.6 i/s - same-ish: difference falls within error
+# lightio (synchronous):   64502.5 i/s - 2.59x  slower
+#   lightio (parallel):    49827.3 i/s - 3.35x  slower
+
+
+DURATION = 0.000001
+
+def run_async(count, repeats = 10000)
 	Async::Reactor.run do |task|
-		tasks = count.times.map do
-			# LightIO::Beam is a thread-like executor, use it instead Thread
+		count.times.map do
 			task.async do |subtask|
-				# do some io operations in beam
-				subtask.sleep(0.0001)
+				repeats.times do
+					subtask.sleep(DURATION)
+				end
 			end
-		end
-		
-		tasks.each(&:wait)
+		end.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
+def run_lightio(count, repeats = 10000)
+	count.times.map do
 		LightIO::Beam.new do
-			# do some io operations in beam
-			LightIO.sleep(0.0001)
+			repeats.times do
+				LightIO.sleep(DURATION)
+			end
 		end
-	end
-
-	beams.each(&:join)
+	end.each(&:join)
 end
 
 Benchmark.ips do |benchmark|
-	benchmark.report("lightio") do |count|
-		run_lightio(count)
+	benchmark.time = 10
+	benchmark.warmup = 2
+	
+	benchmark.report("lightio (synchronous)") do |count|
+		run_lightio(1, count)
+	end
+	
+	benchmark.report("async (synchronous)") do |count|
+		run_async(1, count)
+	end
+	
+	benchmark.report("lightio (parallel)") do |count|
+		run_lightio(32, count/32)
 	end
 	
-	benchmark.report("async") do |count|
-		run_async(count)
+	benchmark.report("async (parallel)") do |count|
+		run_async(32, count/32)
 	end
 	
 	benchmark.compare!

data/examples/fibers.rb

@@ -0,0 +1,178 @@
+
+
+require 'fiber'
+
+class IO
+	READABLE = 1
+	WRITABLE = 2
+	
+	# rb_wait_for_single_fd (int fd, int events, struct timeval *tv)
+	def self.wait(descriptor, events, duration)
+		fiber = Fiber.current
+		reactor = fiber.reactor
+		
+		monitor = reactor.add_io(fiber, descriptor, state)
+		
+		fiber.timeout(duration) do
+			result = Fiber.yield
+			raise result if result.is_a? Exception
+		end
+		
+		return result
+	ensure
+		reactor.remove_io(monitor)
+	end
+	
+	def wait_readable(duration = nil)
+		wait_any(READABLE)
+	end
+	
+	def wait_writable(duration = nil)
+		wait_any(WRITABLE)
+	end
+	
+	def wait_until(events = READABLE|WRITABLE, duration = nil)
+		IO.wait_for_io(self.fileno, events, duration)
+	end
+end
+
+class Fiber
+	# Raised when a task times out.
+	class TimeoutError < RuntimeError
+	end
+	
+	# This should be inherited by nested fibers.
+	attr :reactor
+	
+	def timeout(duration)
+		reactor = self.reactor
+		backtrace = caller
+		
+		timer = reactor.add_timer(duration) do
+			if self.alive?
+				error = Fiber::TimeoutError.new("execution expired")
+				error.set_backtrace backtrace
+				self.resume error
+			end
+		end
+		
+		yield
+	ensure
+		reactor.cancel_timer(timer)
+	end
+end
+
+# Can be standard implementation, but could also be provided by external gem/library.
+class Fiber::Reactor
+	# Add IO to the reactor. The reactor will call `fiber.resume` when the event is triggered.
+	# Returns an opaque monitor object which can be passed to `remove_io` to stop waiting for events.
+	def add_io(fiber, io, state)
+		# The motivation for add_io and remove_io is that it's how a lot of the underlying APIs work, where remove_io just takes the file descriptor.
+		# It also avoids the need for any memory allocation, and maps well to how it's typically used (i.e. in an implementation of `IO#read`).
+		# An efficient implementation might do it's job and then just:
+		return io
+	end
+	
+	def remove_io(monitor)
+	end
+	
+	# The reactor will call the block at some point after duration time has elapsed.
+	# Returns an opaque timer object which can be passed to `cancel_timer` to avoid this happening.
+	def add_timer(duration, &block)
+	end
+	
+	def cancel_timer(timer)
+	end
+	
+	# Run until idle (no registered io/timers), or duration time has passed if specified.
+	def run(duration = nil)
+	end
+	
+	# Stop the reactor as soon as possible. Can be called from another thread.
+	def stop
+	end
+	
+	def close
+		# Close the reactor so it can no longer be used.
+	end
+end
+
+# Basic non-blocking task:
+reactor = Fiber::Reactor.new
+
+# User could provide their own reactor, it might even do other things, but the basic interface above should continue to work.
+
+Fiber.new(reactor: reactor) do
+	# Blocking operations call Fiber.yield, which goes to...
+end.resume
+
+# ...here, which starts running the reactor which can also be controlled (e.g. duration, stopping)
+reactor.run
+
+# Here is a rough outline of the reactor concept implementation using NIO4R
+# Can be standard implementation, but could also be provided by external gem/library.
+class NIO::Reactor
+	def initialize
+		@selector = NIO::Selector.new
+		@timers = Timers::Group.new
+		
+		@stopped = true
+	end
+	
+	EVENTS = [
+		:r,
+		:w,
+		:rw
+	]
+	
+	def add_io(fiber, io, event)
+		monitor = @selector.register(io, EVENTS[event])
+		monitor.value = fiber
+	end
+	
+	def remove_io(monitor)
+		monitor.cancel
+	end
+	
+	# The reactor will call `fiber.resume(Fiber::TimeoutError)` at some point after duration time has elapsed.
+	# Returns an opaque timer object which can be passed to `cancel_timer` to avoid this happening.
+	def add_timer(fiber, duration)
+		@timers.after(duration, &block)
+	end
+	
+	def cancel_timer(timer)
+		timer.cancel
+	end
+	
+	# Run until idle (no registered io/timers), or duration time has passed if specified.
+	def run(duration = nil)
+		@timers.wait do |interval|
+			# - nil: no timers
+			# - -ve: timers expired already
+			# -   0: timers ready to fire
+			# - +ve: timers waiting to fire
+			interval = 0 if interval && interval < 0
+			
+			# If there is nothing to do, then finish:
+			return if @fibers.empty? && interval.nil?
+			
+			if monitors = @selector.select(interval)
+				monitors.each do |monitor|
+					if fiber = monitor.value
+						fiber.resume
+					end
+				end
+			end
+		end until @stopped
+	end
+	
+	def stop
+		@stopped = true
+		@selector.wakeup
+	end
+	
+	def close
+		@seletor.close
+	end
+end
+

data/lib/async/condition.rb

@@ -23,7 +23,7 @@ require 'forwardable'
 require_relative 'node'
 
 module Async
-	# A synchronization primative, which allows fibers to wait until a particular condition is triggered.
+	# A synchronization primative, which allows fibers to wait until a particular condition is triggered. Signalling the condition directly resumes the waiting fibers and thus blocks the caller.
 	class Condition
 		def initialize
 			@waiting = []
@@ -37,17 +37,49 @@ module Async
 			Task.yield
 		end
 		
+		# Is any fiber waiting on this notification?
+		# @return [Boolean]
+		def empty?
+			@waiting.empty?
+		end
+		
 		# Signal to a given task that it should resume operations.
 		# @param value The value to return to the waiting fibers.
 		# @see Task.yield which is responsible for handling value.
 		# @return [void]
 		def signal(value = nil)
-			# TODO: Should we hot-swap @waiting - so that tasks can wait on this condition again?
-			while task = @waiting.pop
-				task.resume(value)
+			waiting = @waiting
+			@waiting = []
+			
+			waiting.each do |fiber|
+				fiber.resume(value) if fiber.alive?
 			end
 			
 			return nil
 		end
+		
+		# Signal to a given task that it should resume operations.
+		# @return [void]
+		def resume(value = nil, task: Task.current)
+			return if @waiting.empty?
+			
+			task.reactor << Signal.new(@waiting, value)
+			
+			@waiting = []
+			
+			return nil
+		end
+		
+		Signal = Struct.new(:waiting, :value) do
+			def alive?
+				true
+			end
+			
+			def resume
+				waiting.each do |fiber|
+					fiber.resume(value) if fiber.alive?
+				end
+			end
+		end
 	end
 end

data/lib/async/notification.rb

@@ -0,0 +1,50 @@
+# Copyright, 2017, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative 'condition'
+
+module Async
+	# A synchronization primative, which allows fibers to wait until a notification is received. Does not block the task which signals the notification. Waiting tasks are resumed on next iteration of the reactor.
+	class Notification < Condition
+		# Signal to a given task that it should resume operations.
+		# @return [void]
+		def signal(value = nil, task: Task.current)
+			return if @waiting.empty?
+			
+			task.reactor << Signal.new(@waiting, value)
+			
+			@waiting = []
+			
+			return nil
+		end
+		
+		Signal = Struct.new(:waiting, :value) do
+			def alive?
+				true
+			end
+			
+			def resume
+				waiting.each do |fiber|
+					fiber.resume(value) if fiber.alive?
+				end
+			end
+		end
+	end
+end

data/lib/async/reactor.rb

@@ -64,6 +64,8 @@ module Async
 			@selector = NIO::Selector.new
 			@timers = Timers::Group.new
 			
+			@ready = []
+			
 			@stopped = true
 		end
 		
@@ -116,7 +118,19 @@ module Async
 				@selector.wakeup
 			end
 		end
-	
+		
+		# Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
+		def << fiber
+			@ready << fiber
+		end
+		
+		# Yield the current fiber and resume it on the next iteration of the event loop.
+		def yield(fiber = Fiber.current)
+			@ready << fiber
+			
+			Fiber.yield
+		end
+		
 		# Run the reactor until either all tasks complete or {#stop} is invoked.
 		# Proxies arguments to {#async} immediately before entering the loop.
 		def run(*args, &block)
@@ -137,6 +151,10 @@ module Async
 				# Async.logger.debug{"[#{self} Pre] Updating #{@children.count} children..."}
 				# As timeouts may have been updated, and caused fibers to complete, we should check this.
 				
+				@ready.each do |fiber|
+					fiber.resume if fiber.alive?
+				end; @ready.clear
+				
 				# If there is nothing to do, then finish:
 				# Async.logger.debug{"[#{self}] @children.empty? = #{@children.empty?} && interval #{interval.inspect}"}
 				return initial_task if @children.empty? && interval.nil?
@@ -178,11 +196,11 @@ module Async
 		# Put the calling fiber to sleep for a given ammount of time.
 		# @param duration [Numeric] The time in seconds, to sleep for.
 		def sleep(duration)
-			task = Fiber.current
+			fiber = Fiber.current
 			
 			timer = self.after(duration) do
-				if task.alive?
-					task.resume
+				if fiber.alive?
+					fiber.resume
 				end
 			end
 			

data/lib/async/version.rb

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

data/spec/async/condition_examples.rb

@@ -0,0 +1,53 @@
+# Copyright, 2018, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+RSpec.shared_examples Async::Condition do
+	it 'can signal waiting task' do
+		state = nil
+		
+		task = reactor.async do
+			state = :waiting
+			subject.wait
+			state = :resumed
+		end
+		
+		expect(state).to be == :waiting
+		
+		subject.signal
+		
+		reactor.yield
+		
+		expect(state).to be == :resumed
+	end
+	
+	it 'should be able to signal stopped task' do
+		expect(subject.empty?).to be_truthy
+		
+		task = reactor.async do
+			subject.wait
+		end
+		
+		expect(subject.empty?).to be_falsey
+		
+		task.stop
+		
+		subject.signal
+	end
+end

data/spec/async/condition_spec.rb

@@ -20,6 +20,8 @@
 
 require 'async/condition'
 
+require_relative 'condition_examples'
+
 RSpec.describe Async::Condition do
 	include_context Async::RSpec::Reactor
 	
@@ -38,4 +40,6 @@ RSpec.describe Async::Condition do
 		
 		task.stop
 	end
+	
+	it_behaves_like Async::Condition
 end

data/spec/async/notification_spec.rb

@@ -0,0 +1,63 @@
+# Copyright, 2017, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'async/notification'
+
+require_relative 'condition_examples'
+
+RSpec.describe Async::Notification do
+	include_context Async::RSpec::Reactor
+	
+	it 'should continue after notification is signalled' do
+		sequence = []
+		
+		task = reactor.async do
+			sequence << :waiting
+			subject.wait
+			sequence << :resumed
+		end
+		
+		expect(task.status).to be :running
+		
+		sequence << :running
+		# This will cause the task to exit:
+		subject.signal
+		sequence << :signalled
+		
+		expect(task.status).to be :running
+		
+		sequence << :yielding
+		reactor.yield
+		sequence << :finished
+		
+		expect(task.status).to be :complete
+		
+		expect(sequence).to be == [
+			:waiting,
+			:running,
+			:signalled,
+			:yielding,
+			:resumed,
+			:finished
+		]
+	end
+	
+	it_behaves_like Async::Condition
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-16 00:00:00.000000000 Z
+date: 2018-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nio4r
@@ -115,12 +115,14 @@ files:
 - async.gemspec
 - benchmark/async_vs_lightio.rb
 - examples/async_method.rb
+- examples/fibers.rb
 - examples/sleep_sort.rb
 - lib/async.rb
 - lib/async/condition.rb
 - lib/async/logger.rb
 - lib/async/measure.rb
 - lib/async/node.rb
+- lib/async/notification.rb
 - lib/async/reactor.rb
 - lib/async/task.rb
 - lib/async/version.rb
@@ -129,8 +131,10 @@ files:
 - logo.svg
 - papers/1982 Grossman.pdf
 - papers/1987 ODell.pdf
+- spec/async/condition_examples.rb
 - spec/async/condition_spec.rb
 - spec/async/node_spec.rb
+- spec/async/notification_spec.rb
 - spec/async/performance_spec.rb
 - spec/async/reactor/nested_spec.rb
 - spec/async/reactor_spec.rb
@@ -162,8 +166,10 @@ signing_key:
 specification_version: 4
 summary: Async is an asynchronous I/O framework based on nio4r.
 test_files:
+- spec/async/condition_examples.rb
 - spec/async/condition_spec.rb
 - spec/async/node_spec.rb
+- spec/async/notification_spec.rb
 - spec/async/performance_spec.rb
 - spec/async/reactor/nested_spec.rb
 - spec/async/reactor_spec.rb