async 2.17.0 → 2.32.0

data/lib/async/priority_queue.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require "io/event/priority_heap"
+require "thread"
+
+require_relative "queue"
+
+module Async
+	# A queue which allows items to be processed in priority order of consumers.
+	#
+	# Unlike a traditional priority queue where items have priorities, this queue 
+	# assigns priorities to consumers (fibers waiting to dequeue). Higher priority
+	# consumers are served first when items become available.
+	#
+	# @public Since *Async v2*.
+	class PriorityQueue
+		ClosedError = Queue::ClosedError
+		
+		# A waiter represents a fiber waiting to dequeue with a given priority.
+		Waiter = Struct.new(:fiber, :priority, :sequence, :condition, :value) do
+			include Comparable
+			
+			def <=>(other)
+				# Higher priority comes first, then FIFO for equal priorities:
+				if priority == other.priority
+					# Use sequence for FIFO behavior (lower sequence = earlier):
+					sequence <=> other.sequence
+				else
+					other.priority <=> priority  # Reverse for max-heap behavior
+				end
+			end
+			
+			def signal(value)
+				self.value = value
+				condition.signal
+			end
+			
+			def wait_for_value(mutex, timeout = nil)
+				condition.wait(mutex, timeout)
+				return self.value
+			end
+			
+			# Invalidate this waiter, making it unusable and detectable as abandoned.
+			def invalidate!
+				self.fiber = nil
+			end
+			
+			# Check if this waiter has been invalidated.
+			def valid?
+				self.fiber&.alive?
+			end
+		end
+		
+		private_constant :Waiter
+		
+		# Create a new priority queue.
+		#
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		def initialize(parent: nil)
+			@items = []
+			@closed = false
+			@parent = parent
+			@waiting = IO::Event::PriorityHeap.new
+			@sequence = 0
+			
+			@mutex = Mutex.new
+		end
+		
+		# Close the queue, causing all waiting tasks to return `nil`. 
+		# Any subsequent calls to {enqueue} will raise an exception.
+		def close
+			@mutex.synchronize do
+				@closed = true
+				
+				# Signal all waiting fibers with nil, skipping dead/invalid ones:
+				while waiter = @waiting.pop
+					waiter.signal(nil)
+				end
+			end
+		end
+		
+		# @returns [Boolean] Whether the queue is closed.
+		def closed?
+			@closed
+		end
+		
+		# @attribute [Array] The items in the queue.
+		attr :items
+		
+		# @returns [Integer] The number of items in the queue.
+		def size
+			@items.size
+		end
+		
+		# @returns [Boolean] Whether the queue is empty.
+		def empty?
+			@items.empty?
+		end
+		
+		# @returns [Integer] The number of fibers waiting to dequeue.
+		def waiting_count
+			@mutex.synchronize do
+				@waiting.size
+			end
+		end
+		
+		# @deprecated Use {#waiting_count} instead.
+		alias waiting waiting_count
+		
+		# Add an item to the queue.
+		#
+		# @parameter item [Object] The item to add to the queue.
+		def push(item)
+			@mutex.synchronize do
+				if @closed
+					raise ClosedError, "Cannot push items to a closed queue."
+				end
+				
+				@items << item
+				
+				# Wake up the highest priority waiter if any, skipping dead/invalid waiters:
+				while waiter = @waiting.pop
+					if waiter.valid?
+						value = @items.shift
+						waiter.signal(value)
+						break
+					end
+					# Dead/invalid waiter discarded, try next one.
+				end
+			end
+		end
+		
+		# Compatibility with {::Queue#push}.
+		def <<(item)
+			self.push(item)
+		end
+		
+		# Add multiple items to the queue.
+		#
+		# @parameter items [Array] The items to add to the queue.
+		def enqueue(*items)
+			@mutex.synchronize do
+				if @closed
+					raise ClosedError, "Cannot enqueue items to a closed queue."
+				end
+				
+				@items.concat(items)
+				
+				# Wake up waiting fibers in priority order, skipping dead/invalid waiters:
+				while !@items.empty? && (waiter = @waiting.pop)
+					if waiter.valid?
+						value = @items.shift
+						waiter.signal(value)
+					end
+					# Dead/invalid waiter discarded, continue to next one.
+				end
+			end
+		end
+		
+		# Remove and return the next item from the queue.
+		#
+		# If the queue is empty, this method will block until an item is available or timeout expires.
+		# Fibers are served in priority order, with higher priority fibers receiving
+		# items first.
+		#
+		# @parameter priority [Numeric] The priority of this consumer (higher = served first).
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The next item in the queue, or nil if timeout expires.
+		def dequeue(priority: 0, timeout: nil)
+			@mutex.synchronize do
+				# If queue is closed and empty, return nil immediately:
+				if @closed && @items.empty?
+					return nil
+				end
+				
+				# Fast path: if items available and either no waiters or we have higher priority:
+				unless @items.empty?
+					head = @waiting.peek
+					if head.nil? or priority > head.priority
+						return @items.shift
+					end
+				end
+				
+				# Handle immediate timeout (non-blocking)
+				return nil if timeout == 0
+				
+				# Need to wait - create our own condition variable and add to waiting queue:
+				sequence = @sequence
+				@sequence += 1
+				
+				condition = ConditionVariable.new
+				
+				begin
+					waiter = Waiter.new(Fiber.current, priority, sequence, condition, nil)
+					@waiting.push(waiter)
+					
+					# Wait for our specific condition variable to be signaled:
+					return waiter.wait_for_value(@mutex, timeout)
+				ensure
+					waiter&.invalidate!
+				end
+			end
+		end
+		
+		# Compatibility with {::Queue#pop}.
+		#
+		# @parameter priority [Numeric] The priority of this consumer.
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def pop(priority: 0, timeout: nil)
+			self.dequeue(priority: priority, timeout: timeout)
+		end
+		
+		# Process each item in the queue.
+		#
+		# @asynchronous Executes the given block concurrently for each item.
+		#
+		# @parameter priority [Numeric] The priority for processing items.
+		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
+		# @parameter options [Hash] The options to pass to the task.
+		# @yields {|task| ...} When the system is idle, the block will be executed in a new task.
+		def async(priority: 0, parent: (@parent or Task.current), **options, &block)
+			while item = self.dequeue(priority: priority)
+				parent.async(item, **options, &block)
+			end
+		end
+		
+		# Enumerate each item in the queue.
+		#
+		# @parameter priority [Numeric] The priority for dequeuing items.
+		def each(priority: 0)
+			while item = self.dequeue(priority: priority)
+				yield item
+			end
+		end
+		
+		# Signal the queue with a value, the same as {#enqueue}.
+		def signal(value = nil)
+			self.enqueue(value)
+		end
+		
+		# Wait for an item to be available, the same as {#dequeue}.
+		#
+		# @parameter priority [Numeric] The priority of this consumer.
+		def wait(priority: 0)
+			self.dequeue(priority: priority)
+		end
+	end
+end

