async 1.30.2 → 2.0.0

data/lib/async/semaphore.md

@@ -0,0 +1,41 @@
+A synchronization primitive, which limits access to a given resource, such as a limited number of database connections, open files, or network connections.
+
+## Example
+
+~~~ ruby
+require 'async'
+require 'async/semaphore'
+require 'net/http'
+
+Sync do
+	# Only allow two concurrent tasks at a time:
+	semaphore = Async::Semaphore.new(2)
+	
+	# Generate an array of 10 numbers:
+	terms = ['ruby', 'python', 'go', 'java', 'c++'] 
+	
+	# Search for the terms:
+	terms.each do |term|
+		semaphore.async do |task|
+			Console.logger.info("Searching for #{term}...")
+			response = Net::HTTP.get(URI "https://www.google.com/search?q=#{term}")
+			Console.logger.info("Got response #{response.size} bytes.")
+		end
+	end
+end
+~~~
+
+### Output
+
+~~~
+0.0s     info: Searching for ruby... [ec=0x3c] [pid=50523]
+0.04s     info: Searching for python... [ec=0x21c] [pid=50523]
+1.7s     info: Got response 182435 bytes. [ec=0x3c] [pid=50523]
+1.71s     info: Searching for go... [ec=0x834] [pid=50523]
+3.0s     info: Got response 204854 bytes. [ec=0x21c] [pid=50523]
+3.0s     info: Searching for java... [ec=0xf64] [pid=50523]
+4.32s     info: Got response 103235 bytes. [ec=0x834] [pid=50523]
+4.32s     info: Searching for c++... [ec=0x12d4] [pid=50523]
+4.65s     info: Got response 109697 bytes. [ec=0xf64] [pid=50523]
+6.64s     info: Got response 87249 bytes. [ec=0x12d4] [pid=50523]
+~~~

data/lib/async/semaphore.rb

@@ -21,8 +21,11 @@
 # THE SOFTWARE.
 
 module Async
-	# A semaphore is used to control access to a common resource in a concurrent system. A useful way to think of a semaphore as used in the real-world systems is as a record of how many units of a particular resource are available, coupled with operations to adjust that record safely (i.e. to avoid race conditions) as units are required or become free, and, if necessary, wait until a unit of the resource becomes available.
+	# A synchronization primitive, which limits access to a given resource.
+	# @public Since `stable-v1`.
 	class Semaphore
+		# @parameter limit [Integer] The maximum number of times the semaphore can be acquired before it blocks.
+		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
 		def initialize(limit = 1, parent: nil)
 			@count = 0
 			@limit = limit
@@ -67,8 +70,8 @@ module Async
 		
 		# Acquire the semaphore, block if we are at the limit.
 		# If no block is provided, you must call release manually.
-		# @yield when the semaphore can be acquired
-		# @return the result of the block if invoked
+		# @yields {...} When the semaphore can be acquired.
+		# @returns The result of the block if invoked.
 		def acquire
 			wait
 			
@@ -89,7 +92,7 @@ module Async
 			
 			while (@limit - @count) > 0 and fiber = @waiting.shift
 				if fiber.alive?
-					fiber.resume
+					Fiber.scheduler.resume(fiber)
 				end
 			end
 		end
@@ -102,7 +105,7 @@ module Async
 			
 			if blocking?
 				@waiting << fiber
-				Task.yield while blocking?
+				Fiber.scheduler.transfer while blocking?
 			end
 		rescue Exception
 			@waiting.delete(fiber)

data/lib/async/task.rb

@@ -21,7 +21,6 @@
 # THE SOFTWARE.
 
 require 'fiber'
-require 'forwardable'
 
 require_relative 'node'
 require_relative 'condition'
@@ -38,55 +37,45 @@ module Async
 				true
 			end
 			
-			def resume
+			def transfer
 				@task.stop
 			end
 		end
 	end
 	
-	# A task represents the state associated with the execution of an asynchronous
-	# block.
+	# Raised if a timeout occurs on a specific Fiber. Handled gracefully by `Task`.
+	# @public Since `stable-v1`.
+	class TimeoutError < StandardError
+		def initialize(message = "execution expired")
+			super
+		end
+	end
+	
+	# Encapsulates the state of a running task and it's result.
+	# @public Since `stable-v1`.
 	class Task < Node
-		extend Forwardable
-		
-		# Yield the unerlying `result` for the task. If the result
-		# is an Exception, then that result will be raised an its
-		# exception.
-		# @return [Object] result of the task
-		# @raise [Exception] if the result is an exception
-		# @yield [result] result of the task if a block if given.
+		# @deprecated With no replacement.
 		def self.yield
