async 2.28.1 → 2.32.0

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,53 +25,44 @@ 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?
-			@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
+		
+		# @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)
-			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}.
@@ -77,31 +72,23 @@ 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
+		# @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}.
-		def pop
-			self.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.
@@ -136,7 +123,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.
@@ -149,78 +137,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.1"
+	VERSION = "2.32.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,31 @@ 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.32.0
+
+  - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
+
+### v2.31.0
+
+  - Introduce `Async::Deadline` for precise timeout management in compound operations.
+
+### v2.30.0
+
+  - Add timeout support to `Async::Queue#dequeue` and `Async::Queue#pop` methods.
+  - Add timeout support to `Async::PriorityQueue#dequeue` and `Async::PriorityQueue#pop` methods.
+  - Add `closed?` method to `Async::PriorityQueue` for full queue interface compatibility.
+  - Support non-blocking operations using `timeout: 0` parameter.
+
+### 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.
@@ -59,34 +84,6 @@ Please see the [project releases](https://socketry.github.io/async/releases/inde
 
   - Updated documentation and agent context.
 
-### v2.27.0
-
-  - `Async::Task#stop` supports an optional `cause:` argument (that defaults to `$!`), which allows you to specify the cause (exception) for stopping the task.
-  - Add thread-safety agent context.
-
-### v2.26.0
-
-  - `Async::Notification#signal` now returns `true` if a task was signaled, `false` otherwise, providing better feedback for notification operations.
-  - `require "async/limited_queue"` is required to use `Async::LimitedQueue` without a deprecation warning. `Async::LimitedQueue` is not deprecated, but it's usage via `async/queue` is deprecated.
-  - `Async::Task#sleep` is deprecated with no replacement.
-  - `Async::Task.yield` is deprecated with no replacement.
-  - `Async::Scheduler#async` is deprecated, use `Async{}`, `Sync{}` or `Async::Task#async` instead.
-  - Agent context is now available, via the [`agent-context` gem](https://github.com/ioquatix/agent-context).
-  - [`Async::Barrier` Improvements](https://socketry.github.io/async/releases/index#async::barrier-improvements)
-  - [Introduce `Async::Queue#close`](https://socketry.github.io/async/releases/index#introduce-async::queue#close)
-
-### v2.25.0
-
-  - Added support for `io_select` hook in the fiber scheduler, allowing non-blocking `IO.select` operations. This enables better integration with code that uses `IO.select` for multiplexing IO operations.
-  - [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)
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,98 @@
 # Releases
 
+## v2.32.0
+
+  - Introduce `Queue#waiting_count` and `PriorityQueue#waiting_count`. Generally for statistics/testing purposes only.
+
+## v2.31.0
+
+  - Introduce `Async::Deadline` for precise timeout management in compound operations.
+
+## v2.30.0
+
+  - Add timeout support to `Async::Queue#dequeue` and `Async::Queue#pop` methods.
+  - Add timeout support to `Async::PriorityQueue#dequeue` and `Async::PriorityQueue#pop` methods.
+  - Add `closed?` method to `Async::PriorityQueue` for full queue interface compatibility.
+  - Support non-blocking operations using `timeout: 0` parameter.
+
+## 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.

data.tar.gz.sig

@@ -1,2 +1,2 @@
-=��؃��6
���{�/�hܯ+�t��������y����%��h�AY�|�uc{��Y'����Z�<;0����E�#d&�xw�f����	�J?���5�r��S��o���R0��4��3H����yD��Ɨ<���d��h�7�~"Ê�~�?[�#�XU�+l{�
-��Pz;��
+���\��v�]3^į38��h�V��&,���a�j�5P��t�h���)'��C��,� AGp���G#�zi)c��d���n��.:���檾A�|F~O^�D�Ж���,���Z46J!{���m���6���p�k~S
+{z+�s������_ԗ�����i�B��lv�w��ӛQ~9p��_�m������2���)r�e}M�u��Y��IL;�����ҳ��C_zɀt�����ͦ/�����+���	�}�ve7��F�94�0� 6"�� eڜ���+s�Oz�RL���;hGS��#Q{���=~2=n��?P�;��Xy�
�N(6�%��~��^��\�M\��N��񮡼�����>I/6D��ƍ��