data/lib/async/promise.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	# A promise represents a value that will be available in the future.
+	# Unlike Condition, once resolved (or rejected), all future waits return immediately 
+	# with the stored value or raise the stored exception.
+	# 
+	# This is thread-safe and integrates with the fiber scheduler.
+	#
+	# @public Since *Async v2*.
+	class Promise
+		# Create a new promise.
+		def initialize
+			# nil = pending, :completed = success, :failed = failure, :cancelled = cancelled:
+			@resolved = nil
+			
+			# Stores either the result value or the exception:
+			@value = nil
+			
+			# Track how many fibers are currently waiting:
+			@waiting = 0
+			
+			@mutex = Mutex.new
+			@condition = ConditionVariable.new
+		end
+		
+		# @returns [Boolean] Whether the promise has been resolved or rejected.
+		def resolved?
+			@mutex.synchronize {!!@resolved}
+		end
+		
+		# @returns [Symbol | Nil] The internal resolved state (:completed, :failed, :cancelled, or nil if pending).
+		# @private For internal use by Task.
+		def resolved
+			@mutex.synchronize {@resolved}
+		end
+		
+		# @returns [Boolean] Whether the promise has been cancelled.
+		def cancelled?
+			@mutex.synchronize {@resolved == :cancelled}
+		end
+		
+		# @returns [Boolean] Whether the promise failed with an exception.
+		def failed?
+			@mutex.synchronize {@resolved == :failed}
+		end
+		
+		# @returns [Boolean] Whether the promise has completed successfully.
+		def completed?
+			@mutex.synchronize {@resolved == :completed}
+		end
+		
+		# @returns [Boolean] Whether any fibers are currently waiting for this promise.
+		def waiting?
+			@mutex.synchronize {@waiting > 0}
+		end
+		
+		# Artificially mark that someone is waiting (useful for suppressing warnings).
+		# @private Internal use only.
+		def suppress_warnings!
+			@mutex.synchronize {@waiting += 1}
+		end
+		
+		# Non-blocking access to the current value. Returns nil if not yet resolved.
+		# Does not raise exceptions even if the promise was rejected or cancelled.
+		# For resolved promises, returns the raw stored value (result, exception, or cancel exception).
+		#
+		# @returns [Object | Nil] The stored value, or nil if pending.
+		def value
+			@mutex.synchronize {@resolved ? @value : nil}
+		end
+		
+		# Wait for the promise to be resolved and return the value.
+		# If already resolved, returns immediately. If rejected, raises the stored exception.
+		#
+		# @returns [Object] The resolved value.
+		# @raises [Exception] The rejected or cancelled exception.
+		def wait
+			@mutex.synchronize do
+				# Increment waiting count:
+				@waiting += 1
+				
+				begin
+					# Wait for resolution if not already resolved:
+					@condition.wait(@mutex) unless @resolved
+					
+					# Return value or raise exception based on resolution type:
+					if @resolved == :completed
+						return @value
+					else
+						# Both :failed and :cancelled store exceptions in @value
+						raise @value
+					end
+				ensure
+					# Decrement waiting count when done:
+					@waiting -= 1
+				end
+			end
+		end
+		
+		# Resolve the promise with a value.
+		# All current and future waiters will receive this value.
+		# Can only be called once - subsequent calls are ignored.
+		#
+		# @parameter value [Object] The value to resolve the promise with.
+		def resolve(value)
+			@mutex.synchronize do
+				return if @resolved
+				
+				@value = value
+				@resolved = :completed
+				
+				# Wake up all waiting fibers:
+				@condition.broadcast
+			end
+			
+			return value
+		end
+		
+		# Reject the promise with an exception.
+		# All current and future waiters will receive this exception.
+		# Can only be called once - subsequent calls are ignored.
+		#
+		# @parameter exception [Exception] The exception to reject the promise with.
+		def reject(exception)
+			@mutex.synchronize do
+				return if @resolved
+				
+				@value = exception
+				@resolved = :failed
+				
+				# Wake up all waiting fibers:
+				@condition.broadcast
+			end
+			
+			return nil
+		end
+		
+		# Exception used to indicate cancellation.
+		class Cancel < Exception
+		end
+		
+		# Cancel the promise, indicating cancellation.
+		# All current and future waiters will receive nil.
+		# Can only be called on pending promises - no-op if already resolved.
+		def cancel(exception = Cancel.new("Promise was cancelled!"))
+			@mutex.synchronize do
+				# No-op if already in any final state
+				return if @resolved
+				
+				@value = exception
+				@resolved = :cancelled
+				
+				# Wake up all waiting fibers:
+				@condition.broadcast
+			end
+			
+			return nil
+		end
+		
+		# Resolve the promise with the result of the block.
+		# If the block raises an exception, the promise will be rejected.
+		# If the promise was already resolved, the block will not be called.
+		# @yields {...} The block to call to resolve the promise.
+		# @returns [Object] The result of the block.
+		def fulfill(&block)
+			raise "Promise already resolved!" if @resolved
+			
+			begin
+				return self.resolve(yield)
+			rescue Cancel => exception
+				return self.cancel(exception)
+			rescue => error
+				return self.reject(error)
+			rescue Exception => exception
+				self.reject(exception)
+				raise
+			ensure
+				# Handle non-local exits (throw, etc.) that bypass normal flow:
+				self.resolve(nil) unless @resolved
+			end
+		end
+	end
+end

