async 1.25.2 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 81b7571d3f6ac5ce2ade98ca74b0440581178c8cb74503553d5a6dc70956a6fb
-  data.tar.gz: f5aeea0f0a482f52e98c5064bd9678aed1f9b8e4868ad2d5bf7a79c009f53275
+  metadata.gz: e7dacbad60b89b492fe3741aa5f61240c8bc1f2d9f23e242c7eadd80cc7d9d38
+  data.tar.gz: a8193d5ec289670c5ca4a795e905ffd660aa57edaac8796e58c3db8b866fa340
 SHA512:
-  metadata.gz: 9a513e4b8f4efb35cd0438801c2e0dc6896b9f11f911e8cc547a15c22043d28adeb257d47de2d326513095cf813ab88fd9c1aec8c7c7daffef85a8c7238da7f9
-  data.tar.gz: 84e46d9e07977de42c79297f0c1decf62957497ed6688bdc65b687fee21b26127c7e553c64d09d5e4dcf405dcc46d468b22e689bfb6e69dfac4c541b9608459f
+  metadata.gz: de1a9942175a329082d388b280d63c80f614a99145d0df8b6b39e7a4b31d2cb7af4a91bad643f408eeebe6b72807d3f50093528aa5bac273daef67cbb25b3b97
+  data.tar.gz: 206be83fe80c466b12669ad847b041e60f27c21d32f82995e7350385f50d990abe94cfbd701a86717532936d7b6ad1e495df78f45a3c0972e2c70b6647824528

data/lib/async/barrier.rb

@@ -23,7 +23,7 @@
 require_relative 'task'
 
 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 barrier is used to synchronize multiple tasks, waiting for them all to complete before continuing.
 	class Barrier
 		def initialize(parent: nil)
 			@tasks = []

data/lib/async/clock.rb

@@ -21,7 +21,7 @@
 # THE SOFTWARE.
 
 module Async
-	module Clock
+	class Clock
 		# Get the current elapsed monotonic time.
 		def self.now
 			::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
@@ -35,5 +35,37 @@ module Async
 			
 			return self.now - start_time
 		end
+		
+		def self.start
+			self.new.tap(&:start!)
+		end
+		
+		def initialize(total = 0)
+			@total = total
+			@started = nil
+		end
+		
+		def start!
+			@started ||= Clock.now
+		end
+		
+		def stop!
+			if @started
+				@total += (Clock.now - @started)
+				@started = nil
+			end
+			
+			return @total
+		end
+		
+		def total
+			total = @total
+			
+			if @started
+				total += (Clock.now - @started)
+			end
+			
+			return total
+		end
 	end
 end

data/lib/async/logger.rb

@@ -24,10 +24,5 @@ require 'console'
 require_relative 'task'
 
 module Async
-	# @return the current logger, either the active tasks logger, or the global event console logger.
-	def self.logger
-		if task = Task.current?
-			task.logger
-		end || Console.logger
-	end
+	extend Console
 end

data/lib/async/node.rb

@@ -217,6 +217,10 @@ module Async
 			end
 		end
 		
+		def backtrace(*arguments)
+			nil
+		end
+		
 		def to_s
 			"\#<#{description}>"
 		end
@@ -297,9 +301,23 @@ module Async
 			@children&.each(&:stop)
 		end
 		
-		def print_hierarchy(out = $stdout)
+		def print_hierarchy(out = $stdout, backtrace: true)
 			self.traverse do |node, level|
-				out.puts "#{"\t" * level}#{node}"
+				indent = "\t" * level
+				
+				out.puts "#{indent}#{node}"
+				
+				print_backtrace(out, indent, node) if backtrace
+			end
+		end
+		
+		private
+		
+		def print_backtrace(out, indent, node)
+			if backtrace = node.backtrace
+				backtrace.each_with_index do |line, index|
+					out.puts "#{indent}#{index.zero? ? "→ " : "  "}#{line}"
+				end
 			end
 		end
 	end

data/lib/async/queue.rb

@@ -34,7 +34,11 @@ module Async
 		
 		attr :items
 		
