async 2.28.1 → 2.32.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efc7dde75b60834caa61f17a3f742ff7836422c0dbc8ab6dc0f67392c00bff0e
-  data.tar.gz: ee3ffc8bab4adc4f98c5df81dda26f74266eb12512aba815b65cab587bb280e5
+  metadata.gz: 5a816b65e2cdf3f1f9ee99d421b32f13ed00c858bfa2b1ff0f814cf33c9dd470
+  data.tar.gz: 85dc9dfad110e4ae2f0d4db45db9b1f941b797891f945da1caaa302df233f813
 SHA512:
-  metadata.gz: 239dfdc750425c0ac90abdf981faa3358593b2d4aa782897e9b7b073fddff04d631606d6bd61d60904fbdd71fb91536dddae5b63343d831a850d67d7ee9782b7
-  data.tar.gz: 83d4af2ab658fef715ad268cb936bbc30851948135b935191d7bdaecad45d7eef9d3f988b8c0857129d4bff0d58648724410ee16671639a7c64d718526e7a175
+  metadata.gz: e6cf114ad81e9eb511504ed44b719f9838ad84623fea14aab43acd531a9d8493b92eb0a24a49bb410670c0be82c8de5617280f39e984f1d9477c4828d96d2fc5
+  data.tar.gz: 2acb3e1516b2670a57cb717713d882f9d75807864924bf7aa691aa82cd5406a2b273c7aa813a30037a3dabce338095eb7faa5efff8f5f5b56290a07b3b0927b5

data/lib/async/condition.rb

@@ -13,65 +13,47 @@ module Async
 	class Condition
 		# Create a new condition.
 		def initialize
-			@waiting = List.new
+			@ready = ::Thread::Queue.new
 		end
 		
-		class FiberNode < List::Node
-			def initialize(fiber)
-				@fiber = fiber
-			end
-			
-			def transfer(*arguments)
-				@fiber.transfer(*arguments)
-			end
-			
-			def alive?
-				@fiber.alive?
-			end
-		end
-		
-		private_constant :FiberNode
-		
 		# Queue up the current fiber and wait on yielding the task.
 		# @returns [Object]
 		def wait
-			@waiting.stack(FiberNode.new(Fiber.current)) do
-				Fiber.scheduler.transfer
-			end
+			@ready.pop
 		end
 		
-		# @deprecated Replaced by {#waiting?}
+		# @returns [Boolean] If there are no fibers waiting on this condition.
 		def empty?
-			warn("`Async::Condition#empty?` is deprecated, use `Async::Condition#waiting?` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
-			
-			@waiting.empty?
+			@ready.num_waiting.zero?
 		end
 		
 		# @returns [Boolean] Is any fiber waiting on this notification?
 		def waiting?
-			@waiting.size > 0
+			!self.empty?
 		end
 		
 		# Signal to a given task that it should resume operations.
 		# @parameter value [Object | Nil] The value to return to the waiting fibers.
 		def signal(value = nil)
-			return if @waiting.empty?
+			return if empty?
 			
-			waiting = self.exchange
+			ready = self.exchange
 			
-			waiting.each do |fiber|
-				Fiber.scheduler.resume(fiber, value) if fiber.alive?
+			ready.num_waiting.times do
+				ready.push(value)
 			end
 			
+			ready.close
+			
 			return nil
 		end
 		
 		protected
 		
 		def exchange
-			waiting = @waiting
-			@waiting = List.new
-			return waiting
+			ready = @ready
+			@ready = ::Thread::Queue.new
+			return ready
 		end
 	end
 end

data/lib/async/deadline.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "clock"
+
+# @namespace
+module Async
+	# Represents a deadline timeout with decrementing remaining time.
+	# Includes an efficient representation for zero (non-blocking) timeouts.
+	# @public Since *Async v2.31*.
+	class Deadline
+		# Singleton module for immediate timeouts (zero or negative).
+		# Avoids object allocation for fast path (non-blocking) timeouts.
+		module Zero
+			# Check if the deadline has expired.
+			# @returns [Boolean] Always returns true since zero timeouts are immediately expired.
+			def self.expired?
+				true
+			end
+			
+			# Get the remaining time.
+			# @returns [Integer] Always returns 0 since zero timeouts have no remaining time.
+			def self.remaining
+				0
+			end
+		end
+		
+		# Create a deadline for the given timeout.
+		# @parameter timeout [Numeric | Nil] The timeout duration, or nil for no timeout.
+		# @returns [Deadline | Nil] A deadline instance, Zero singleton, or nil.
+		def self.start(timeout)
+			if timeout.nil?
+				nil
+			elsif timeout <= 0
+				Zero
+			else
+				self.new(timeout)
+			end
+		end
+		
+		# Create a new deadline with the specified remaining time.
+		# @parameter remaining [Numeric] The initial remaining time.
+		def initialize(remaining)
+			@remaining = remaining
+			@start = Clock.now
+		end
+		
+		# Get the remaining time, updating internal state.
+		# Each call to this method advances the internal clock and reduces
+		# the remaining time by the elapsed duration since the last call.
+		# @returns [Numeric] The remaining time (may be negative if expired).
+		def remaining
+			now = Clock.now
+			delta = now - @start
+			@start = now
+			
+			@remaining -= delta
+			
+			return @remaining
+		end
+		
+		# Check if the deadline has expired.
+		# @returns [Boolean] True if no time remains.
+		def expired?
+			self.remaining <= 0
+		end
+	end
+end

data/lib/async/notification.rb

@@ -12,23 +12,25 @@ module Async
 		# Signal to a given task that it should resume operations.
 		#
 		# @returns [Boolean] if a task was signalled.
-		def signal(value = nil, task: Task.current)
-			return false if @waiting.empty?
+		def signal(value = nil)
+			return false if empty?
 			
 			Fiber.scheduler.push Signal.new(self.exchange, value)
 			
 			return true
 		end
 		
-		Signal = Struct.new(:waiting, :value) do
+		Signal = Struct.new(:ready, :value) do
 			def alive?
 				true
 			end
 			
 			def transfer
-				waiting.each do |fiber|
-					fiber.transfer(value) if fiber.alive?
+				ready.num_waiting.times do
+					ready.push(value)
 				end
+				
+				ready.close
 			end
 		end
 		

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