async 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2fbc8a7a4d1987be4082ebae4b613319a95e936f
-  data.tar.gz: a6eb19cd5a9485c3de75d4498e7f96b0f0755334
+  metadata.gz: 881ace206b49720782f4bf53c50cea4997efe5ac
+  data.tar.gz: f9b1ecbd174370ce7b62c6f4fdbd6a0dddda858c
 SHA512:
-  metadata.gz: 9f53412d28ed692ca27c059371ea97bca9a7424e6dc37ad3b97e910c8031d475388de304030a8004cce54712712c59915071bff1fd281892a1ed96fb7bedbe14
-  data.tar.gz: 6d2691f41bdd26610261269e8c15ef210696f15dba391119437758e604ac524fb0d65c871bdcc164babd6570b3c8fbea2784b4d3cd57ef9f4d6e6ced48552f67
+  metadata.gz: ef14bfef3d114ef2ee95f15fc239efad2b1f91efe5b0e99d8243dc3d5d487188cf41a7c5e36708c07d8f007db0b5fd7dfaf3ba731ab2a3fb98751bf0a6938b8c
+  data.tar.gz: fc1eeaadb11ec7dafe4e21ea2afa251508d1eaab8820d86b4e8a93aa7eca1828caa3c9bf42384cae7aec11afca8a0159b608fd732e26dcdf25118832fbcaa748

data/.rspec

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

data/.travis.yml

@@ -10,7 +10,9 @@ rvm:
   - 2.4
   - jruby-head
   - ruby-head
+  - rbx-3
 matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
+    - rvm: rbx-3

data/README.md

@@ -1,6 +1,6 @@
 # Async
 
-Asynchronous I/O framework for Ruby based on [nio4r] and [timers].
+Async is a composable asynchronous I/O framework for Ruby based on [nio4r] and [timers].
 
 [timers]: https://github.com/socketry/timers
 [nio4r]: https://github.com/socketry/nio4r
@@ -39,53 +39,69 @@ Or install it yourself as:
 
 ## Usage
 
-Implementing an asynchronous client/server is easy:
+`Async::Reactor` is the top level IO reactor, and runs `Async::Task`s asynchronously. The reactor itself is not thread-safe, so you'd typically have one reactor per thread.
+
+An `Async::Task` runs using a `Fiber` and blocking operations e.g. `sleep`, `read`, `write` yield control until the operation can succeed.
+
+The design of this core library is deliberately simple in scope. Additional libraries provide asynchronous networking, process management, etc. It's likely you will prefer to depend on `async-io` for actual wrappers around `IO` and `Socket`.
+
+### Main Entry Points
+
+#### `Async::Reactor.run`
+
+The highest level entry point is `Async::Reactor.run`. It's useful if you are building a library and you want well defined asynchronous semantics.
 
 ```ruby
-#!/usr/bin/env ruby
-
-require 'async'
-require 'async/tcp_socket'
-
-def echo_server
-  Async::Reactor.run do |task|
-    # This is a synchronous block within the current task:
-    task.with(TCPServer.new('localhost', 9000)) do |server|
-      
-      # This is an asynchronous block within the current reactor:
-      task.reactor.with(server.accept) do |client|
-        data = client.read(512)
-        
-        task.sleep(rand)
-        
-        client.write(data)
-      end while true
-    end
-  end
+def run_server
+	Async::Reactor.run do |task|
+		# ... acccept connections
+	end
 end
+```
+
+If `Async::Reactor.run(&block)` happens within an existing reactor, it will schedule an asynchronous task and return. If `Async::Reactor.run(&block)` happens outside of an existing reactor, it will create a reactor, schedule the asynchronous task, and block until it completes. The task is scheduled by calling `Async::Reactor.async(&block)`.
+
+This puts the power into the hands of the client, who can either have blocking or non-blocking behaviour by explicitly wrapping the call in a reactor (or not). The cost of using `Async::Reactor.run` is minimal for initialization/server setup, but is not ideal for per-connection tasks.
+
+#### `Async::Task#async`
+
+If you can guarantee you are running within a task, and have access to it (e.g. via an argument), you can efficiently schedule new tasks using the `Async::Task#async(&block)` method.
 
