async 1.26.1 → 1.28.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af5004e8d05722b3187b65bad44d03c64514cef04b3ea84f604f2491b04c9441
-  data.tar.gz: 3e00948623889a9a584767a5678b55d474b4015603da9031eea4ab420bea80e0
+  metadata.gz: a043ccb6378ff70b23eff7218723e910af5828508241e4ca87bb59669eee5990
+  data.tar.gz: c1891f280b416fd092caa8e54473697856718d55a820dc784ad3026ba301c4b7
 SHA512:
-  metadata.gz: eb57c398f8f778ded45849d98412106133bd68294eeee34e734144b1792b63c1c7f4da9087cf36ed14d385efacd730a4e461f029ba22503a89efa56debd7dc5c
-  data.tar.gz: d81812db0ca0f6ad8d81d6582ce82d6b1e210b437a6614d825ad0bc1be4cb200f2f3c930df51f6fc963b82e0c98bfc757fe339646a9227d6dacfab06e70b469e
+  metadata.gz: 61abcad6fc07e331c6eaba134865e329964b7c8c87f23338e4f8ce39dd250fa2c9719e83eb74a55c284ada13873f5ad996ba68162c131be2a933b67a124d17ed
+  data.tar.gz: b5039970211fec3361ee6bf8044be988771a968a7f43ca8f20d3a4eea95234fc45fbc78f395b8ff2a9cb77407865915102ca38936b57c875fa1b07848050cae3

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,6 +34,10 @@ module Async
 		
 		attr :items
 		
+		def size
+			@items.size
+		end
+
 		def empty?
 			@items.empty?
 		end

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'
@@ -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
@@ -226,6 +284,8 @@ module Async
 		def run(*arguments, **options, &block)
 			raise RuntimeError, 'Reactor has been closed' if @selector.nil?
 			
+			@scheduler&.set!
+			
 			initial_task = self.async(*arguments, **options, &block) if block_given?
 			
 			while self.run_once
@@ -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

data/lib/async/version.rb

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

metadata

@@ -1,57 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.26.1
+  version: 1.28.2
 platform: ruby
 authors:
 - Samuel Williams
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-14 00:00:00.000000000 Z
+date: 2020-12-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nio4r
+  name: console
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '1.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '1.10'
 - !ruby/object:Gem::Dependency
-  name: timers
+  name: nio4r
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '2.3'
 - !ruby/object:Gem::Dependency
-  name: console
+  name: timers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '4.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: async-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -67,19 +67,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.1'
 - !ruby/object:Gem::Dependency
-  name: covered
+  name: bake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -95,68 +109,39 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: covered
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '0.10'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '0.10'
 - !ruby/object:Gem::Dependency
-  name: bake-bundler
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: "\t\tAsync is a modern concurrency framework for Ruby. It implements
-  the\n\t\treactor pattern, providing both non-blocking I/O and timer events.\n"
+        version: '3.6'
+description:
 email:
-- samuel.williams@oriontransfer.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".editorconfig"
-- ".github/workflows/development.yml"
-- ".gitignore"
-- ".rspec"
-- ".yardopts"
-- Gemfile
-- Guardfile
-- README.md
-- Rakefile
-- async.gemspec
-- bake.rb
-- benchmark/async_vs_lightio.rb
-- benchmark/fiber_count.rb
-- benchmark/rubies/README.md
-- benchmark/rubies/benchmark.rb
-- benchmark/thread_count.rb
-- benchmark/thread_vs_fiber.rb
-- examples/async_method.rb
-- examples/callback/loop.rb
-- examples/capture/README.md
-- examples/capture/capture.rb
-- examples/fibers.rb
-- examples/queue/producer.rb
-- examples/sleep_sort.rb
-- examples/stop/condition.rb
-- examples/stop/sleep.rb
-- gems/event.gemfile
 - lib/async.rb
 - lib/async/barrier.rb
 - lib/async/clock.rb
@@ -168,41 +153,18 @@ files:
 - lib/async/notification.rb
 - lib/async/queue.rb
 - lib/async/reactor.rb
+- lib/async/scheduler.rb
 - lib/async/semaphore.rb
 - lib/async/task.rb
 - lib/async/version.rb
 - lib/async/wrapper.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb
-- logo.png
-- logo.svg
-- papers/1982 Grossman.pdf
-- papers/1987 ODell.pdf
-- spec/async/barrier_spec.rb
-- spec/async/chainable_async_examples.rb
-- spec/async/clock_spec.rb
-- spec/async/condition_examples.rb
-- spec/async/condition_spec.rb
-- spec/async/logger_spec.rb
-- spec/async/node_spec.rb
-- spec/async/notification_spec.rb
-- spec/async/performance_spec.rb
-- spec/async/queue_spec.rb
-- spec/async/reactor/nested_spec.rb
-- spec/async/reactor_spec.rb
-- spec/async/semaphore_spec.rb
-- spec/async/task_spec.rb
-- spec/async/wrapper_spec.rb
-- spec/async_spec.rb
-- spec/enumerator_spec.rb
-- spec/kernel/async_spec.rb
-- spec/kernel/sync_spec.rb
-- spec/spec_helper.rb
 homepage: https://github.com/socketry/async
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -217,28 +179,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.2.3
+signing_key:
 specification_version: 4
-summary: Async is a concurrency framework for Ruby.
-test_files:
-- spec/async/barrier_spec.rb
-- spec/async/chainable_async_examples.rb
-- spec/async/clock_spec.rb
-- spec/async/condition_examples.rb
-- spec/async/condition_spec.rb
-- spec/async/logger_spec.rb
-- spec/async/node_spec.rb
-- spec/async/notification_spec.rb
-- spec/async/performance_spec.rb
-- spec/async/queue_spec.rb
-- spec/async/reactor/nested_spec.rb
-- spec/async/reactor_spec.rb
-- spec/async/semaphore_spec.rb
-- spec/async/task_spec.rb
-- spec/async/wrapper_spec.rb
-- spec/async_spec.rb
-- spec/enumerator_spec.rb
-- spec/kernel/async_spec.rb
-- spec/kernel/sync_spec.rb
-- spec/spec_helper.rb
+summary: A concurrency framework for Ruby.
+test_files: []