async 1.23.0 → 1.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1dc28a8cd53cda6b82492cf8a1ed3c2a7786f4f6a29da3935be00298e25eaaea
-  data.tar.gz: c70dfa854738d6eccd197f322312ed1ea810378428b08fba18ca24076a5d98d4
+  metadata.gz: 2edec7ff8d1bdb38814250485c36cfe4128a627c81a6976124cb689f9adf144a
+  data.tar.gz: 885288ad542ef4758f3a2b1fe2d5ce2bcd13ff1c71992262927ecca7ee21dbb0
 SHA512:
-  metadata.gz: d305bdc4e707ba26b602809669ba8972017be01b7a599e98c471bf969e434a05b5ef725b3853793f7a82a2e7dc13c89231e383d6b06ffbadb966d77eaa36015a
-  data.tar.gz: 58673e31ac2e10e82062fd2def69e040c7780bf6179eb5092bed365ef3564a61d1553a63b45a151b53b64fe43cea4d7139fe0e844b7755083b13436c0008fd42
+  metadata.gz: 6919a8b9bb8d54dce220024d0c8418a303cb2bb43dbeb6878491a9491c64ab45d953ca83831b6cccfcf6ee12d0db19a47509a981f3841591061e1d3240a75467
+  data.tar.gz: 41f251a4cf7fa2982f974964e6c7cf46d323364c53c34cce367475fe92e252433633967b4cf22a2a2edac40819ab8ec1b03207fe0e5d22febc2d96c1fdf795a8

data/.github/workflows/tests.yml

@@ -11,7 +11,6 @@ jobs:
           # - macos
         
         ruby: 
-          - 2.3
           - 2.4
           - 2.5
           - 2.6

data/README.md

