async 1.17.1 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9513c847ed714794e7792f205c2aa3d6ece0712f39b426246bb147f60ad21b20
-  data.tar.gz: a1382d2118fff244e3bcaa06b1bab8a2284d395304b0e85ef7a8a32c171c9915
+  metadata.gz: 36f2b61b71527d107240403ca7ec078814ed7638bd18cf6ef14b02003d6bfc5d
+  data.tar.gz: 0de32e45303f0ce6514c685169422e6cc22cc0b49a497739e183964414430f7d
 SHA512:
-  metadata.gz: 853b55599bc4c0923fdb49534f02e474ee7fa048bc29ee66b3d1fa57d7dc1d902a53b859bf1337b71b2f94fe85fa5b3e6462633f5af210178210221d3444a14d
-  data.tar.gz: '07092c2764ebdbe0fb106cefffd1bbc6e33710d17d899f64626df60601d488ca696ea6522b62740ffbd5fdd46d8f72bbca98303d041ea2ce1076be74e477de03'
+  metadata.gz: f09914dff9e1eccff8b2b6849cd111fa43a6c2db9ff1bc43db02aeb1fa82059bccef2728ec93eecc549486b00012f97268d46686aed23ad375704ec08ca54e71
+  data.tar.gz: 259262665baaee81c4ff1d056649e14e77bc891b63936eef3dbfab1124408ee8cbd9442ebbb27903430a645bbeb2b4856c7bad333375d57a51cb2608b919092a

data/.travis.yml

@@ -28,9 +28,6 @@ matrix:
       env: JRUBY_OPTS="--debug -X+O"
     - rvm: truffleruby
     - rvm: ruby-head
-    - rvm: rbx-3
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
-    - rvm: rbx-3
-    - rvm: truffleruby

data/README.md