-			if block_given?
-				result = yield
-			else
-				result = Fiber.yield
-			end
-			
-			if result.is_a? Exception
-				raise result
-			else
-				return result
-			end
+			Fiber.scheduler.transfer
 		end
 		
 		# Create a new task.
-		# @param reactor [Async::Reactor] the reactor this task will run within.
-		# @param parent [Async::Task] the parent task.
-		def initialize(reactor, parent = Task.current?, logger: nil, finished: nil, **options, &block)
-			super(parent || reactor, **options)
-			
-			@reactor = reactor
+		# @parameter reactor [Reactor] the reactor this task will run within.
+		# @parameter parent [Task] the parent task.
+		def initialize(parent = Task.current?, finished: nil, **options, &block)
+			super(parent, **options)
 			
 			@status = :initialized
 			@result = nil
 			@finished = finished
 			
-			@logger = logger || @parent.logger
-			
-			@fiber = make_fiber(&block)
+			@block = block
+			@fiber = nil
 		end
 		
-		attr :logger
+		def reactor
+			self.root
+		end
 		
 		if Fiber.current.respond_to?(:backtrace)
 			def backtrace(*arguments)
@@ -98,14 +87,19 @@ module Async
 			"\#<#{self.description} (#{@status})>"
 		end
 		
-		# @attr ios [Reactor] The reactor the task was created within.
-		attr :reactor
+		# @deprecated Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
+		def sleep(duration = nil)
+			super
+		end
 		
-		def_delegators :@reactor, :with_timeout, :sleep
+		# @deprecated Replaced by {Scheduler#timeout_after}.
+		def with_timeout(timeout, exception = TimeoutError, message = "execution expired", &block)
+			Fiber.scheduler.timeout_after(timeout, exception, message, &block)
+		end
 		
 		# Yield back to the reactor and allow other fibers to execute.
 		def yield
-			Task.yield{reactor.yield}
+			Fiber.scheduler.yield
 		end
 		
 		# @attr fiber [Fiber] The fiber which is being used for the execution of this task.
@@ -123,14 +117,14 @@ module Async
 			if @status == :initialized
 				@status = :running
 				
-				@fiber.resume(*arguments)
+				schedule(arguments)
 			else
 				raise RuntimeError, "Task already running!"
 			end
 		end
 		
 		def async(*arguments, **options, &block)
-			task = Task.new(@reactor, self, **options, &block)
+			task = Task.new(self, **options, &block)
 			
 			task.run(*arguments)
 			
@@ -138,22 +132,26 @@ module Async
 		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] the final expression/result of the task's block.
+		# @raises[RuntimeError] If the task's fiber is the current fiber.
+		# @returns [Object] The final expression/result of the task's block.
 		def wait
-			raise RuntimeError, "Cannot wait on own fiber" if Fiber.current.equal?(@fiber)
+			raise "Cannot wait on own fiber" if Fiber.current.equal?(@fiber)
 			
 			if running?
 				@finished ||= Condition.new
 				@finished.wait
+			end
+			
+			case @result
+			when Exception
+				raise @result
 			else
-				Task.yield{@result}
+				return @result
 			end
 		end
 		
-		# Deprecated.
-		alias result wait
-		# Soon to become attr :result
+		# Access the result of the task without waiting. May be nil if the task is not completed.
+		attr :result
 		
 		# Stop the task and all of its children.
 		def stop(later = false)
@@ -165,15 +163,15 @@ module Async
 			if self.running?
 				if self.current?
 					if later
-						@reactor << Stop::Later.new(self)
+						Fiber.scheduler.push Stop::Later.new(self)
 					else
 						raise Stop, "Stopping current task!"
 					end
 				elsif @fiber&.alive?
 					begin
-						@fiber.resume(Stop.new)
+						Fiber.scheduler.raise(@fiber, Stop)
 					rescue FiberError
-						@reactor << Stop::Later.new(self)
+						Fiber.scheduler.push Stop::Later.new(self)
 					end
 				end
 			else
@@ -183,14 +181,14 @@ module Async
 		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.
+		# @returns [Task]
+		# @raises[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]
+		# @returns [Task | Nil]
 		def self.current?
 			Thread.current[:async_task]
 		end
@@ -200,13 +198,13 @@ module Async
 		end
 		
 		# Check if the task is running.
-		# @return [Boolean]
+		# @returns [Boolean]
 		def running?
 			@status == :running
 		end
 		
 		# Whether we can remove this node from the reactor graph.
-		# @return [Boolean]
+		# @returns [Boolean]
 		def finished?
 			super && @status != :running
 		end
@@ -246,18 +244,18 @@ module Async
 		end
 		
 		def stop!