@@ -5,7 +5,7 @@ Async is a composable asynchronous I/O framework for Ruby based on [nio4r] and [
 [timers]: https://github.com/socketry/timers
 [nio4r]: https://github.com/socketry/nio4r
 
-[![Build Status](https://secure.travis-ci.org/socketry/async.svg)](http://travis-ci.org/socketry/async)
+[![Build Status](https://secure.travis-ci.com/socketry/async.svg)](http://travis-ci.com/socketry/async)
 [![Code Climate](https://codeclimate.com/github/socketry/async.svg)](https://codeclimate.com/github/socketry/async)
 [![Coverage Status](https://coveralls.io/repos/socketry/async/badge.svg)](https://coveralls.io/r/socketry/async)
 [![Gitter](https://badges.gitter.im/join.svg)](https://gitter.im/socketry/async)
@@ -192,9 +192,9 @@ Async do |task|
 end
 ```
 
-#### Stopping Reactors
+#### Embedding Reactors
 
-`Async::Reactor#run` will run until the reactor runs out of work to do or is explicitly stopped.
+`Async::Reactor#run` will run until the reactor runs out of work to do. To run a single iteration of the reactor, use `Async::Reactor#run_once`
 
 ```ruby
 require 'async'
@@ -203,13 +203,25 @@ Async.logger.debug!
 reactor = Async::Reactor.new
 
 # Run the reactor for 1 second:
-reactor.run do |task|
+reactor.async do |task|
 	task.sleep 1
-	reactor.stop
+	puts "Finished!"
+end
+
+while reactor.run_once
+	# Round and round we go!
 end
 ```
 
-You can use this approach to embed the reactor in another event loop. `Async::Reactor#stop` is can be called safely from a different thread.
+You can use this approach to embed the reactor in another event loop.
+
+#### Stopping Reactors
+
+`Async::Reactor#stop` will stop the current reactor and all children tasks.
+
+#### Interrupting Reactors
+
+`Async::Reactor#interrupt` can be called safely from a different thread (or signal handler) and will cause the reactor to invoke `#stop`.
 
 ### Resource Management
 

data/lib/async.rb

@@ -26,7 +26,7 @@ require_relative "kernel/async"
 
 module Async
 	# Invoke `Reactor.run` with all arguments/block.
-	def self.run(*args, &block)
-		Reactor.run(*args, &block)
+	def self.run(*arguments, &block)
+		Reactor.run(*arguments, &block)
 	end
 end

data/lib/async/barrier.rb

@@ -23,8 +23,10 @@ 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.
 	class Barrier
-		def initialize
+		def initialize(parent: nil)
 			@tasks = []
+			
+			@parent = parent
 		end
 		
 		# All tasks which have been invoked into the barrier.
@@ -34,8 +36,8 @@ module Async
 			@tasks.size
 		end
 		
-		def async(*args, parent: Task.current, **options, &block)
-			task = parent.async(*args, **options, &block)
+		def async(*arguments, parent: (@parent or Task.current), **options, &block)
+			task = parent.async(*arguments, **options, &block)
 			
 			@tasks << task
 			

data/lib/async/debug/monitor.rb

@@ -31,12 +31,12 @@ module Async
 				@monitor.close
 			end
 			
-			def method_missing(*args, &block)
-				@monitor.send(*args)
+			def method_missing(*arguments, &block)
+				@monitor.send(*arguments)
 			end
 			
-			def respond_to?(*args)
-				@monitor.respond_to?(*args)
+			def respond_to?(*arguments)
+				@monitor.respond_to?(*arguments)
 			end
 			
 			def inspect

data/lib/async/debug/selector.rb

@@ -79,8 +79,8 @@ module Async
 				@selector.close
 			end
 			
-			def select(*args)
-				@selector.select(*args)
+			def select(*arguments)
+				@selector.select(*arguments)
 			end
 		end
 	end

data/lib/async/node.rb

@@ -132,6 +132,10 @@ module Async
 			end
 		end
 		
+		def stop
+			@children&.each(&:stop)
+		end
+		
 		def print_hierarchy(out = $stdout)
 			self.traverse do |node, level|
 				out.puts "#{"\t" * level}#{node}"

data/lib/async/queue.rb

@@ -23,10 +23,11 @@ require_relative 'notification'
 module Async
 	# A queue which allows items to be processed in order.
 	class Queue < Notification
-		def initialize
-			super
+		def initialize(parent: nil)
+			super()
 			
 			@items = []
+			@parent = parent
 		end
 		
 		attr :items
@@ -47,21 +48,26 @@ module Async
 			@items.shift
 		end
 		
-		def async(&block)
-			parent = Task.current
-			
+		def async(parent: (@parent or Task.current), &block)
 			while item = self.dequeue
 				parent.async(item, &block)
 			end
 		end
+		
+		def each
+			while item = self.dequeue
+				yield item
+			end
+		end
 	end
 	
 	class LimitedQueue < Queue
-		def initialize(limit = 1)
-			super()
+		def initialize(limit = 1, **options)
+			super(**options)
 			
 			@limit = limit
-			@full = Async::Queue.new
+			
+			@full = Notification.new
 		end
 		
 		attr :limit
@@ -72,8 +78,8 @@ module Async
 		end
 		
 		def enqueue item
-			if limited?
-				@full.dequeue
+			while limited?
+				@full.wait
 			end
 			
 			super
@@ -82,7 +88,7 @@ module Async
 		def dequeue
 			item = super
 			
-			@full.enqueue(nil) unless @full.empty?
+			@full.signal
 			
 			return item
 		end

data/lib/async/reactor.rb

@@ -42,16 +42,16 @@ module Async
 		# - 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.
-		def self.run(*args, **options, &block)
+		def self.run(*arguments, **options, &block)
 			if current = Task.current?
 				reactor = current.reactor
 				
-				return reactor.async(*args, **options, &block)
+				return reactor.async(*arguments, **options, &block)
 			else
 				reactor = self.new(**options)
 				
 				begin
-					return reactor.run(*args, &block)
+					return reactor.run(*arguments, &block)
 				ensure
 					reactor.close
 				end
@@ -80,7 +80,8 @@ module Async
 			@ready = []
 			@running = []
 			
-			@stopped = true
+			@interrupted = false
+			@guard = Mutex.new
 		end
 		
 		def logger
@@ -88,14 +89,11 @@ module Async
 		end
 		
 		def to_s
-			"\#<#{self.description} (#{@stopped ? 'stopped' : 'running'})>"
+			"\#<#{self.description} #{@children&.size || 0} children #{stopped? ? 'stopped' : 'running'}>"
 		end
 		
-		# @attr stopped [Boolean]
-		attr :stopped
-		
 		def stopped?
-			@stopped
+			@children.nil? || @children.empty?
 		end
 		
 		# TODO Remove these in next major release. They are too confusing to use correctly.
@@ -109,7 +107,7 @@ module Async
 		#
 		# @yield [Task] Executed within the task.
 		# @return [Task] The task that was scheduled into the reactor.
-		def async(*args, **options, &block)
+		def async(*arguments, **options, &block)
 			task = Task.new(self, **options, &block)
 			
 			# I want to take a moment to explain the logic of this.
@@ -119,7 +117,7 @@ module Async
 			# - Fail at the point of the method call where possible.
 			# - Execute determinstically where possible.
 			# - Avoid scheduler overhead if no blocking operation is performed.
-			task.run(*args)
+			task.run(*arguments)
 			
 			# logger.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..."
 			return task
@@ -132,12 +130,13 @@ module Async
 			return monitor
 		end
 		
-		# Stop the reactor at the earliest convenience. Can be called from a different thread safely.
-		# @return [void]
-		def stop
-			unless @stopped
-				@stopped = true
-				@selector.wakeup
+		# Interrupt the reactor at the earliest convenience. Can be called from a different thread safely.
+		def interrupt
+			@guard.synchronize do
+				unless @interrupted
+					@interrupted = true
+					@selector.wakeup
+				end
 			end
 		end
 		
@@ -155,73 +154,95 @@ module Async
 		end
 		
 		def finished?
-			# I'm not sure if checking `@running.empty?` is really required.
+			# TODO I'm not sure if checking `@running.empty?` is really required.
 			super && @ready.empty? && @running.empty?
 		end
 		
-		# Run the reactor until either all tasks complete or {#stop} is invoked.
-		# Proxies arguments to {#async} immediately before entering the loop.
-		def run(*args, &block)
-			raise RuntimeError, 'Reactor has been closed' if @selector.nil?
+		# Run one iteration of the event loop.
+		# @param timeout [Float | nil] the maximum timeout, or if nil, indefinite.
+		# @return [Boolean] whether there is more work to do.
+		def run_once(timeout = nil)
+			logger.debug(self) {"@ready = #{@ready} @running = #{@running}"}
 			
-			@stopped = false
-			
-			initial_task = self.async(*args, &block) if block_given?
-			
-			until @stopped
-				logger.debug(self) {"@ready = #{@ready} @running = #{@running}"}
+			if @ready.any?
+				# running used to correctly answer on `finished?`, and to reuse Array object.
+				@running, @ready = @ready, @running
 				
-				if @ready.any?
-					# running used to correctly answer on `finished?`, and to reuse Array object.
-					@running, @ready = @ready, @running
-					
-					@running.each do |fiber|
-						fiber.resume if fiber.alive?
-					end
-					
-					@running.clear
+				@running.each do |fiber|
+					fiber.resume if fiber.alive?
 				end
 				
-				if @ready.empty?
-					interval = @timers.wait_interval
-				else
-					# if there are tasks ready to execute, don't sleep:
-					interval = 0
+				@running.clear
+			end
+			
+			if @ready.empty?
+				interval = @timers.wait_interval
+			else
+				# if there are tasks ready to execute, don't sleep:
+				interval = 0
+			end
+			
+			# If there is no interval to wait (thus no timers), and no tasks, we could be done:
+			if interval.nil?
+				if self.finished?
+					# If there is nothing to do, then finish:
+					return false
 				end
 				
-				# If there is no interval to wait (thus no timers), and no tasks, we could be done:
-				if interval.nil?
-					if self.finished?
-						# If there is nothing to do, then finish:
-						return initial_task
-					end
-				elsif interval < 0
-					# We have timers ready to fire, don't sleep in the selctor:
-					interval = 0
+				# Allow the user to specify a maximum interval if we would otherwise be sleeping indefinitely:
+				interval = timeout
+			elsif interval < 0
+				# We have timers ready to fire, don't sleep in the selctor:
+				interval = 0
+			elsif timeout and interval > timeout
+				interval = timeout
+			end
+			
+			logger.debug(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
 				end
-				
-				logger.debug(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
-					end
+			end
+			
+			@timers.fire
+			
+			# We check and clear the interrupted flag here:
+			if @interrupted
+				@guard.synchronize do
+					@interrupted = false
 				end
 				
-				@timers.fire
+				self.stop
+				
+				return false
+			end
+			
+			return true
+		end
+		
+		# Run the reactor until either all tasks complete or {#pause} or {#stop} is
+		# invoked. Proxies arguments to {#async} immediately before entering the
+		# loop, if a block is provided.
+		def run(*arguments, &block)
+			raise RuntimeError, 'Reactor has been closed' if @selector.nil?
+			
+			initial_task = self.async(*arguments, &block) if block_given?
+			
+			while self.run_once
+				# Round and round we go!
 			end
 			
 			return initial_task
 		ensure
 			logger.debug(self) {"Exiting run-loop because #{$! ? $! : 'finished'}."}
-			
-			@stopped = true
 		end
-	
+		
 		# Stop each of the children tasks and close the selector.
 		# 
 		# @return [void]
 		def close
-			@children&.each(&:stop)
+			self.stop
 			
 			# TODO Should we also clear all timers?
 			@selector.close
@@ -267,12 +288,5 @@ module Async
 		ensure
 			timer.cancel if timer
 		end
-		
-		# TODO remove
-		def timeout(*args, &block)
-			warn "#{self.class}\#timeout(...) is deprecated, use #{self.class}\#with_timeout(...) instead."
-			
-			with_timeout(*args, &block)
-		end
 	end
 end

data/lib/async/semaphore.rb

@@ -21,10 +21,12 @@
 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.
 	class Semaphore
-		def initialize(limit = 1)
+		def initialize(limit = 1, parent: nil)
 			@count = 0
 			@limit = limit
 			@waiting = []
+			
+			@parent = parent
 		end
 		
 		# The current number of tasks that have acquired the semaphore.
@@ -47,14 +49,14 @@ module Async
 		end
 		
 		# Run an async task. Will wait until the semaphore is ready until spawning and running the task.
-		def async(*args, parent: Task.current, **options)
+		def async(*arguments, parent: (@parent or Task.current), **options)
 			wait
 			
 			parent.async(**options) do |task|
 				@count += 1
 				
 				begin
-					yield task, *args
+					yield task, *arguments
 				ensure
 					self.release
 				end

data/lib/async/task.rb

@@ -112,19 +112,20 @@ module Async
 		attr :status
 		
 		# Begin the execution of the task.
-		def run(*args)
+		def run(*arguments)
 			if @status == :initialized
 				@status = :running
-				@fiber.resume(*args)
+				
+				@fiber.resume(*arguments)
 			else
 				raise RuntimeError, "Task already running!"
 			end
 		end
 		
-		def async(*args, **options, &block)
+		def async(*arguments, **options, &block)
 			task = Task.new(@reactor, self, **options, &block)
 			
-			task.run(*args)
+			task.run(*arguments)
 			
 			return task
 		end
@@ -248,11 +249,11 @@ module Async
 		end
 		
 		def make_fiber(&block)
-			Fiber.new do |*args|
+			Fiber.new do |*arguments|
 				set!
 				
 				begin
-					@result = yield(self, *args)
+					@result = yield(self, *arguments)
 					@status = :complete
 					# logger.debug(self) {"Task was completed with #{@children.size} children!"}
 				rescue Stop

data/lib/async/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Async
-	VERSION = "1.23.0"
+	VERSION = "1.24.0"
 end

data/lib/async/wrapper.rb

@@ -73,22 +73,22 @@ module Async
 			self.class.new(@io.dup, @reactor)
 		end
 		
-		def resume(*args)
+		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(*args)
+				@readable.resume(*arguments)
 			end
 			
 			if @writable and (readiness == :w or readiness == :rw)
-				@writable.resume(*args)
+				@writable.resume(*arguments)
 			end
 			
 			if @any
-				@any.resume(*args)
+				@any.resume(*arguments)
 			end
 		end
 		

data/lib/kernel/async.rb

@@ -22,7 +22,7 @@ require_relative "../async/reactor"
 
 module Kernel
 	# Run the given block of code in a task, asynchronously, creating a reactor if necessary.
-	def Async(*args, &block)
-		::Async::Reactor.run(*args, &block)
+	def Async(*arguments, &block)
+		::Async::Reactor.run(*arguments, &block)
 	end
 end

data/spec/async/barrier_spec.rb

@@ -24,6 +24,8 @@ require 'async/rspec'
 
 require 'async/semaphore'
 
+require_relative 'chainable_async_examples'
+
 RSpec.describe Async::Barrier do
 	include_context Async::RSpec::Reactor
 	
@@ -107,4 +109,6 @@ RSpec.describe Async::Barrier do
 			subject.wait
 		end
 	end
+	
+	it_behaves_like 'chainable async'
 end

data/spec/async/chainable_async_examples.rb

@@ -0,0 +1,12 @@
+
+RSpec.shared_examples 'chainable async' do
+	let(:parent) {double}
+	subject {described_class.new(parent: parent)}
+	
+	it 'should chain async to parent' do
+		expect(parent).to receive(:async)
+		
+		subject.async do
+		end
+	end
+end

data/spec/async/queue_spec.rb

@@ -21,8 +21,10 @@
 require 'async'
 require 'async/queue'
 require 'async/rspec'
+require 'async/semaphore'
 
 require_relative 'condition_examples'
+require_relative 'chainable_async_examples'
 
 RSpec.shared_context Async::Queue do
 	it 'should process items in order' do
@@ -48,6 +50,41 @@ RSpec.shared_context Async::Queue do
 			expect(item).to be 1
 		end
 	end
+	
+	context 'with semaphore' do
+		let(:capacity) {2}
+		let(:semaphore) {Async::Semaphore.new(capacity)}
+		let(:repeats) {capacity * 2}
+		
+		it 'should process several items limited by a semaphore' do
+			count = 0
+			
+			Async do
+				repeats.times do
+					subject.enqueue :item
+				end
+				
+				subject.enqueue nil
+			end
+			
+			subject.async(parent: semaphore) do |task|
+				count += 1
+			end
+			
+			expect(count).to be == repeats
+		end
+	end
+	
+	it_behaves_like 'chainable async' do
+		before do
+			subject.enqueue(:item)
+			
+			# The limited queue may block.
+			Async do
+				subject.enqueue(nil)
+			end
+		end
+	end
 end
 
 RSpec.describe Async::Queue do

data/spec/async/reactor_spec.rb

@@ -19,6 +19,8 @@
 # THE SOFTWARE.
 
 require 'async'
+require 'async/rspec/reactor'
+
 require 'benchmark/ips'
 
 RSpec.describe Async::Reactor do
@@ -45,8 +47,39 @@ RSpec.describe Async::Reactor do
 		end
 	end
 	
+	describe '#run_once' do
+		it "can run the reactor" do
+			# Run the reactor for 1 second:
+			task = subject.async do |task|
+				task.yield
+			end
+			
+			expect(task).to be_running
+			
+			# This will resume the task, and then the reactor will be finished.
+			expect(subject.run_once).to be false
+			
+			expect(task).to be_finished
+		end
+		
+		it "can run one iteration" do
+			state = nil
+	
+			subject.async do |task|
+				state = :started
+				task.yield
+				state = :finished
+			end
+	
+			expect(state).to be :started
+	
+			subject.run_once
+			expect(state).to be :finished
+		end
+	end
+	
 	describe '#stop' do
-		it "can be stop reactor" do
+		it "can stop the reactor" do
 			state = nil
 			
 			subject.async do |task|

data/spec/async/semaphore_spec.rb

@@ -22,6 +22,8 @@ require 'async/semaphore'
 require 'async/barrier'
 require 'async/rspec'
 
+require_relative 'chainable_async_examples'
+
 RSpec.describe Async::Semaphore do
 	include_context Async::RSpec::Reactor
 	
@@ -160,4 +162,6 @@ RSpec.describe Async::Semaphore do
 			barrier.wait
 		end
 	end
+	
+	it_behaves_like 'chainable async'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 1.23.0
+  version: 1.24.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-15 00:00:00.000000000 Z
+date: 2019-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nio4r
@@ -132,7 +132,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".editorconfig"
-- ".github/FUNDING.yml"
 - ".github/workflows/tests.yml"
 - ".gitignore"
 - ".rspec"
@@ -181,6 +180,7 @@ files:
 - 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
@@ -218,12 +218,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Async is an asynchronous I/O framework based on nio4r.
 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

data/.github/FUNDING.yml

@@ -1,4 +0,0 @@
-# These are supported funding model platforms
-
-# github: ioquatix
-custom: https://github.com/socketry/community/#funding