async 1.32.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ed31b6b8b115f7013a59e0eb58fd10793c061a8be9968f83fc3d8ee750e92c8
-  data.tar.gz: a7517e133ad3f944067399f2b9f9dd3e7753fb82cd4912424dd0690f17eebd3d
+  metadata.gz: 6e5f7f4cbc1cfc595409b58cfc0b74e2a2767837fc40bae5e1a1b60e7dcd3384
+  data.tar.gz: 4eeb27d8248bc7993cf7758e41c8ffee3a54141d7c521e2a2805bbc8e8be3edd
 SHA512:
-  metadata.gz: 4819e554eec0bc91973791b6d87042638658f54e372ee11f32dd11c7c319d28cf9a08745f7f2a1af04ca0f20cff7a5c29174fcb7fddcc78a56a44f1499385a39
-  data.tar.gz: 2e777449edd348c2db0dc0a50d756981cd5e0a2e5d9f709e1f0dbbc609e39e4e840b86258d0a1a744473855cbec8539b3398b91e01133128a84721c77bfc0e6d
+  metadata.gz: d0b59a751dd4ea8cd7f2a83ad76fbf4dcff30ca11629d2e7f6ba18e017cf5de06880c1a6b19a3297967793e80394e10f8873ed24aa278d2019b11eb90a002394
+  data.tar.gz: 1c23c709f983bc14ba1477b41b3ca7533275eb3464928c7d4d564e897fc2fb893617cde7bb6d1e90d050db9bbc1d1d2ed71c87da02e61cd559f0afef363fc567

data/lib/async/barrier.md

@@ -0,0 +1,36 @@
+A synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
+
+## Example
+
+~~~ ruby
+require 'async'
+require 'async/barrier'
+
+Sync do
+	barrier = Async::Barrier.new
+	
+	# Generate an array of 10 numbers:
+	numbers = 10.times.map{rand(10)}
+	sorted = []
+	
+	# Sleep sort the numbers:
+	numbers.each do |number|
+		barrier.async do |task|
+			task.sleep(number)
+			sorted << number
+		end
+	end
+	
+	# Wait for all the numbers to be sorted:
+	barrier.wait
+	
+	Console.logger.info("Sorted", sorted)
+end
+~~~
+
+### Output
+
+~~~
+0.0s     info: Sorted [ec=0x104] [pid=50291]
+						 | [0, 0, 0, 0, 1, 2, 2, 3, 6, 6]
+~~~

data/lib/async/barrier.rb

@@ -23,8 +23,12 @@
 require_relative 'task'
 
 module Async
-	# A barrier is used to synchronize multiple tasks, waiting for them all to complete before continuing.
+	# A synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore}.
+	# @public Since `stable-v1`.
 	class Barrier
+		# Initialize the barrier.
+		# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
+		# @public Since `stable-v1`.
 		def initialize(parent: nil)
 			@tasks = []
 			
@@ -34,10 +38,13 @@ module Async
 		# All tasks which have been invoked into the barrier.
 		attr :tasks
 		
+		# The number of tasks currently held by the barrier.
 		def size
 			@tasks.size
 		end
 		
+		# Execute a child task and add it to the barrier.
+		# @asynchronous Executes the given block concurrently.
 		def async(*arguments, parent: (@parent or Task.current), **options, &block)
 			task = parent.async(*arguments, **options, &block)
 			
@@ -46,6 +53,8 @@ module Async
 			return task
 		end
 		
+		# Whether there are any tasks being held by the barrier.
+		# @returns [Boolean]
 		def empty?
 			@tasks.empty?
 		end
@@ -60,15 +69,14 @@ module Async
 				begin
 					task.wait
 				ensure
-					# We don't know for sure that the exception was due to the task completion.
-					unless task.running?
-						# Remove the task from the waiting list if it's finished:
-						@tasks.shift if @tasks.first == task
-					end
+					# Remove the task from the waiting list if it's finished:
+					@tasks.shift if @tasks.first == task
 				end
 			end
 		end
 		
+		# Stop all tasks held by the barrier.
+		# @asynchronous May wait for tasks to finish executing.
 		def stop
 			# We have to be careful to avoid enumerating tasks while adding/removing to it:
 			tasks = @tasks.dup

data/lib/async/clock.rb

@@ -21,6 +21,8 @@
 # THE SOFTWARE.
 
 module Async
+	# A convenient wrapper around the internal monotonic clock.
+	# @public Since `stable-v1`.
 	class Clock
 		# Get the current elapsed monotonic time.
 		def self.now
@@ -28,6 +30,8 @@ module Async
 		end
 		
 		# Measure the execution of a block of code.
+		# @yields {...} The block to execute.
+		# @returns [Numeric] The total execution time.
 		def self.measure
 			start_time = self.now
 			
@@ -36,19 +40,25 @@ module Async
 			return self.now - start_time
 		end
 		