data/lib/async/queue.rb

@@ -1,70 +1,95 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2024, by Samuel Williams.
+# Copyright, 2018-2025, by Samuel Williams.
 # Copyright, 2019, by Ryan Musgrave.
 # Copyright, 2020-2022, by Bruno Sutic.
+# Copyright, 2025, by Jahfer Husain.
+# Copyright, 2025, by Shopify Inc.
 
-require_relative 'notification'
+require_relative "notification"
 
 module Async
-	# A queue which allows items to be processed in order.
+	# A thread-safe queue which allows items to be processed in order.
+	#
+	# This implementation uses Thread::Queue internally for thread safety while
+	# maintaining compatibility with the fiber scheduler.
 	#
 	# It has a compatible interface with {Notification} and {Condition}, except that it's multi-value.
 	#
-	# @public Since `stable-v1`.
+	# @asynchronous This class is thread-safe.
+	# @public Since *Async v1*.
 	class Queue
-		# Create a new queue.
+		# An error raised when trying to enqueue items to a closed queue.
+		# @public Since *Async v2.24*.
+		class ClosedError < RuntimeError
+		end
+		
+		# Create a new thread-safe queue.
 		#
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
-		# @parameter available [Notification] The notification to use for signaling when items are available.
-		def initialize(parent: nil, available: Notification.new)
-			@items = []
+		def initialize(parent: nil, delegate: Thread::Queue.new)
+			@delegate = delegate
 			@parent = parent
-			@available = available
 		end
 		
-		# @attribute [Array] The items in the queue.
-		attr :items
+		# @returns [Boolean] Whether the queue is closed.
+		def closed?
+			@delegate.closed?
+		end
+		
+		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
+		def close
+			@delegate.close
+		end
 		
 		# @returns [Integer] The number of items in the queue.
 		def size
