async 2.28.0 → 2.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3d7b98c33c331424b3e803d3081ee28abc72ca52e910cc0ee49a51a1a90d8f0
-  data.tar.gz: 306153a2296017bfb169251642c9b64409b5152b98a28e49b1e02158b5c69634
+  metadata.gz: 643f4000360902d473fec7d3c35dfa4d810499a7ee2d419bb6a44e185e4ce9a6
+  data.tar.gz: fd8150c4df0e9834259c612811856764dde221f3e21a58cb33ae7a9903822f8a
 SHA512:
-  metadata.gz: 580a4f849c6344fd1968c7376b801ce5ed2ee1a3eb79390793f1e9a3c370f12abb2a5664d46cf3b6d75067896365fd762ccdcf491a3fdf25471458284ac86fa2
-  data.tar.gz: 914a5d6bcfaca6c91bf8437b9d5d3e0c894d9666c3819a0c822cc1173af44ce92c9ae4ce901cc1292543d5624c58aa693aed8a4e0ae9e96a7b7c8b9150bc003d
+  metadata.gz: 39886cbaf6b6d9a10522956c67d2c5228e22aeefe27104456f3e767441b43b13887ddb41c71e7bc2cffab7956e17117a9e0a8df64d585ecbfe532a87c2f2d592
+  data.tar.gz: b282710c3ce0fc5db35b7de431fa7d8121c9ca3d2ef4ccb1b0c5cafc26a84162eff01aae53b1b267683d8a0c635a991afae54e4d73d3cf7c2a8b23e2e8d32cdf

data/lib/async/barrier.rb

@@ -43,6 +43,8 @@ module Async
 		# 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)
+			raise "Barrier is stopped!" if @finished.closed?
+			
 			waiting = nil
 			
 			parent.async(*arguments, **options) do |task, *arguments|
@@ -50,7 +52,7 @@ module Async
 				@tasks.append(waiting)
 				block.call(task, *arguments)
 			ensure
-				@finished.signal(waiting)
+				@finished.signal(waiting) unless @finished.closed?
 			end
 		end
 		

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/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,226 @@
+# 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)
+				condition.wait(mutex)
+				return self.value
+			end
+		end
+		
+		# 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 ones:
+				while waiter = @waiting.pop
+					if waiter.fiber.alive?
+						waiter.signal(nil)
+					end
+					# Dead waiter discarded, continue to next one.
+				end
+			end
+		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
+			@mutex.synchronize do
+				@waiting.size
+			end
+		end
+		
+		# 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 waiters:
+				while waiter = @waiting.pop
+					if waiter.fiber.alive?
+						value = @items.shift
+						waiter.signal(value)
+						break
+					end
+					# Dead 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 waiters:
+				while !@items.empty? && (waiter = @waiting.pop)
+					if waiter.fiber.alive?
+						value = @items.shift
+						waiter.signal(value)
+					end
+					# Dead 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.
+		# Fibers are served in priority order, with higher priority fibers receiving
+		# items first.
+		#
+		# @parameter priority [Numeric] The priority of this consumer (higher = served first).
+		# @returns [Object] The next item in the queue.
+		def dequeue(priority: 0)
+			@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
+				
+				# Need to wait - create our own condition variable and add to waiting queue:
+				sequence = @sequence
+				@sequence += 1
+				
+				condition = ConditionVariable.new
+				waiter = Waiter.new(Fiber.current, priority, sequence, condition, nil)
+				@waiting.push(waiter)
+				
+				# Wait for our specific condition variable to be signaled:
+				# The mutex is released during wait, reacquired after:
+				return waiter.wait_for_value(@mutex)
+			end
+		end
+		
+		# Compatibility with {::Queue#pop}.
+		#
+		# @parameter priority [Numeric] The priority of this consumer.
+		def pop(priority: 0)
+			self.dequeue(priority: priority)
+		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

@@ -10,10 +10,14 @@
 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.
 	#
+	# @asynchronous This class is thread-safe.
 	# @public Since *Async v1*.
 	class Queue
 		# An error raised when trying to enqueue items to a closed queue.
@@ -21,48 +25,39 @@ module Async
 		class ClosedError < RuntimeError
 		end
 		