+		# Start measuring elapsed time from now.
+		# @returns [Clock]
 		def self.start
 			self.new.tap(&:start!)
 		end
 		
+		# Create a new clock with the initial total time.
+		# @parameter total [Numeric] The initial clock duration.
 		def initialize(total = 0)
 			@total = total
 			@started = nil
 		end
 		
+		# Start measuring a duration.
 		def start!
 			@started ||= Clock.now
 		end
 		
+		# Stop measuring a duration and append the duration to the current total.
 		def stop!
 			if @started
 				@total += (Clock.now - @started)
@@ -58,6 +68,7 @@ module Async
 			return @total
 		end
 		
+		# The total elapsed time including any current duration.
 		def total
 			total = @total
 			

data/lib/async/condition.md

@@ -0,0 +1,31 @@
+A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered. Zero or more fibers can wait on a condition. When the condition is signalled, the fibers will be resumed in order.
+
+## Example
+
+~~~ ruby
+require 'async'
+
+Sync do
+	condition = Async::Condition.new
+	
+	Async do
+		Console.logger.info "Waiting for condition..."
+		value = condition.wait
+		Console.logger.info "Condition was signalled: #{value}"
+	end
+	
+	Async do |task|
+		task.sleep(1)
+		Console.logger.info "Signalling condition..."
+		condition.signal("Hello World")
+	end
+end
+~~~
+
+### Output
+
+~~~
+0.0s     info: Waiting for condition... [ec=0x3c] [pid=47943]
+1.0s     info: Signalling condition... [ec=0x64] [pid=47943]
+1.0s     info: Condition was signalled: Hello World [ec=0x3c] [pid=47943]
+~~~

data/lib/async/condition.rb

@@ -24,43 +24,54 @@ require 'fiber'
 require_relative 'node'
 
 module Async
-	# A synchronization primative, which allows fibers to wait until a particular condition is triggered. Signalling the condition directly resumes the waiting fibers and thus blocks the caller.
+	# A synchronization primitive, which allows fibers to wait until a particular condition is (edge) triggered.
+	# @public Since `stable-v1`.
 	class Condition
 		def initialize
 			@waiting = []
 		end
 		
+		Queue = Struct.new(:fiber) do
+			def transfer(*arguments)
+				fiber&.transfer(*arguments)
+			end
+			
+			def alive?
+				fiber&.alive?
+			end
+			
+			def nullify
+				self.fiber = nil
+			end
+		end
+		
+		private_constant :Queue
+		
 		# Queue up the current fiber and wait on yielding the task.
-		# @return [Object]
+		# @returns [Object]
 		def wait
-			fiber = Fiber.current
-			@waiting << fiber
-			
-			Task.yield
+			queue = Queue.new(Fiber.current)
+			@waiting << queue
 			
-			# It would be nice if there was a better construct for this. We only need to invoke #delete if the task was not resumed normally. This can only occur with `raise` and `throw`. But there is no easy way to detect this.
-		# ensure when not return or ensure when raise, throw
-		rescue Exception
-			@waiting.delete(fiber)
-			raise
+			Fiber.scheduler.transfer
+		ensure
+			queue.nullify
 		end
 		
 		# Is any fiber waiting on this notification?
-		# @return [Boolean]
+		# @returns [Boolean]
 		def empty?
 			@waiting.empty?
 		end
 		
 		# Signal to a given task that it should resume operations.
-		# @param value The value to return to the waiting fibers.
-		# @see Task.yield which is responsible for handling value.
-		# @return [void]
+		# @parameter value [Object | Nil] The value to return to the waiting fibers.
 		def signal(value = nil)
 			waiting = @waiting
 			@waiting = []
 			
 			waiting.each do |fiber|
-				fiber.resume(value) if fiber.alive?
+				Fiber.scheduler.resume(fiber, value) if fiber.alive?
 			end
 			
 			return nil

data/lib/async/node.rb

@@ -21,7 +21,7 @@
 # THE SOFTWARE.
 
 module Async
-	# A double linked list.
+	# A double linked list used for managing tasks.
 	class List
 		def initialize
 			# The list behaves like a list node, so @tail points to the next item (the first one) and head points to the previous item (the last one). This may be slightly confusing but it makes the interface more natural.
@@ -121,6 +121,7 @@ module Async
 	
 	private_constant :List
 	
+	# A list of children tasks.
 	class Children < List
 		def initialize
 			super
@@ -154,10 +155,10 @@ module Async
 		end
 	end
 	
-	# Represents a node in a tree, used for nested {Task} instances.
+	# A node in a tree, used for implementing the task hierarchy.
 	class Node
 		# Create a new node in the tree.
-		# @param parent [Node, nil] This node will attach to the given parent.
+		# @parameter parent [Node | Nil] This node will attach to the given parent.
 		def initialize(parent = nil, annotation: nil, transient: false)
 			@parent = nil
 			@children = nil