-		def enqueue item
+		def empty?
+			@items.empty?
+		end
+		
+		def enqueue(item)
 			@items.push(item)
 			
 			self.signal unless self.empty?

data/lib/async/reactor.rb

@@ -23,6 +23,7 @@
 require_relative 'logger'
 require_relative 'task'
 require_relative 'wrapper'
+require_relative 'scheduler'
 
 require 'nio'
 require 'timers'
@@ -50,10 +51,10 @@ module Async
 				
 				return reactor.async(*arguments, **options, &block)
 			else
-				reactor = self.new(**options)
+				reactor = self.new
 				
 				begin
-					return reactor.run(*arguments, &block)
+					return reactor.run(*arguments, **options, &block)
 				ensure
 					reactor.close
 				end
@@ -82,12 +83,60 @@ module Async
 			@ready = []
 			@running = []
 			
+			if Scheduler.supported?
+				@scheduler = Scheduler.new(self)
+			else
+				@scheduler = nil
+			end
+			
 			@interrupted = false
 			@guard = Mutex.new
+			@blocked = 0
+			@unblocked = []
+		end
+		
+		attr :scheduler
+		
+		# @reentrant Not thread safe.
+		def block(blocker, timeout)
+			fiber = Fiber.current
+			
+			if timeout
+				timer = self.after(timeout) do
+					if fiber.alive?
+						fiber.resume(false)
+					end
+				end
+			end
+			
+			begin
+				@blocked += 1
+				Fiber.yield
+			ensure
+				@blocked -= 1
+			end
+		ensure
+			timer&.cancel
+		end
+		
+		# @reentrant Thread safe.
+		def unblock(blocker, fiber)
+			@guard.synchronize do
+				@unblocked << fiber
+				@selector.wakeup
+			end
+		end
+		
+		def fiber(&block)
+			if @scheduler
+				Fiber.new(blocking: false, &block)
+			else
+				Fiber.new(&block)
+			end
 		end
 		
 		def logger
-			@logger ||= Console.logger
+			@logger || Console.logger
 		end
 		
 		def to_s
@@ -98,9 +147,6 @@ module Async
 			@children.nil?
 		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
 		# executed until the first blocking call, at which point it will yield and
 		# and this method will return.
@@ -157,7 +203,7 @@ module Async
 		
 		def finished?
 			# TODO I'm not sure if checking `@running.empty?` is really required.
-			super && @ready.empty? && @running.empty?
+			super && @ready.empty? && @running.empty? && @blocked.zero?
 		end
 		
 		# Run one iteration of the event loop.
@@ -177,6 +223,18 @@ module Async
 				@running.clear
 			end
 			
+			unless @blocked.zero?
+				unblocked = Array.new
+				
+				@guard.synchronize do
+					unblocked, @unblocked = @unblocked, unblocked
+				end
+				
+				while fiber = unblocked.pop
+					fiber.resume if fiber.alive?
+				end
+			end
+			
 			if @ready.empty?
 				interval = @timers.wait_interval
 			else
@@ -200,7 +258,7 @@ module Async
 				interval = timeout
 			end
 			
-			# logger.debug(self) {"Selecting with #{@children&.size} children with interval = #{interval ? interval.round(2) : 'infinite'}..."}
+			# logger.info(self) {"Selecting with #{@children&.size} children with interval = #{interval ? interval.round(2) : 'infinite'}..."}
 			if monitors = @selector.select(interval)
 				monitors.each do |monitor|
 					monitor.value.resume
@@ -223,10 +281,12 @@ module Async
 		end
 		
 		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.
-		def run(*arguments, &block)
+		def run(*arguments, **options, &block)
 			raise RuntimeError, 'Reactor has been closed' if @selector.nil?
 			
-			initial_task = self.async(*arguments, &block) if block_given?
+			@scheduler&.set!
+			
+			initial_task = self.async(*arguments, **options, &block) if block_given?
 			
 			while self.run_once
 				# Round and round we go!
@@ -234,6 +294,7 @@ module Async
 			
 			return initial_task
 		ensure
+			@scheduler&.clear!
 			logger.debug(self) {"Exiting run-loop because #{$! ? $! : 'finished'}."}
 		end
 		