-def echo_client(data)
-  Async::Reactor.run do |task|
-    Async::TCPServer.connect('localhost', 9000) do |socket|
-      socket.write(data)
-      puts "echo_client: #{socket.read(512)}"
-    end
-  end
+```ruby
+def do_request(task: Task.current)
+	task.async do
+		# ... do some actual work
+	end
 end
+```
+
+This method effectively creates a child task. It's the most efficient way to schedule a task. The task is executed until the first blocking operation, at which point it will yield control and `#async` will return. The result of this method is the task itself.
+
+### Reactor Tree
+
+`Async::Reactor` and `Async::Task` form nodes in a tree. Reactors and tasks can spawn children tasks. When you invoke `Async::Reactor#async`, the parent task is determined by calling `Async::Task.current?` which uses fiber local storage. A slightly more efficient method is to use `Async::Task#async`, which uses `self` as the parent task.
 
+When invoking `Async::Reactor#stop`, you will stop *all* children tasks of that reactor. Tasks will raise `Async::Interrupt` if they are in a blocking operation. In addition, it's possible to only stop a sub-tree by issuing `Async::Task#stop`, which will stop that task and all it's children (recursively). When you design a server, you should return the task back to the caller. They can use this task to stop the server if needed, independently of any other unrelated tasks within the reactor, and it will correctly clean up all related tasks.
+
+### Resource Management
+
+In order to ensure your resources are cleaned up correctly, make sure you wrap resources appropriately, e.g.:
+
+```ruby
 Async::Reactor.run do
-  # Start the echo server:
-  server = echo_server
-  
-  5.times.collect do |i|
-    echo_client("Hello World #{i}")
-  end.each(&:wait) # Wait until all clients are finished.
-  
-  # Terminate the server and all tasks created within it's async scope:
-  server.stop
+	begin
+		socket = connect(remote_address) # May raise Async::Interrupt so socket could be nil
+		
+		socket.write(...) # May raise Async::Interrupt
+		socket.read(...) # May raise Async::Interrupt
+	ensure
+		socket.close if socket
+	end
 end
 ```
 
+As tasks run synchronously until they yield back to the reactor, you can guarantee this model works correctly. While in theory `IO#autoclose` allows you to automatically close file descriptors when they go out of scope via the GC, it may produce unpredictable behavour (exhaustion of file descriptors, flushing data at odd times), so it's not recommended.
+
 ## Supported Ruby Versions
 
 This library aims to support and is [tested against][travis] the following Ruby
@@ -119,7 +135,9 @@ dropped.
 
 ## See Also
 