@@ -175,15 +176,21 @@ module Async
 			end
 		end
 		
-		# You should not directly rely on these pointers but instead use `#children`.
-		# List pointers:
+		# @returns [Node] the root node in the hierarchy.
+		def root
+			@parent&.root || self
+		end
+		
+		# @private
 		attr_accessor :head
+		
+		# @private
 		attr_accessor :tail
 		
-		# @attr parent [Node, nil]
+		# @attribute [Node] The parent node.
 		attr :parent
 		
-		# @attr children [List<Node>] Optional list of children.
+		# @attribute children [Children | Nil] Optional list of children.
 		attr :children
 		
 		# A useful identifier for the current node.
@@ -215,6 +222,8 @@ module Async
 			
 			if @annotation
 				"#{@object_name} #{@annotation}"
+			elsif line = self.backtrace(0, 1)&.first
+				"#{@object_name} #{line}"
 			else
 				@object_name
 			end
@@ -225,12 +234,14 @@ module Async
 		end
 		
 		def to_s
-			"\#<#{description}>"
+			"\#<#{self.description}>"
 		end
 		
+		alias inspect to_s
+		
 		# Change the parent of this node.
-		# @param parent [Node, nil] the parent to attach to, or nil to detach.
-		# @return [self]
+		# @parameter parent [Node | Nil] the parent to attach to, or nil to detach.
+		# @returns [Node] Itself.
 		def parent=(parent)
 			return if @parent.equal?(parent)
 			
@@ -263,7 +274,7 @@ module Async
 		
 		# Whether the node can be consumed safely. By default, checks if the
 		# children set is empty.
-		# @return [Boolean]
+		# @returns [Boolean]
 		def finished?
 			@children.nil? || @children.finished?
 		end
@@ -293,7 +304,7 @@ module Async
 		end
 		
 		# Traverse the tree.
-		# @yield [node, level] The node and the level relative to the given root.
+		# @yields {|node, level| ...} The node and the level relative to the given root.
 		def traverse(level = 0, &block)
 			yield self, level
 			
@@ -329,6 +340,10 @@ module Async
 			end
 		end
 		
+		def stopped?
+			@children.nil?
+		end
+		
 		def print_hierarchy(out = $stdout, backtrace: true)
 			self.traverse do |node, level|
 				indent = "\t" * level

data/lib/async/notification.rb

@@ -24,13 +24,13 @@ require_relative 'condition'
 
 module Async
 	# A synchronization primitive, which allows fibers to wait until a notification is received. Does not block the task which signals the notification. Waiting tasks are resumed on next iteration of the reactor.
+	# @public Since `stable-v1`.
 	class Notification < Condition
 		# Signal to a given task that it should resume operations.
-		# @return [void]
 		def signal(value = nil, task: Task.current)
 			return if @waiting.empty?
 			
-			task.reactor << Signal.new(@waiting, value)
+			Fiber.scheduler.push Signal.new(@waiting, value)
 			
 			@waiting = []
 			
@@ -42,9 +42,9 @@ module Async
 				true
 			end
 			
-			def resume
+			def transfer
 				waiting.each do |fiber|
-					fiber.resume(value) if fiber.alive?
+					fiber.transfer(value) if fiber.alive?
 				end
 			end
 		end

data/lib/async/queue.rb

@@ -24,6 +24,7 @@ require_relative 'notification'
 
 module Async
 	# A queue which allows items to be processed in order.
+	# @public Since `stable-v1`.
 	class Queue < Notification
 		def initialize(parent: nil)
 			super()
@@ -42,16 +43,14 @@ module Async
 			@items.empty?
 		end
 		
-		def <<(item)
-			@items << item
+		def enqueue(item)
+			@items.push(item)
 			
 			self.signal unless self.empty?
 		end
 		
-		def enqueue(*items)
-			@items.concat(items)
-			
-			self.signal unless self.empty?
+		def <<(item)
+			enqueue(item)
 		end
 		
 		def dequeue
@@ -75,6 +74,7 @@ module Async
 		end
 	end
 	
+	# @public Since `stable-v1`.
 	class LimitedQueue < Queue
 		def initialize(limit = 1, **options)
 			super(**options)
@@ -86,12 +86,12 @@ module Async
 		
 		attr :limit
 		
-		# @return [Boolean] Whether trying to enqueue an item would block.
+		# @returns [Boolean] Whether trying to enqueue an item would block.
 		def limited?
 			@items.size >= @limit
 		end
 		
-		def <<(item)
+		def enqueue item
 			while limited?
 				@full.wait
 			end
@@ -99,19 +99,6 @@ module Async
 			super
 		end
 		
-		def enqueue *items
-			while !items.empty?
-				while limited?
-					@full.wait
-				end
-				
-				available = @limit - @items.size
-				@items.concat(items.shift(available))
-				
-				self.signal unless self.empty?
-			end
-		end
-		
 		def dequeue
 			item = super