-			# logger.debug(self) {"Task was stopped with #{@children&.size.inspect} children!"}
+			# Console.logger.info(self, self.annotation) {"Task was stopped with #{@children&.size.inspect} children!"}
 			@status = :stopped
 			
 			stop_children(true)
 		end
 		
-		def make_fiber(&block)
-			Fiber.new do |*arguments|
+		def schedule(arguments)
+			@fiber = Fiber.new do
 				set!
 				
 				begin
-					@result = yield(self, *arguments)
+					@result = @block.call(self, *arguments)
 					@status = :complete
 					# Console.logger.debug(self) {"Task was completed with #{@children.size} children!"}
 				rescue Stop
@@ -267,10 +265,12 @@ module Async
 				rescue Exception => exception
 					fail!(exception, true)
 				ensure
-					# Console.logger.debug(self) {"Task ensure $!=#{$!} with #{@children.size} children!"}
+					# Console.logger.info(self) {"Task ensure $! = #{$!} with #{@children&.size.inspect} children!"}
 					finish!
 				end
 			end
+			
+			self.root.resume(@fiber)
 		end
 		
 		# Finish the current task, and all bound bound IO objects.
@@ -291,7 +291,6 @@ module Async
 		def set!
 			# This is actually fiber-local:
 			Thread.current[:async_task] = self
-			Console.logger = @logger if @logger
 		end
 	end
 end

data/lib/async/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module Async
-	VERSION = "1.30.2"
+	VERSION = "2.0.0"
 end

data/lib/async/wrapper.rb

@@ -20,220 +20,60 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require 'nio'
-
 module Async
 	# Represents an asynchronous IO within a reactor.
+	# @deprecated With no replacement. Prefer native interfaces.
 	class Wrapper
+		# An exception that occurs when the asynchronous operation was cancelled.
 		class Cancelled < StandardError
-			class From
-				def initialize
-					@backtrace = caller[5..-1]
-				end
-				
-				attr :backtrace
-				
-				def cause
-					nil
-				end
-				
-				def message
-					"Cancelled"
-				end
-			end
-			
-			def initialize
-				super "The operation has been cancelled!"
-				
-				@cause = From.new
-			end
-			
-			attr :cause
 		end
 		
-		# wait_readable, wait_writable and wait_any are not re-entrant, and will raise this failure.
-		class WaitError < StandardError
-			def initialize
-				super "A fiber is already waiting!"
-			end
-		end
-		
-		# @param io the native object to wrap.
-		# @param reactor [Reactor] the reactor that is managing this wrapper, or not specified, it's looked up by way of {Task.current}.
+		# @parameter io the native object to wrap.
+		# @parameter reactor [Reactor] the reactor that is managing this wrapper, or not specified, it's looked up by way of {Task.current}.
 		def initialize(io, reactor = nil)
 			@io = io
-			
 			@reactor = reactor
-			@monitor = nil
 			
-			@readable = nil
-			@writable = nil
-			@any = nil
+			@timeout = nil
 		end
 		
-		def dup
-			self.class.new(@io.dup, @reactor)
-		end
+		attr_accessor :reactor
 		
-		def resume(*arguments)
-			# It's possible that the monitor was closed before calling resume.
-			return unless @monitor
-			
-			readiness = @monitor.readiness
-			
-			if @readable and (readiness == :r or readiness == :rw)
-				@readable.resume(*arguments)
-			end
-			
-			if @writable and (readiness == :w or readiness == :rw)
-				@writable.resume(*arguments)
-			end
-			
-			if @any
-				@any.resume(*arguments)
-			end
+		def dup
+			self.class.new(@io.dup)
 		end
 		
 		# The underlying native `io`.
 		attr :io
 		
-		# The reactor this wrapper is associated with, if any.
-		attr :reactor
-		
-		# The monitor for this wrapper, if any.
-		attr :monitor
-		
-		# 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
-			return if @reactor.equal?(reactor)
-			
-			cancel_monitor
-			
-			@reactor = reactor
+		# Wait for the io to become readable.
+		def wait_readable(timeout = @timeout)
+			@io.to_io.wait_readable(timeout) or raise TimeoutError
 		end
 		
-		# Wait for the io to become readable.
-		def wait_readable(timeout = nil)
-			raise WaitError if @readable
-			
-			self.reactor = Task.current.reactor
-			
-			begin
-				@readable = Fiber.current
-				wait_for(timeout)
-			ensure
-				@readable = nil
-				@monitor.interests = interests if @monitor
-			end
+		# Wait for the io to become writable.
+		def wait_priority(timeout = @timeout)
+			@io.to_io.wait_priority(timeout) or raise TimeoutError
 		end
 		
 		# Wait for the io to become writable.
-		def wait_writable(timeout = nil)
-			raise WaitError if @writable
-			
-			self.reactor = Task.current.reactor
-			
-			begin
-				@writable = Fiber.current
-				wait_for(timeout)
-			ensure
-				@writable = nil
-				@monitor.interests = interests if @monitor
-			end
+		def wait_writable(timeout = @timeout)
+			@io.to_io.wait_writable(timeout) or raise TimeoutError
 		end
 		
 		# Wait fo the io to become either readable or writable.
-		# @param duration [Float] timeout after the given duration if not `nil`.
-		def wait_any(timeout = nil)
-			raise WaitError if @any
-			
-			self.reactor = Task.current.reactor
-			
-			begin
-				@any = Fiber.current
-				wait_for(timeout)
-			ensure
-				@any = nil
-				@monitor.interests = interests if @monitor
-			end
+		# @parameter duration [Float] timeout after the given duration if not `nil`.
+		def wait_any(timeout = @timeout)
+			@io.wait_any(timeout) or raise TimeoutError
 		end
 		
 		# Close the io and monitor.
 		def close
-			cancel_monitor
-			
 			@io.close
 		end
 		
 		def closed?
 			@io.closed?
 		end
-		
-		private
-		
-		# What an abomination.
-		def interests
-			if @any
-				return :rw
-			elsif @readable
-				if @writable
-					return :rw
-				else
-					return :r
-				end
-			elsif @writable
-				return :w
-			end
-			
-			return nil
-		end
-		
-		def cancel_monitor
-			if @readable
-				readable = @readable
-				@readable = nil
-				
-				readable.resume(Cancelled.new)
-			end
-			
-			if @writable
-				writable = @writable
-				@writable = nil
-				
-				writable.resume(Cancelled.new)
-			end
-			
-			if @any
-				any = @any
-				@any = nil
-				
-				any.resume(Cancelled.new)
-			end
-			
-			if @monitor
-				@monitor.close
-				@monitor = nil
-			end
-		end
-		
-		def wait_for(timeout)
-			if @monitor
-				@monitor.interests = interests
-			else
-				@monitor = @reactor.register(@io, interests, self)
-			end
-			
-			# If the user requested an explicit timeout for this operation:
-			if timeout
-				@reactor.with_timeout(timeout) do
-					Task.yield
-				end
-			else
-				Task.yield
-			end
-			
-			return true
-		end
 	end
 end

data/lib/async.rb

@@ -21,15 +21,10 @@
 # THE SOFTWARE.
 
 require_relative "async/version"
-require_relative "async/logger"
 require_relative "async/reactor"
 
 require_relative "kernel/async"
 require_relative "kernel/sync"
 
 module Async
-	# Invoke `Reactor.run` with all arguments/block.
-	def self.run(*arguments, &block)
-		Reactor.run(*arguments, &block)
-	end
 end

data/lib/kernel/async.rb

@@ -24,7 +24,31 @@ require_relative "../async/reactor"
 
 module Kernel
 	# Run the given block of code in a task, asynchronously, creating a reactor if necessary.
-	def Async(*arguments, **options, &block)
-		::Async::Reactor.run(*arguments, **options, &block)
+	#
+	# 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.
+	# - When invoked at the top level, will create and run a reactor, and invoke
+	# the block as an asynchronous task. Will block until the reactor finishes
+	# running.
+	#
+	# @yields {|task| ...} The block that will execute asynchronously.
+	# 	@parameter task [Async::Task] The task that is executing the given block.
+	#
+	# @public Since `stable-v1`.
+	# @asynchronous May block until given block completes executing.
+	def Async(...)
+		if current = ::Async::Task.current?
+			return current.async(...)
+		else
+			reactor = ::Async::Reactor.new
+			
+			begin
+				return reactor.run(...)
+			ensure
+				Fiber.set_scheduler(nil)
+			end
+		end
 	end
 end

data/lib/kernel/sync.rb

@@ -22,16 +22,26 @@
 
 require_relative "../async/reactor"
 
+# Extensions to all Ruby objects.
 module Kernel
 	# Run the given block of code synchronously, but within a reactor if not already in one.
+	#
+	# @yields {|task| ...} The block that will execute asynchronously.
+	# 	@parameter task [Async::Task] The task that is executing the given block.
+	#
+	# @public Since `stable-v1`.
+	# @asynchronous Will block until given block completes executing.
 	def Sync(&block)
 		if task = ::Async::Task.current?
 			yield task
 		else
-			::Async::Reactor.run(
-				finished: ::Async::Condition.new,
-				&block
-			).wait
+			reactor = Async::Reactor.new
+			
+			begin
+				return reactor.run(finished: ::Async::Condition.new, &block).wait
+			ensure
+				Fiber.set_scheduler(nil)
+			end
 		end
 	end
 end