-		# Create a new queue.
+		# 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 = []
-			@closed = false
+		def initialize(parent: nil, delegate: Thread::Queue.new)
+			@delegate = delegate
 			@parent = parent
-			@available = available
+		end
+		
+		# @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
-			@closed = true
-			
-			while @available.waiting?
-				@available.signal(nil)
-			end
+			@delegate.close
 		end
 		
-		# @attribute [Array] The items in the queue.
-		attr :items
-		
 		# @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
 		
 		# Add an item to the queue.
 		def push(item)
-			if @closed
-				raise ClosedError, "Cannot push items to a closed queue."
-			end
-			
-			@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}.
@@ -72,31 +67,19 @@ module Async
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
-			if @closed
-				raise ClosedError, "Cannot enqueue items to a closed queue."
-			end
-			
-			@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?
-				if @closed
-					return nil
-				end
-				
-				@available.wait
-			end
-			
-			@items.shift
+			@delegate.pop
 		end
 		
 		# Compatibility with {::Queue#pop}.
-		def pop
-			self.dequeue
+		def pop(...)
+			@delegate.pop(...)
 		end
 		
 		# Process each item in the queue.
@@ -131,7 +114,8 @@ module Async
 		end
 	end
 	
-	# A queue which limits the number of items that can be enqueued.
+	# 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.
@@ -144,78 +128,19 @@ module Async
 		# 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
-		
-		# Close the queue, causing all waiting tasks to return `nil`. Any subsequent calls to {enqueue} will raise an exception.
-		# Also signals all tasks waiting for the queue to be full.
-		def close
-			super
-			
-			while @full.waiting?
-				@full.signal(nil)
-			end
+		def limit
+			@delegate.max
 		end
 		
 		# @returns [Boolean] Whether trying to enqueue an item would block.
 		def limited?