@@ -10,7 +10,7 @@ Async is a composable asynchronous I/O framework for Ruby based on [nio4r] and [
 [![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)
 
-> "Lately I've been looking into `async`, as one of my projects – [tus-ruby-server](https://github.com/janko/tus-ruby-server) – would really benefit from `async` I/O. It's really beautifully designed." *– [janko](https://github.com/janko)*
+> "Lately I've been looking into `async`, as one of my projects – [tus-ruby-server](https://github.com/janko/tus-ruby-server) – would really benefit from non-blocking I/O. It's really beautifully designed." *– [janko](https://github.com/janko)*
 
 ## Motivation
 
@@ -47,6 +47,8 @@ Or install it yourself as:
 
 ## Usage
 
+Please [try the interactive online tutorial](https://katacoda.com/ioquatix/scenarios/async-introduction).
+
 ### Tasks
 
 An `Async::Task` runs using a `Fiber` and blocking operations e.g. `sleep`, `read`, `write` yield control until the operation can complete. There are two main methods to create tasks.

data/examples/capture/README.md

@@ -0,0 +1,59 @@
+# Capture
+
+## Falcon
+
+```
+% wrk -t 8 -c 32 http://localhost:9292/
+Running 10s test @ http://localhost:9292/
+  8 threads and 32 connections
+  Thread Stats   Avg      Stdev     Max   +/- Stdev
+    Latency   106.31ms   10.20ms 211.79ms   98.00%
+    Req/Sec    37.94      5.43    40.00     84.24%
+  3003 requests in 10.01s, 170.16KB read
+Requests/sec:    299.98
+Transfer/sec:     17.00KB
+```
+
+```
+0.0s: Process 28065 start times:
+    | #<struct Process::Tms utime=2.38, stime=0.0, cutime=0.0, cstime=0.2>
+^C15.11s: strace -p 28065
+    | ["sendto", {:"% time"=>57.34, :seconds=>0.595047, :"usecs/call"=>14, :calls=>39716, :errors=>32, :syscall=>"sendto"}]
+    | ["recvfrom", {:"% time"=>42.58, :seconds=>0.441867, :"usecs/call"=>12, :calls=>36718, :errors=>70, :syscall=>"recvfrom"}]
+    | ["read", {:"% time"=>0.07, :seconds=>0.000723, :"usecs/call"=>7, :calls=>98, :errors=>nil, :syscall=>"read"}]
+    | ["write", {:"% time"=>0.01, :seconds=>0.000112, :"usecs/call"=>56, :calls=>2, :errors=>nil, :syscall=>"write"}]
+    | [:total, {:"% time"=>100.0, :seconds=>1.037749, :"usecs/call"=>nil, :calls=>76534, :errors=>102, :syscall=>"total"}]
+15.11s: Process 28065 end times:
+    | #<struct Process::Tms utime=3.93, stime=0.0, cutime=0.0, cstime=0.2>
+15.11s: Process Waiting: 1.0377s out of 1.55s
+    | Wait percentage: 66.95%
+```
+
+## Puma
+
+```
+wrk -t 8 -c 32 http://localhost:9292/
+Running 10s test @ http://localhost:9292/
+  8 threads and 32 connections
+  Thread Stats   Avg      Stdev     Max   +/- Stdev
+    Latency   108.83ms    3.50ms 146.38ms   86.58%
+    Req/Sec    34.43      6.70    40.00     92.68%
+  1371 requests in 10.01s, 81.67KB read
+Requests/sec:    136.94
+Transfer/sec:      8.16KB
+```
+
+```
+0.0s: Process 28448 start times:
+    | #<struct Process::Tms utime=0.63, stime=0.0, cutime=0.0, cstime=0.2>
+^C24.89s: strace -p 28448
+    | ["recvfrom", {:"% time"=>64.65, :seconds=>0.595275, :"usecs/call"=>13, :calls=>44476, :errors=>27769, :syscall=>"recvfrom"}]
+    | ["sendto", {:"% time"=>30.68, :seconds=>0.282467, :"usecs/call"=>18, :calls=>15288, :errors=>nil, :syscall=>"sendto"}]
+    | ["write", {:"% time"=>4.66, :seconds=>0.042921, :"usecs/call"=>15, :calls=>2772, :errors=>nil, :syscall=>"write"}]
+    | ["read", {:"% time"=>0.02, :seconds=>0.000157, :"usecs/call"=>8, :calls=>19, :errors=>1, :syscall=>"read"}]
+    | [:total, {:"% time"=>100.0, :seconds=>0.92082, :"usecs/call"=>nil, :calls=>62555, :errors=>27770, :syscall=>"total"}]
+24.89s: Process 28448 end times:
+    | #<struct Process::Tms utime=3.19, stime=0.0, cutime=0.0, cstime=0.2>
+24.89s: Process Waiting: 0.9208s out of 2.56s
+    | Wait percentage: 35.97%
+```

data/examples/capture/capture.rb

@@ -0,0 +1,104 @@
+#!/usr/bin/env ruby
+
+require 'irb'
+require 'console'
+
+pids = ARGV.collect(&:to_i)
+
+TICKS = Process.clock_getres(:TIMES_BASED_CLOCK_PROCESS_CPUTIME_ID, :hertz).to_f
+
+def getrusage(pid)
+	fields = File.read("/proc/#{pid}/stat").split(/\s+/)
+	
+	return Process::Tms.new(
+		fields[14].to_f / TICKS,
+		fields[15].to_f / TICKS,
+		fields[16].to_f / TICKS,
+		fields[17].to_f / TICKS,
+	)
+end
+
+def parse(value)
+	case value
+	when /^\s*\d+\.\d+/
+		Float(value)
+	when /^\s*\d+/
+		Integer(value)
+	else
+		value = value.strip
+		if value.empty?
+			nil
+		else
+			value
+		end
+	end
+end
+
+def strace(pid, duration = 10)
+	input, output = IO.pipe
+	
+	pid = Process.spawn("strace", "-p", pid.to_s, "-cqf", "-w", "-e", "trace=read,write,sendto,recvfrom", err: output)
+	
+	output.close
+	
+	Signal.trap(:INT) do
+		Process.kill(:INT, pid)
+		Signal.trap(:INT, :DEFAULT)
+	end
+	
+	summary = {}
+	
+	if line = input.gets
+		rule = input.gets # horizontal separator
+		pattern = Regexp.new(
+			rule.split(/\s/).map{|s| "(.{1,#{s.size}})"}.join(' ')
+		)
+		
+		header = pattern.match(line).captures.map{|key| key.strip.to_sym}
+		
+		while line = input.gets
+			break if line == rule
+			row = pattern.match(line).captures.map{|value| parse(value)}
+			fields = header.zip(row).to_h
+			
+			summary[fields[:syscall]] = fields
+		end
+		
+		if line = input.gets
+			row = pattern.match(line).captures.map{|value| parse(value)}
+			fields = header.zip(row).to_h
+			summary[:total] = fields
+		end
+	end
+	
+	Process.waitpid(pid)
+	
+	return summary
+end
+
+pids.each do |pid|
+	start_times = getrusage(pid)
+	Console.logger.info("Process #{pid} start times:", start_times)
+	
+	summary = strace(pid)
+	
+	Console.logger.info("strace -p #{pid}") do |buffer|
+		summary.each do |fields|
+			buffer.puts fields.inspect
+		end
+	end
+	
+	end_times = getrusage(pid)
+	Console.logger.info("Process #{pid} end times:", end_times)
+	
+	if total = summary[:total]
+		process_duration = end_times.utime - start_times.utime
+		wait_duration = summary[:total][:seconds]
+		
+		Console.logger.info("Process Waiting: #{wait_duration.round(4)}s out of #{process_duration.round(4)}s") do |buffer|
+			buffer.puts "Wait percentage: #{(wait_duration / process_duration * 100.0).round(2)}%"
+		end
+	else
+		Console.logger.warn("No system calls detected.")
+	end
+end

data/lib/async/condition.rb

@@ -33,8 +33,8 @@ module Async
 		# @return [Object]
 		def wait
 			fiber = Fiber.current
-			
 			@waiting << fiber
+			
 			Task.yield
 			
 			# It would be nice if there was a better construct for this. We only need to invoke #delete if the task was not resumed normally. This can only occur with `raise` and `throw`. But there is no easy way to detect this.

data/lib/async/node.rb

@@ -26,7 +26,7 @@ module Async
 		# Create a new node in the tree.
 		# @param parent [Node, nil] This node will attach to the given parent.
 		def initialize(parent = nil)
-			@children = Set.new
+			@children = nil
 			@parent = nil
 			
 			@annotation = nil
@@ -40,7 +40,7 @@ module Async
 		# @attr parent [Node, nil]
 		attr :parent
 		
-		# @attr children [Set<Node>]
+		# @attr children [Set<Node>] Optional list of children.
 		attr :children
 		
 		# A useful identifier for the current node.
@@ -84,17 +84,22 @@ module Async
 			
 			if parent
 				@parent = parent
-				@parent.children << self
+				@parent.add_child(self)
 			end
 			
 			return self
 		end
 		
+		protected def add_child child
+			@children ||= Set.new
+			@children << child
+		end
+		
 		# Whether the node can be consumed safely. By default, checks if the
 		# children set is empty.
 		# @return [Boolean]
 		def finished?
-			@children.empty?
+			@children.nil? or @children.empty?
 		end
 		
 		# If the node has a parent, and is {finished?}, then remove this node from
@@ -118,7 +123,7 @@ module Async
 		def traverse(level = 0, &block)
 			yield self, level
 			
-			@children.each do |child|
+			@children&.each do |child|
 				child.traverse(level + 1, &block)
 			end
 		end

data/lib/async/queue.rb

@@ -37,6 +37,8 @@ module Async
 			self.signal unless self.empty?
 		end
 		
+		alias << enqueue
+		
 		def dequeue
 			while @items.empty?
 				self.wait
@@ -44,6 +46,14 @@ module Async
 			
 			@items.shift
 		end
+		
+		def async(&block)
+			parent = Task.current
+			
+			while item = self.dequeue
+				parent.async(item, &block)
+			end
+		end
 	end
 	
 	class LimitedQueue < Queue

data/lib/async/reactor.rb

@@ -58,7 +58,19 @@ module Async
 			end
 		end
 		
-		def initialize(parent = nil, selector: NIO::Selector.new, logger: nil)
+		def self.selector
+			if backend = ENV['ASYNC_BACKEND']&.to_sym
+				if NIO::Selector.backends.include?(backend)
+					return NIO::Selector.new(backend)
+				else
+					warn "Could not find ASYNC_BACKEND=#{backend}!"
+				end
+			end
+			
+			return NIO::Selector.new
+		end
+		
+		def initialize(parent = nil, selector: self.class.selector, logger: nil)
 			super(parent)
 			
 			@selector = selector
@@ -86,6 +98,7 @@ module Async
 			@stopped
 		end
 		
+		# TODO Remove these in next major release. They are too confusing to use correctly.
 		def_delegators :@timers, :every, :after
 		
 		# Start an asynchronous task within the specified reactor. The task will be
@@ -142,6 +155,7 @@ module Async
 		end
 		
 		def finished?
+			# I'm not sure if checking `@running.empty?` is really required.
 			super && @ready.empty? && @running.empty?
 		end
 		
@@ -155,14 +169,18 @@ module Async
 			initial_task = self.async(*args, &block) if block_given?
 			
 			@timers.wait do |interval|
-				# running used to correctly answer on `finished?`, and to reuse Array object.
-				@running, @ready = @ready, @running
-				if @running.any?
+				# logger.debug(self) {"@ready = #{@ready} @running = #{@running}"}
+				
+				if @ready.any?
+					# running used to correctly answer on `finished?`, and to reuse Array object.
+					@running, @ready = @ready, @running
+					
 					@running.each do |fiber|
 						fiber.resume if fiber.alive?
 					end
+					
 					@running.clear
-
+					
 					# if there are tasks ready to execute, don't sleep.
 					if @ready.any?
 						interval = 0
@@ -172,23 +190,18 @@ module Async
 					end
 				end
 				
-				# - nil: no timers
-				# - -ve: timers expired already
-				# -   0: timers ready to fire
-				# - +ve: timers waiting to fire
-				if interval && interval < 0
-					interval = 0
-				end
-				
-				# logger.debug(self) {"Updating #{@children.count} children..."}
 				# As timeouts may have been updated, and caused fibers to complete, we should check this.
-				
-				# If there is nothing to do, then finish:
-				if !interval && self.finished?
-					return initial_task
+				if interval.nil?
+					if self.finished?
+						# If there is nothing to do, then finish:
+						return initial_task
+					end
+				elsif interval < 0
+					# We have timers ready to fire, don't sleep in the selctor:
+					interval = 0
 				end
 				
-				# logger.debug(self) {"Selecting with #{@children.count} fibers interval = #{interval.inspect}..."}
+				# logger.debug(self) {"Selecting with #{@children&.count} children with interval = #{interval.inspect}..."}
 				if monitors = @selector.select(interval)
 					monitors.each do |monitor|
 						monitor.value.resume
@@ -207,7 +220,7 @@ module Async
 		# 
 		# @return [void]
 		def close
-			@children.each(&:stop)
+			@children&.each(&:stop)
 			
 			# TODO Should we also clear all timers?
 			@selector.close

data/lib/async/task.rb

@@ -134,7 +134,7 @@ module Async
 		# Stop the task and all of its children.
 		# @return [void]
 		def stop
-			@children.each(&:stop)
+			@children&.each(&:stop)
 			
 			if @fiber.alive?
 				@fiber.resume(Stop.new)

data/lib/async/version.rb

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

data/spec/async/condition_spec.rb

@@ -29,7 +29,6 @@ RSpec.describe Async::Condition do
 	it 'should continue after condition is signalled' do
 		task = reactor.async do
 			subject.wait
-			#puts "Got #{value}"
 		end
 		
 		expect(task.status).to be :running

data/spec/async/performance_spec.rb

@@ -4,9 +4,13 @@ require 'benchmark/ips'
 RSpec.describe Async::Wrapper do
 	let(:pipe) {IO.pipe}
 	
+	after do
+		pipe.each(&:close)
+	end
+	
 	let(:input) {described_class.new(pipe.first)}
 	let(:output) {described_class.new(pipe.last)}
-		
+	
 	it "should be fast to wait until readable" do
 		Benchmark.ips do |x|
 			x.report('Wrapper#wait_readable') do |repeats|

data/spec/async/reactor_spec.rb

@@ -37,6 +37,14 @@ RSpec.describe Async::Reactor do
 		end
 	end
 	
+	describe '#close' do
+		it "can close empty reactor" do
+			subject.close
+			
+			expect(subject).to be_closed
+		end
+	end
+	
 	describe '#stop' do
 		it "can be stop reactor" do
 			state = nil
@@ -55,6 +63,8 @@ RSpec.describe Async::Reactor do
 			subject.run
 			
 			expect(state).to be == :started
+			
+			subject.close
 		end
 		
 		it "can stop reactor from different thread" do
@@ -73,9 +83,11 @@ RSpec.describe Async::Reactor do
 			subject.run
 			
 			thread.join
+			
 			expect(subject).to be_stopped
 		end
 	end
+	
 	it "can't return" do
 		expect do
 			Async do |task|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.17.1
+  version: 1.18.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-29 00:00:00.000000000 Z
+date: 2019-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nio4r
@@ -144,6 +144,8 @@ files:
 - benchmark/async_vs_lightio.rb
 - examples/async_method.rb
 - examples/callback/loop.rb
+- examples/capture/README.md
+- examples/capture/capture.rb
 - examples/fibers.rb
 - examples/sleep_sort.rb
 - gems/event.gemfile
@@ -199,7 +201,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.2
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Async is an asynchronous I/O framework based on nio4r.