+- [async-io](https://github.com/socketry/async-io) — Asynchronous networking and sockets.
 - [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
+- [async-rspec](https://github.com/socketry/async-rspec) — Shared contexts for running async specs.
 - [rubydns](https://github.com/ioquatix/rubydns) — A easy to use Ruby DNS server.
 
 ## License

data/Rakefile

@@ -4,3 +4,7 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:test)
 
 task :default => :test
+
+task :coverage do
+	ENV['COVERAGE'] = 'y'
+end

data/async.gemspec

@@ -21,13 +21,14 @@ Gem::Specification.new do |spec|
 	spec.require_paths = ["lib"]
 	spec.has_rdoc      = "yard"
 	
-	spec.required_ruby_version = ">= 2.0.0"
+	spec.required_ruby_version = "~> 2.0"
 
 	spec.add_runtime_dependency "nio4r"
 	spec.add_runtime_dependency "timers", "~> 4.1"
 	
+	spec.add_development_dependency "async-rspec", "~> 1.0"
+	
 	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 "rspec", "~> 3.4"
 	spec.add_development_dependency "rake"
 end

data/lib/async/node.rb

@@ -29,6 +29,9 @@ module Async
 			@children = Set.new
 			@parent = nil
 			
+			@annotation = nil
+			@object_name = nil
+			
 			if parent
 				self.parent = parent
 			end
@@ -40,6 +43,34 @@ module Async
 		# @attr children [Set<Node>]
 		attr :children
 		
+		# A useful identifier for the current node.
+		attr :annotation
+		
+		def annotate(annotation)
+			if block_given?
+				previous_annotation = @annotation
+				@annotation = annotation
+				yield
+				@annotation = previous_annotation
+			else
+				@annotation = annotation
+			end
+		end
+		
+		def description
+			@object_name ||= "#{self.class}:0x#{object_id.to_s(16)}"
+			
+			if @annotation
+				"#{@object_name} #{@annotation}"
+			else
+				@object_name
+			end
+		end
+		
+		def to_s
+			"\#<#{description}>"
+		end
+		
 		# Change the parent of this node.
 		# @param parent [Node, nil] the parent to attach to, or nil to detach.
 		# @return [self]
@@ -81,5 +112,21 @@ module Async
 		def reap(child)
 			@children.delete(child)
 		end
+		
+		# Traverse the tree.
+		# @yield [node, level] The node and the level relative to the given root.
+		def traverse(level = 0, &block)
+			yield self, level
+			
+			@children.each do |child|
+				child.traverse(level + 1, &block)
+			end
+		end
+		
+		def print_hierarchy(out = $stdout)
+			self.traverse do |node, level|
+				out.puts "#{"\t" * level}#{node}"
+			end
+		end
 	end
 end

data/lib/async/reactor.rb

@@ -35,7 +35,7 @@ module Async
 	class Reactor < Node
 		extend Forwardable
 		
-		# The preferred method to invoke asynchronous behavior.
+		# The preferred method to invoke asynchronous behavior at the top level.
 		#
 		# - When invoked within an existing reactor task, it will run the given block
 		# asynchronously. Will return the task once it has been scheduled.
@@ -59,43 +59,35 @@ module Async
 				return reactor
 			end
 		end
-	
-		# @param wrappers [Hash] A mapping for wrapping pre-existing IO objects.
-		def initialize(wrappers: IO)
-			super(nil)
-			
-			@wrappers = wrappers
+		
+		def initialize
+			super
 			
 			@selector = NIO::Selector.new
 			@timers = Timers::Group.new
 			
 			@stopped = true
 		end
-	
-		# @attr wrappers [Object] 
-		attr :wrappers
-		# @attr stopped [Boolean] 
+		
+		def to_s
+			"<#{self.description} stopped=#{@stopped}>"
+		end
+		
+		# @attr stopped [Boolean]
 		attr :stopped
 		
 		def_delegators :@timers, :every, :after
-	
-		# Wrap a given IO object and associate it with a specific task.
-		# @param io The `IO` instance to wrap.
-		# @param task [Task] The task which manages the wrapper.
-		# @return [Wrapper]
-		def wrap(io, task)
-			@wrappers[io].new(io, task)
-		end
-	
-		def with(io, &block)
-			async do |task|
-				task.with(io, &block)
-			end
-		end
-
-		# @return [Task]	
-		def async(*ios, &block)
-			task = Task.new(ios, self, &block)
+		
+		# Start an asynchronous task within the specified reactor. The task will be
+		# executed until the first blocking call, at which point it will yield and
+		# and this method will return.
+		#
+		# This is the main entry point for scheduling asynchronus tasks.
+		#
+		# @yield [Task] Executed within the asynchronous task.
+		# @return [Task] The task that was 
+		def async(*args, &block)
+			task = Task.new(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
@@ -104,7 +96,7 @@ module Async
 			# - Fail at the point of call where possible.
 			# - Execute determinstically where possible.
 			# - Avoid overhead if no blocking operation is performed.
-			task.run
+			task.run(*args)
 			
 			# Async.logger.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..."
 			return task
@@ -141,7 +133,6 @@ module Async
 				interval = 0 if interval && interval < 0
 				
 				Async.logger.debug{"[#{self} Pre] Updating #{@children.count} children..."}
-				Async.logger.debug{@children.collect{|child| [child.to_s, child.alive?]}.inspect}
 				# As timeouts may have been updated, and caused fibers to complete, we should check this.
 				
 				# If there is nothing to do, then finish:
@@ -161,16 +152,18 @@ module Async
 			
 			return self
 		ensure
-			Async.logger.debug{"[#{self} Ensure] Exiting run-loop (stopped: #{@stopped} exception: #{$!})..."}
-			Async.logger.debug{@children.collect{|child| [child.to_s, child.alive?]}.inspect}
+			Async.logger.debug{"[#{self} Ensure] Exiting run-loop (stopped: #{@stopped} exception: #{$!.inspect})..."}
 			@stopped = true
 		end
 	
-		# Close each of the children tasts and selector.
+		# Stop each of the children tasks and close the selector.
+		# 
 		# @return [void]
 		def close
 			@children.each(&:stop)
 			
+			# TODO Should we also clear all timers?
+			
 			@selector.close
 			@selector = nil
 		end

data/lib/async/task.rb

@@ -53,34 +53,25 @@ module Async
 				return result
 			end
 		end
-	
+		
 		# Create a new task.
-		# @param ios [Array] an array of `IO` objects such as `TCPServer`, `Socket`, etc.
-		# @param reactor [Async::Reactor] 
-		# @return [void]
-		def initialize(ios, reactor)
-			if parent = Task.current?
-				super(parent)
-			else
-				super(reactor)
-			end
-			
-			@ios = Hash[
-				ios.collect{|io| [io.fileno, reactor.wrap(io, self)]}
-			]
+		# @param reactor [Async::Reactor] the reactor this task will run within.
+		# @param parent [Async::Task] the parent task.
+		def initialize(reactor, parent = Task.current?)
+			super(parent || reactor)
 			
 			@reactor = reactor
 			
-			@status = :running
+			@status = :initialized
 			@result = nil
 			
 			@condition = nil
 			
-			@fiber = Fiber.new do
+			@fiber = Fiber.new do |args|
 				set!
 				
 				begin
-					@result = yield(*@ios.values, self)
+					@result = yield(self, *args)
 					@status = :complete
 					# Async.logger.debug("Task #{self} completed normally.")
 				rescue Interrupt
@@ -93,19 +84,14 @@ module Async
 					raise
 				ensure
 					# Async.logger.debug("Task #{self} closing: #{$!}")
-					close
+					finish!
 				end
 			end
 		end
 		
-		# Show the current status of the task as a string.
-		# @todo (picat) Add test for this method?	
 		def to_s
-			"#{super}[#{@status}]"
+			"<#{self.description} status=#{@status}>"
 		end
-	
-		# @attr ios [Array<IO>] All wrappers associated with this task.
-		attr :ios
 		
 		# @attr ios [Reactor] The reactor the task was created within.
 		attr :reactor
@@ -119,10 +105,23 @@ module Async
 		attr :status
 		
 		# Resume the execution of the task.
-		def run
-			@fiber.resume
+		def run(*args)
+			if @status == :initialized
+				@status = :running
+				@fiber.resume(*args)
+			else
+				raise RuntimeError, "Task already running!"
+			end
 		end
-	
+		
+		def async(*args, &block)
+			task = Task.new(@reactor, self, &block)
+			
+			task.run(*args)
+			
+			return task
+		end
+		
 		# Retrieve the current result of the task. Will cause the caller to wait until result is available.
 		# @raise [RuntimeError] if the task's fiber is the current fiber.
 		# @return [Object]
@@ -150,62 +149,35 @@ module Async
 			end
 		end
 	
-		# Provide a wrapper to an IO object with a Reactor.
-		# @yield [Async::Wrapper] a wrapped object.
-		def with(io, *args)
-			wrapper = @reactor.wrap(io, self)
-			yield wrapper, *args
-		ensure
-			wrapper.close if wrapper
-			io.close if io
-		end
-		
-		# Wrap and bind the given object to the reactor.
-		# @param io the native object to bind to this task.
-		# @return [Wrapper] The wrapped object.
-		def bind(io)
-			@ios[io.fileno] ||= @reactor.wrap(io, self)
-		end
-		
-		# Register a given IO with given interests to be able to monitor it.
-		# @param io [IO] a native io object.
-		# @param interests [Symbol] One of `:r`, `:w` or `:rw`.
-		# @return [NIO::Monitor]
-		def register(io, interests)
-			@reactor.register(io, interests)
-		end
-	
 		# Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.
 		# @return [Async::Task]
 		# @raise [RuntimeError] if task was not {set!} for the current fiber.
 		def self.current
 			Thread.current[:async_task] or raise RuntimeError, "No async task available!"
 		end
-
-			
+	
 		# Check if there is a task defined for the current fiber.
 		# @return [Async::Task, nil]
 		def self.current?
 			Thread.current[:async_task]
 		end
-	
+		
 		# Check if the task is running.
 		# @return [Boolean]
 		def running?
 			@status == :running
 		end
-		
+	
 		# Whether we can remove this node from the reactor graph.
 		# @return [Boolean]
 		def finished?
 			super && @status != :running
 		end
-		
-		# Close all bound IO objects.
-		def close
-			@ios.each_value(&:close)
-			@ios = nil
-			
+	
+		private
+	
+		# Finish the current task, and all bound bound IO objects.
+		def finish!
 			# Attempt to remove this node from the task tree.
 			consume
 			
@@ -214,9 +186,7 @@ module Async
 				@condition.signal(@result)
 			end
 		end
-		
-		private
-		
+	
 		# Set the current fiber's `:async_task` to this task.
 		def set!
 			# This is actually fiber-local: