async 1.31.0 → 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
@@ -40,25 +43,6 @@ module Async
 		# The tasks waiting on this semaphore.
 		attr :waiting
 		
-		# Allow setting the limit. This is useful for cases where the semaphore is used to limit the number of concurrent tasks, but the number of tasks is not known in advance or needs to be modified.
-		#
-		# On increasing the limit, some tasks may be immediately resumed. On decreasing the limit, some tasks may execute until the count is < than the limit. 
-		#
-		# @parameter limit [Integer] The new limit.
-		def limit= limit
-			difference = limit - @limit
-			@limit = limit
-			
-			# We can't suspend 
-			if difference > 0
-				difference.times do
-					break unless fiber = @waiting.shift
-					
-					fiber.resume
-				end
-			end
-		end
-		
 		# Is the semaphore currently acquired?
 		def empty?
 			@count.zero?
@@ -86,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
 			
@@ -108,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
@@ -121,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
@@ -230,35 +228,34 @@ module Async
 		private
 		
 		# This is a very tricky aspect of tasks to get right. I've modelled it after `Thread` but it's slightly different in that the exception can propagate back up through the reactor. If the user writes code which raises an exception, that exception should always be visible, i.e. cause a failure. If it's not visible, such code fails silently and can be very difficult to debug.
-		def fail!(exception = false, propagate = true)
+		# As an explcit choice, the user can start a task which doesn't propagate exceptions. This only applies to `StandardError` and derived tasks. This allows tasks to internally capture their error state which is raised when invoking `Task#result` similar to how `Thread#join` works. This mode makes {ruby Async::Task} behave more like a promise, and you would need to ensure that someone calls `Task#result` otherwise you might miss important errors.
+		def fail!(exception = nil, propagate = true)
 			@status = :failed
 			@result = exception
 			
-			if exception
-				if propagate
-					raise exception
-				elsif @finished.nil?
-					# If no one has called wait, we log this as a warning:
-					Console.logger.warn(self, "Task may have ended with unhandled exception.", exception)
-				else
-					Console.logger.debug(self, exception)
-				end
+			if propagate
+				raise
+			elsif @finished.nil?
+				# If no one has called wait, we log this as an error:
+				Console.logger.error(self) {$!}
+			else
+				Console.logger.debug(self) {$!}
 			end
 		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
@@ -268,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.
@@ -292,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.31.0"
+	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