-			@items.size
+			@delegate.size
 		end
 		
 		# @returns [Boolean] Whether the queue is empty.
 		def empty?
-			@items.empty?
+			@delegate.empty?
+		end
+		
+		# @returns [Integer] The number of tasks waiting for an item.
+		def waiting_count
+			@delegate.num_waiting
 		end
 		
 		# Add an item to the queue.
 		def push(item)
-			@items << item
-			
-			@available.signal unless self.empty?
+			@delegate.push(item)
+		rescue ClosedQueueError
+			raise ClosedError, "Cannot enqueue items to a closed queue!"
 		end
 		
 		# Compatibility with {::Queue#push}.
-		alias << push
+		def <<(item)
+			self.push(item)
+		end
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
-			@items.concat(items)
-			
-			@available.signal unless self.empty?
+			items.each {|item| @delegate.push(item)}
+		rescue ClosedQueueError
+			raise ClosedError, "Cannot enqueue items to a closed queue!"
 		end
 		
 		# Remove and return the next item from the queue.
-		def dequeue
-			while @items.empty?
-				@available.wait
-			end
-			
-			@items.shift
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def dequeue(timeout: nil)
+			@delegate.pop(timeout: timeout)
 		end
 		
 		# Compatibility with {::Queue#pop}.
-		alias pop dequeue
+		# @parameter timeout [Numeric, nil] Maximum time to wait for an item. If nil, waits indefinitely. If 0, returns immediately.
+		# @returns [Object, nil] The dequeued item, or nil if timeout expires.
+		def pop(timeout: nil)
+			@delegate.pop(timeout: timeout)
+		end
 		
 		# Process each item in the queue.
 		#
@@ -88,7 +113,7 @@ module Async
 		end
 		
 		# Signal the queue with a value, the same as {#enqueue}.
-		def signal(value)
+		def signal(value = nil)
 			self.enqueue(value)
 		end
 		
@@ -98,70 +123,33 @@ module Async
 		end
 	end
 	
-	# A queue which limits the number of items that can be enqueued.
-	# @public Since `stable-v1`.
+	# A thread-safe queue which limits the number of items that can be enqueued.
+	#
+	# @public Since *Async v1*.
 	class LimitedQueue < Queue
+		# @private This exists purely for emitting a warning.
+		def self.new(...)
+			warn("`require 'async/limited_queue'` to use `Async::LimitedQueue`.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
+			super
+		end
+		
 		# Create a new limited queue.
 		#
 		# @parameter limit [Integer] The maximum number of items that can be enqueued.
-		# @parameter full [Notification] The notification to use for signaling when the queue is full.
-		def initialize(limit = 1, full: Notification.new, **options)
-			super(**options)
-			
-			@limit = limit
-			@full = full
+		# @parameter full [Notification] The notification to use for signaling when the queue is full. (ignored, for compatibility)
+		def initialize(limit = 1, **options)
+			super(**options, delegate: Thread::SizedQueue.new(limit))
 		end
 		
 		# @attribute [Integer] The maximum number of items that can be enqueued.
-		attr :limit
+		def limit
+			@delegate.max
+		end
 		
 		# @returns [Boolean] Whether trying to enqueue an item would block.
 		def limited?
-			@items.size >= @limit
-		end
-		
-		# Add an item to the queue.
-		#
-		# If the queue is full, this method will block until there is space available.
-		#
-		# @parameter item [Object] The item to add to the queue.
-		def <<(item)
-			while limited?
-				@full.wait
-			end
-			
-			super
-		end
-		
-		# Add multiple items to the queue.
-		#
-		# If the queue is full, this method will block until there is space available. 
-		#
-		# @parameter items [Array] The items to add to the queue.
-		def enqueue(*items)
-			while !items.empty?
-				while limited?
-					@full.wait
-				end
-				
-				available = @limit - @items.size
-				@items.concat(items.shift(available))
-				
-				@available.signal unless self.empty?
-			end
-		end
-		
-		# Remove and return the next item from the queue.
-		#
-		# If the queue is empty, this method will block until an item is available.
-		#
-		# @returns [Object] The next item in the queue.
-		def dequeue
-			item = super
-			
-			@full.signal
-			
-			return item
+			!@delegate.closed? && @delegate.size >= @delegate.max
 		end
 	end
 end

data/lib/async/reactor.rb

@@ -1,17 +1,19 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2025, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 # Copyright, 2018, by Sokolov Yura.
 
-require_relative 'scheduler'
+require_relative "scheduler"
 
 module Async
 	# A wrapper around the the scheduler which binds it to the current thread automatically.
 	class Reactor < Scheduler
 		# @deprecated Replaced by {Kernel::Async}.
 		def self.run(...)
+			warn("`Async::Reactor.run{}` is deprecated, use `Async{}` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
 			Async(...)
 		end