-			!@closed && @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 push(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
-				
-				if @closed
-					raise ClosedError, "Cannot enqueue items to a closed queue."
-				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/task.rb

@@ -7,12 +7,14 @@
 # Copyright, 2020, by Patrik Wenger.
 # Copyright, 2023, by Math Ieu.
 # Copyright, 2025, by Shigeru Nakajima.
+# Copyright, 2025, by Shopify Inc.
 
 require "fiber"
 require "console"
 
 require_relative "node"
 require_relative "condition"
+require_relative "promise"
 require_relative "stop"
 
 Fiber.attr_accessor :async_task
@@ -63,14 +65,24 @@ module Async
 			
 			# These instance variables are critical to the state of the task.
 			# In the initialized state, the @block should be set, but the @fiber should be nil.
-			# In the running state, the @fiber should be set.
+			# In the running state, the @fiber should be set, and @block should be nil.
 			# In a finished state, the @block should be nil, and the @fiber should be nil.
 			@block = block
 			@fiber = nil
 			
-			@status = :initialized
-			@result = nil
-			@finished = finished
+			@promise = Promise.new
+			
+			# Handle finished: parameter for backward compatibility:
+			case finished
+			when false
+				# `finished: false` suppresses warnings for expected task failures:
+				@promise.suppress_warnings!
+			when nil
+				# `finished: nil` is the default, no special handling:
+			else
+				# All other `finished:` values are deprecated:
+				warn("finished: argument with non-false value is deprecated and will be removed.", uplevel: 1, category: :deprecated) if $VERBOSE
+			end
 			
 			@defer_stop = nil
 		end
@@ -109,7 +121,7 @@ module Async
 		
 		# @returns [String] A description of the task and it's current status.
 		def to_s
-			"\#<#{self.description} (#{@status})>"
+			"\#<#{self.description} (#{self.status})>"
 		end
 		
 		# @deprecated Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
@@ -146,22 +158,22 @@ module Async
 		
 		# @returns [Boolean] Whether the task is running.
 		def running?
-			@status == :running
+			self.alive?
 		end
 		
 		# @returns [Boolean] Whether the task failed with an exception.
 		def failed?
-			@status == :failed
+			@promise.failed?
 		end
 		
 		# @returns [Boolean] Whether the task has been stopped.
 		def stopped?
-			@status == :stopped
+			@promise.cancelled?
 		end
 		
 		# @returns [Boolean] Whether the task has completed execution and generated a result.
 		def completed?
-			@status == :completed
+			@promise.completed?
 		end
 		
 		# Alias for {#completed?}.
@@ -170,20 +182,32 @@ module Async
 		end
 		
 		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
-		attr :status
+		def status
+			case @promise.resolved
+			when :cancelled
+				:stopped
+			when :failed
+				:failed
+			when :completed
+				:completed
+			when nil
+				self.running? ? :running : :initialized
+			end
+		end
 		
 		# Begin the execution of the task.
 		#
 		# @raises [RuntimeError] If the task is already running.
 		def run(*arguments)
-			if @status == :initialized
-				@status = :running
+			# Move from initialized to running by clearing @block
+			if block = @block
+				@block = nil
 				
 				schedule do
-					@block.call(self, *arguments)
+					block.call(self, *arguments)
 				rescue => error
 					# I'm not completely happy with this overhead, but the alternative is to not log anything which makes debugging extremely difficult. Maybe we can introduce a debug wrapper which adds extra logging.
-					if @finished.nil?
+					unless @promise.waiting?
 						warn(self, "Task may have ended with unhandled exception.", exception: error)
 					end
 					
@@ -225,24 +249,29 @@ module Async
 		#
 		# @raises [RuntimeError] If the task's fiber is the current fiber.
 		# @returns [Object] The final expression/result of the task's block.
+		# @asynchronous This method is thread-safe.
 		def wait
 			raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
 			
-			# `finish!` will set both of these to nil before signaling the condition:
-			if @block || @fiber
-				@finished ||= Condition.new
-				@finished.wait
-			end
-			
-			if @status == :failed
-				raise @result
-			else
-				return @result
+			# Wait for the task to complete - Promise handles all the complexity:
+			begin
+				@promise.wait
+			rescue Promise::Cancel
+				# For backward compatibility, stopped tasks return nil
+				return nil
 			end
 		end
 		
 		# Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
-		attr :result
+		def result
+			value = @promise.value
+			# For backward compatibility, return nil for stopped tasks
+			if @promise.cancelled?
+				nil
+			else
+				value
+			end
+		end
 		
 		# Stop the task and all of its children.
 		#
@@ -375,29 +404,25 @@ module Async
 			
 			# Attempt to remove this node from the task tree.
 			consume
-			
-			# If this task was being used as a future, signal completion here:
-			if @finished
-				@finished.signal(self)
-				@finished = nil
-			end
 		end
 		
 		# State transition into the completed state.
 		def completed!(result)
-			@result = result
-			@status = :completed
+			# Resolve the promise with the result:
+			@promise&.resolve(result)
 		end
 		
 		# State transition into the failed state.
 		def failed!(exception = false)
-			@result = exception
-			@status = :failed
+			# Reject the promise with the exception:
+			@promise&.reject(exception)
 		end
 		
 		def stopped!
 			# Console.info(self, status:) {"Task #{self} was stopped with #{@children&.size.inspect} children!"}
-			@status = :stopped
+			
+			# Cancel the promise:
+			@promise&.cancel
 			
 			stopped = false
 			
@@ -442,7 +467,7 @@ module Async
 			
 			@fiber.async_task = self
 			
-			self.root.resume(@fiber)
+			(Fiber.scheduler || self.reactor).resume(@fiber)
 		end
 	end
 end

data/lib/async/variable.rb

@@ -2,16 +2,21 @@
 
 # Released under the MIT License.
 # Copyright, 2021-2025, by Samuel Williams.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "condition"
 
 module Async
 	# A synchronization primitive that allows one task to wait for another task to resolve a value.
+	#
+	# @deprecated Use {Async::Promise} instead.
 	class Variable
 		# Create a new variable.
 		#
 		# @parameter condition [Condition] The condition to use for synchronization.
 		def initialize(condition = Condition.new)
+			warn("`Async::Variable` is deprecated, use `Async::Promise` instead.", category: :deprecated, uplevel: 1) if $VERBOSE
+			
 			@condition = condition
 			@value = nil
 		end

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2025, by Samuel Williams.
 
 module Async
-	VERSION = "2.28.0"
+	VERSION = "2.29.0"
 end

data/lib/async/waiter.rb

@@ -3,9 +3,11 @@
 # Released under the MIT License.
 # Copyright, 2022-2025, by Samuel Williams.
 # Copyright, 2024, by Patrik Wenger.
+# Copyright, 2025, by Shopify Inc.
 
 module Async
 	# A composable synchronization primitive, which allows one task to wait for a number of other tasks to complete. It can be used in conjunction with {Semaphore} and/or {Barrier}.
+	#
 	# @deprecated `Async::Waiter` is deprecated, use `Async::Barrier` instead. 
 	class Waiter
 		# Create a waiter instance.

data/lib/kernel/sync.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2020, by Brian Morearty.
 # Copyright, 2024, by Patrik Wenger.
+# Copyright, 2025, by Shopify Inc.
 
 require_relative "../async/reactor"
 
@@ -30,7 +31,10 @@ module Kernel
 			reactor = Async::Reactor.new
 			
 			begin
-				return reactor.run(annotation: annotation, finished: ::Async::Condition.new, &block).wait
+				# Use finished: false to suppress warnings since we're handling exceptions explicitly
+				task = reactor.async(annotation: annotation, finished: false, &block)
+				reactor.run
+				return task.wait
 			ensure
 				Fiber.set_scheduler(nil)
 			end

data/readme.md

@@ -35,6 +35,20 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
 Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
+### v2.29.0
+
+This release introduces thread-safety as a core concept of Async. Many core classes now have thread-safe guarantees, allowing them to be used safely across multiple threads.
+
+  - Thread-safe `Async::Condition` and `Async::Notification`, implemented using `Thread::Queue`.
+  - Thread-safe `Async::Queue` and `Async::LimitedQueue`, implemented using `Thread::Queue` and `Thread::LimitedQueue` respectively.
+  - `Async::Variable` is deprecated in favor of `Async::Promise`.
+  - [Introduce `Async::Promise`](https://socketry.github.io/async/releases/index#introduce-async::promise)
+  - [Introduce `Async::PriorityQueue`](https://socketry.github.io/async/releases/index#introduce-async::priorityqueue)
+
+### v2.28.1
+
+  - Fix race condition between `Async::Barrier#stop` and finish signalling.
+
 ### v2.28.0
 
   - Use `Traces.current_context` and `Traces.with_context` for better integration with OpenTelemetry.
@@ -77,17 +91,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
   - [Use `IO::Event::WorkerPool` for Blocking Operations](https://socketry.github.io/async/releases/index#use-io::event::workerpool-for-blocking-operations)
   - [Better handling of `IO#close` using `fiber_interrupt`](https://socketry.github.io/async/releases/index#better-handling-of-io#close-using-fiber_interrupt)
 
-### v2.24.0
-
-  - Ruby v3.1 support is dropped.
-  - `Async::Wrapper` which was previously deprecated, is now removed.
-  - [Flexible Timeouts](https://socketry.github.io/async/releases/index#flexible-timeouts)
-
-### v2.23.0
-
-  - Rename `ASYNC_SCHEDULER_DEFAULT_WORKER_POOL` to `ASYNC_SCHEDULER_WORKER_POOL`.
-  - [Fiber Stall Profiler](https://socketry.github.io/async/releases/index#fiber-stall-profiler)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,87 @@
 # Releases
 
+## v2.29.0
+
+This release introduces thread-safety as a core concept of Async. Many core classes now have thread-safe guarantees, allowing them to be used safely across multiple threads.
+
+  - Thread-safe `Async::Condition` and `Async::Notification`, implemented using `Thread::Queue`.
+  - Thread-safe `Async::Queue` and `Async::LimitedQueue`, implemented using `Thread::Queue` and `Thread::LimitedQueue` respectively.
+  - `Async::Variable` is deprecated in favor of `Async::Promise`.
+
+### Introduce `Async::Promise`
+
+This release introduces the new `Async::Promise` class and refactors `Async::Task` to use promises for state management internally. This architectural improvement achieves the design goal that "a task should be a promise with attached computation and cancellation handling."
+
+  - **Thread-safe promise implementation** with immutable state transitions.
+  - **Consistent state management** using symbols: `:completed`, `:failed`, `:cancelled`.
+  - **Promise cancellation** with `cancel()` method and `Cancel` exception class.
+  - **Comprehensive test coverage** with 47 new test cases covering all edge cases.
+
+<!-- end list -->
+
+``` ruby
+require 'async/promise'
+
+# Basic promise usage - works independently of Async framework
+promise = Async::Promise.new
+
+# In another thread or fiber, resolve the promise
+Thread.new do
+  sleep(1)  # Simulate some work
+  promise.resolve("Hello, World!")
+end
+
+# Wait for the result
+result = promise.wait
+puts result  # => "Hello, World!"
+
+# Check promise state
+puts promise.resolved?   # => true
+puts promise.completed?  # => true
+```
+
+Promises bridge Thread and Fiber concurrency models - a promise resolved in one thread can be awaited in a fiber, and vice versa.
+
+### Introduce `Async::PriorityQueue`
+
+The new `Async::PriorityQueue` provides a thread-safe, fiber-aware queue where consumers can specify priority levels. Higher priority consumers are served first when items become available, with FIFO ordering maintained for equal priorities. This is useful for implementing priority-based task processing systems where critical operations need to be handled before lower priority work.
+
+``` ruby
+require 'async'
+require 'async/priority_queue'
+
+Async do
+  queue = Async::PriorityQueue.new
+  
+  # Start consumers with different priorities
+  low_priority = async do
+    puts "Low priority consumer got: #{queue.dequeue(priority: 1)}"
+  end
+  
+  medium_priority = async do
+    puts "Medium priority consumer got: #{queue.dequeue(priority: 5)}"
+  end
+  
+  high_priority = async do
+    puts "High priority consumer got: #{queue.dequeue(priority: 10)}"
+  end
+  
+  # Add items to the queue
+  queue.push("first item")
+  queue.push("second item")
+  queue.push("third item")
+  
+  # Output:
+  # High priority consumer got: first item
+  # Medium priority consumer got: second item  
+  # Low priority consumer got: third item
+end
+```
+
+## v2.28.1
+
+  - Fix race condition between `Async::Barrier#stop` and finish signalling.
+
 ## v2.28.0
 
   - Use `Traces.current_context` and `Traces.with_context` for better integration with OpenTelemetry.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.28.0
+  version: 2.29.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -145,7 +145,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- agent.md
 - context/best-practices.md
 - context/debugging.md
 - context/getting-started.md
@@ -165,6 +164,8 @@ files:
 - lib/async/list.rb
 - lib/async/node.rb
 - lib/async/notification.rb
+- lib/async/priority_queue.rb
+- lib/async/promise.rb
 - lib/async/queue.rb
 - lib/async/reactor.rb
 - lib/async/scheduler.rb

data/agent.md

@@ -1,63 +0,0 @@
-# Agent
-
-## Context
-
-This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
-
-**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
-
-### agent-context
-
-Install and manage context files from Ruby gems.
-
-#### [Usage Guide](.context/agent-context/usage.md)
-
-`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` ...
-
-### decode
-
-Code analysis for documentation generation.
-
-#### [Getting Started with Decode](.context/decode/getting-started.md)
-
-The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
-
-#### [Documentation Coverage](.context/decode/coverage.md)
-
-This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
-
-#### [Ruby Documentation](.context/decode/ruby-documentation.md)
-
-This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
-
-#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
-
-This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
-
-### sus
-
-A fast and scalable test runner.
-
-#### [Using Sus Testing Framework](.context/sus/usage.md)
-
-Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
-
-#### [Mocking](.context/sus/mocking.md)
-
-There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
-
-#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
-
-Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
-
-### sus-fixtures-agent-context
-
-Test fixtures for running in Async.
-
-#### [Getting Started](.context/sus-fixtures-agent-context/getting-started.md)
-
-This guide explains how to use the `sus-fixtures-agent-context` gem to test agent contexts.
-
-#### [GitHub Actions](.context/sus-fixtures-agent-context/github-actions.md)
-
-This guide explains how to integrate the `sus-fixtures-agent-context` gem with GitHub Actions for testing agent contexts.