@@ -266,7 +327,7 @@ module Async
 		def sleep(duration)
 			fiber = Fiber.current
 			
-			timer = self.after(duration) do
+			timer = @timers.after(duration) do
 				if fiber.alive?
 					fiber.resume
 				end
@@ -283,7 +344,7 @@ module Async
 		def with_timeout(timeout, exception = TimeoutError)
 			fiber = Fiber.current
 			
-			timer = self.after(timeout) do
+			timer = @timers.after(timeout) do
 				if fiber.alive?
 					error = exception.new("execution expired")
 					fiber.resume error

data/lib/async/scheduler.rb

@@ -0,0 +1,112 @@
+# Copyright, 2020, 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 'clock'
+
+module Async
+	class Scheduler
+		if Fiber.respond_to?(:set_scheduler)
+			def self.supported?
+				true
+			end
+		else
+			def self.supported?
+				false
+			end
+		end
+		
+		def initialize(reactor)
+			@reactor = reactor
+			@wrappers = nil
+		end
+		
+		def set!
+			@wrappers = {}
+			Fiber.set_scheduler(self)
+		end
+		
+		def clear!
+			# Because these instances are created with `autoclose: false`, this does not close the underlying file descriptor:
+			# @ios&.each_value(&:close)
+			
+			@wrappers = nil
+			Fiber.set_scheduler(nil)
+		end
+		
+		private def from_io(io)
+			@wrappers[io] ||= Wrapper.new(io, @reactor)
+		end
+		
+		def io_wait(io, events, timeout = nil)
+			wrapper = from_io(io)
+			
+			if events == IO::READABLE
+				if wrapper.wait_readable(timeout)
+					return IO::READABLE
+				end
+			elsif events == IO::WRITABLE
+				if wrapper.wait_writable(timeout)
+					return IO::WRITABLE
+				end
+			else
+				if wrapper.wait_any(timeout)
+					return events
+				end
+			end
+			
+			return false
+		ensure
+			wrapper.reactor = nil
+		end
+		
+		# Wait for the specified process ID to exit.
+		# @parameter pid [Integer] The process ID to wait for.
+		# @parameter flags [Integer] A bit-mask of flags suitable for `Process::Status.wait`.
+		# @returns [Process::Status] A process status instance.
+		def process_wait(pid, flags)
+			Thread.new do
+				Process::Status.wait(pid, flags)
+			end.value
+		end
+		
+		def kernel_sleep(duration)
+			@reactor.sleep(duration)
+		end
+		
+		def block(blocker, timeout)
+			@reactor.block(blocker, timeout)
+		end
+		
+		def unblock(blocker, fiber)
+			@reactor.unblock(blocker, fiber)
+		end
+		
+		def close
+		end
+		
+		def fiber(&block)
+			task = Task.new(&block)
+			
+			task.resume
+			
+			return task.fiber
+		end
+	end
+end

data/lib/async/task.rb

@@ -86,17 +86,24 @@ module Async
 			@fiber = make_fiber(&block)
 		end
 		
+		if Fiber.current.respond_to?(:backtrace)
+			def backtrace(*arguments)
+				@fiber.backtrace(*arguments)
+			end
+		end
+		
 		def to_s
 			"\#<#{self.description} (#{@status})>"
 		end
 		
 		def logger
-			@logger ||= @parent&.logger
+			@logger || Console.logger
 		end
 		
 		# @attr ios [Reactor] The reactor the task was created within.
 		attr :reactor
-		def_delegators :@reactor, :with_timeout, :timeout, :sleep
+		
+		def_delegators :@reactor, :with_timeout, :sleep
 		
 		# Yield back to the reactor and allow other fibers to execute.
 		def yield
@@ -226,7 +233,7 @@ 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.
-		# 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 `Async::Task` behave more like a promise, and you would need to ensure that someone calls `Task#result` otherwise you might miss important errors.
+		# 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
@@ -289,6 +296,7 @@ module Async
 		def set!
 			# This is actually fiber-local:
 			Thread.current[:async_task] = self
+			Console.logger = @logger if @logger
 		end
 	end
 end