async 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0c677beaeb3fb10276210be29052382b077ac6ce
+  data.tar.gz: bc0719a32fbffef3861f111d7a245c45b6e24786
+SHA512:
+  metadata.gz: ad2df57e9e6ee7a4280a1b64c6429f6e8c69c2de40dcdd5cb9091c0e8f8b7debdd9f88d4ff3e049900aa16f97c48a3735630725ff4459db1e240360731844712
+  data.tar.gz: 1773d262ce191fcf566a385620ae7fd7f880f1e886f99e0f8bc4fd1829662b83e824cc3d694d6d4e37b25622608eff1a3452eb82b95e4f297f3aa9c41553d7d4

data/.gitignore

@@ -0,0 +1,21 @@
+*.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

data/.rspec

@@ -0,0 +1,4 @@
+--color 
+--format documentation
+--warnings
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+sudo: false
+dist: trusty
+cache: bundler
+rvm:
+  - 2.2.6
+  - 2.3.3
+  - 2.4.0
+  - jruby-head
+  - ruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head

data/Gemfile

@@ -0,0 +1,19 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in utopia.gemspec
+gemspec
+
+group :development do
+	gem 'pry'
+	gem 'guard-rspec'
+	
+	gem 'yard'
+end
+
+group :test do
+	gem 'benchmark-ips'
+	gem 'ruby-prof', platforms: :mri
+	
+	gem 'simplecov'
+	gem 'coveralls', require: false
+end

data/Guardfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+directories %w(lib spec)
+clearing :on
+
+guard :rspec, cmd: "bundle exec rspec" do
+	watch(%r{^spec/.+_spec\.rb$})
+	watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+	watch("spec/spec_helper.rb") { "spec" }
+end

data/README.md

@@ -0,0 +1,100 @@
+# Async
+
+Asynchronous I/O framework for Ruby based on [nio4r] and [timers].
+
+[timers]: https://github.com/socketry/timers
+[nio4r]: https://github.com/socketry/nio4r
+
+[![Build Status](https://secure.travis-ci.org/socketry/async.svg)](http://travis-ci.org/socketry/async)
+[![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)
+
+## Motivation
+
+Several years ago, I was hosting websites on a server in my garage. Back then, my ADSL modem was very basic, and I wanted to have a DNS server which would resolve to an internal IP address when the domain itself resolved to my public IP. Thus was born [RubyDNS]. This project [was originally built on](https://github.com/ioquatix/rubydns/tree/v0.8.5) top of [EventMachine], but a lack of support for [IPv6 at the time](https://github.com/ioquatix/rubydns/issues/45) and [other problems](https://github.com/ioquatix/rubydns/issues/14), meant that I started looking for other options. Around that time [Celluloid] was picking up steam. I had not encountered actors before and I wanted to learn more about it. So, [I reimplemented RubyDNS on top of Celluloid](https://github.com/ioquatix/rubydns/tree/v0.9.0) and this eventually became the first stable release.
+
+Moving forward, I refactored the internals of RubyDNS into [Celluloid::DNS]. This rewrite helped solidify the design of RubyDNS and to a certain extent it works. However, [unfixed bugs and design problems](https://github.com/celluloid/celluloid/pull/710) in Celluloid meant that RubyDNS 2.0 was delayed by almost 2 years. I wasn't happy releasing things with known bugs and problems. Anyway, a lot of discussion and thinking, I decided to build a small event reactor using [nio4r] and [timers], the core parts of [Celluloid::IO] which made it work so well.
+
+[Celluloid]: https://github.com/celluloid/celluloid
+[Celluloid::IO]: https://github.com/celluloid/celluloid-io
+[Celluloid::DNS]: https://github.com/celluloid/celluloid-dns
+[EventMachine]: https://github.com/eventmachine/eventmachine
+[RubyDNS]: https://github.com/ioquatix/rubydns
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "async"
+```
+
+And then execute:
+
+	$ bundle
+
+Or install it yourself as:
+
+	$ gem install async
+
+## Supported Ruby Versions
+
+This library aims to support and is [tested against][travis] the following Ruby
+versions:
+
+* Ruby 2.2.6+
+* Ruby 2.3
+* Ruby 2.4
+* JRuby 9.1.6.0+
+
+If something doesn't work on one of these versions, it's a bug.
+
+This library may inadvertently work (or seem to work) on other Ruby versions,
+however support will only be provided for the versions listed above.
+
+If you would like this library to support another Ruby version or
+implementation, you may volunteer to be a maintainer. Being a maintainer
+entails making sure all tests run and pass on that implementation. When
+something breaks on your implementation, you will be responsible for providing
+patches in a timely fashion. If critical issues for a particular implementation
+exist at the time of a major release, support for that Ruby version may be
+dropped.
+
+[travis]: http://travis-ci.org/socketry/async
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## See Also
+
+- [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
+- [rubydns](https://github.com/socketry/rubydns) — A easy to use Ruby DNS server.
+
+## License
+
+Released under the MIT license.
+
+Copyright, 2017, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+
+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.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:test)
+
+task :default => :test

data/async.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+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.
+	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.require_paths = ["lib"]
+	spec.has_rdoc      = "yard"
+	
+	spec.required_ruby_version = ">= 2.2.6"
+
+	spec.add_runtime_dependency "nio4r", "~> 2"
+	spec.add_runtime_dependency "timers", "~> 4.1"
+	
+	spec.add_development_dependency "bundler", "~> 1.3"
+	spec.add_development_dependency "process-daemon", "~> 1.0.0"
+	spec.add_development_dependency "rspec", "~> 3.4.0"
+	spec.add_development_dependency "rake"
+end

data/examples/aio.rb

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+require 'async'
+
+reactor = Async::Reactor.new
+
+puts "Creating server"
+server = TCPServer.new("localhost", 6777)
+
+REPEATS = 10
+
+timer = reactor.after(1) do
+	puts "Reactor timed out!"
+	reactor.stop
+end
+
+reactor.async(server) do |server, task|
+	REPEATS.times do |i|
+		puts "Accepting peer on server #{server}"
+		task.with(server.accept) do |peer|
+			puts "Sending data to peer"
+			peer << "data #{i}"
+			peer.shutdown
+		end
+	end
+	
+	puts "Server finished, canceling timer"
+	timer.cancel
+end
+
+REPEATS.times do |i|
+	# This aspect of the connection is synchronous.
+	puts "Creating client #{i}"
+	client = TCPSocket.new("localhost", 6777)
+	
+	reactor.async(client) do |client|
+		puts "Reading data on client #{i}"
+		puts client.read(1024)
+	end
+end
+
+reactor.run

data/lib/async.rb

@@ -0,0 +1,23 @@
+# 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 "async/version"
+require_relative "async/logger"
+require_relative "async/reactor"

data/lib/async/io.rb

@@ -0,0 +1,93 @@
+# 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 'wrapper'
+
+require 'forwardable'
+
+module Async
+	# Represents an asynchronous IO within a reactor.
+	class IO < Wrapper
+		extend Forwardable
+		
+		WRAPPERS = {}
+		
+		def self.[] instance
+			WRAPPERS[instance.class]
+		end
+		
+		class << self
+			if RUBY_VERSION >= "2.3"
+				def wrap_blocking_method(new_name, method_name)
+					# puts "#{self}\##{$1} -> #{method_name}"
+					define_method(new_name) do |*args|
+						async do
+							@io.__send__(method_name, *args, exception: false)
+						end
+					end
+				end
+			else
+				def wrap_blocking_method(new_name, method_name)
+					# puts "#{self}\##{$1} -> #{method_name}"
+					define_method(new_name) do |*args|
+						async do
+							@io.__send__(method_name, *args)
+						end
+					end
+				end
+			end
+			
+			def wraps(klass, *additional_methods)
+				WRAPPERS[klass] = self
+				
+				klass.instance_methods(false).grep(/(.*)_nonblock/) do |method_name|
+					wrap_blocking_method($1, method_name)
+				end
+				
+				def_delegators :@io, *(additional_methods - instance_methods(false))
+			end
+		end
+		
+		wraps ::IO
+		
+		protected
+		
+		def async
+			while true
+				begin
+					result = yield
+					
+					case result
+					when :wait_readable
+						wait_readable
+					when :wait_writable
+						wait_writable
+					else
+						return result
+					end
+				rescue ::IO::WaitReadable
+					wait_readable
+				rescue ::IO::WaitWritable
+					wait_writable
+				end
+			end
+		end
+	end
+end

data/lib/async/logger.rb

@@ -0,0 +1,39 @@
+# 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 'logger'
+
+module Async
+	class << self
+		attr :logger
+		
+		def default_log_level
+			if $DEBUG
+				Logger::DEBUG
+			elsif $VERBOSE
+				Logger::INFO
+			else
+				Logger::WARN
+			end
+		end
+	end
+	
+	@logger = Logger.new($stderr, level: default_log_level)
+end

data/lib/async/reactor.rb

@@ -0,0 +1,166 @@
+# 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 'logger'
+require_relative 'task'
+require_relative 'wrapper'
+
+require 'nio'
+require 'timers'
+require 'forwardable'
+
+module Async
+	class TimeoutError < RuntimeError
+	end
+	
+	class Reactor
+		extend Forwardable
+		
+		def self.run(*args, &block)
+			reactor = self.new
+			
+			reactor.async(*args, &block)
+		end
+		
+		def initialize(wrappers: IO)
+			@wrappers = wrappers
+			
+			@selector = NIO::Selector.new
+			@timers = Timers::Group.new
+			
+			@fibers = []
+			
+			@stopped = true
+		end
+		
+		attr :wrappers
+		attr :stopped
+		
+		def_delegators :@timers, :every, :after
+		
+		def wrap(io, task)
+			@wrappers[io].new(io, task)
+		end
+		
+		def with(io, &block)
+			async do |task|
+				task.with(io, &block)
+			end
+		end
+		
+		def async(*ios, &block)
+			task = Task.new(ios, self, &block)
+			
+			# I want to take a moment to explain the logic of this.
+			# When calling an async block, we deterministically execute it until the
+			# first blocking operation. We don't *have* to do this - we could schedule
+			# it for later execution, but it's useful to:
+			# - Fail at the point of call where possible.
+			# - Execute determinstically where possible.
+			# - Avoid overhead if no blocking operation is performed.
+			fiber = task.run
+			
+			# We only start tracking this if the fiber is still alive:
+			@fibers << fiber if fiber.alive?
+			
+			# Async.logger.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..."
+			return task
+		end
+		
+		def register(*args)
+			@selector.register(*args)
+		end
+		
+		def stop
+			@stopped = true
+		end
+		
+		def run(*args, &block)
+			@stopped = false
+			
+			# Allow the user to kick of the initial async tasks.
+			async(*args, &block) if block_given?
+			
+			@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
+				
+				# Async.logger.debug "[#{self} Pre] Updating #{@fibers.count} fibers..."
+				# Async.logger.debug @fibers.collect{|fiber| [fiber, fiber.alive?]}.inspect
+				# As timeouts may have been updated, and caused fibers to complete, we should check this.
+				@fibers.delete_if{|fiber| !fiber.alive?}
+				
+				# If there is nothing to do, then finish:
+				# Async.logger.debug "[#{self}] @fibers.empty? = #{@fibers.empty?} && interval #{interval.inspect}"
+				return if @fibers.empty? && interval.nil?
+				
+				# Async.logger.debug "Selecting with #{@fibers.count} fibers interval = #{interval}..."
+				if monitors = @selector.select(interval)
+					monitors.each do |monitor|
+						if task = monitor.value
+							# Async.logger.debug "Resuming task #{task} due to IO..."
+							task.resume
+						end
+					end
+				end
+			end until @stopped
+		ensure
+			# Async.logger.debug "[#{self} Ensure] Exiting run-loop (stopped: #{@stopped} exception: #{$!})..."
+			# Async.logger.debug @fibers.collect{|fiber| [fiber, fiber.alive?]}.inspect
+			@stopped = true
+		end
+		
+		def sleep(duration)
+			task = Fiber.current
+			
+			timer = self.after(duration) do
+				if task.alive?
+					task.resume
+				end
+			end
+			
+			result = Fiber.yield
+			
+			raise result if result.is_a? Exception
+		ensure
+			timer.cancel if timer
+		end
+		
+		def timeout(duration)
+			backtrace = caller
+			task = Fiber.current
+			
+			timer = self.after(duration) do
+				if task.alive?
+					error = TimeoutError.new("execution expired")
+					error.set_backtrace backtrace
+					task.resume error
+				end
+			end
+			
+			yield
+		ensure
+			timer.cancel if timer
+		end
+	end
+end