async 2.14.2 → 2.23.1

data/lib/async/variable.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2022, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
-require_relative 'condition'
+require_relative "condition"
 
 module Async
 	# A synchronization primitive that allows one task to wait for another task to resolve a value.
@@ -31,6 +31,11 @@ module Async
 			condition.signal(value)
 		end
 		
+		# Alias for {#resolve}.
+		def value=(value)
+			self.resolve(value)
+		end
+		
 		# Whether the value has been resolved.
 		#
 		# @returns [Boolean] Whether the value has been resolved.
@@ -41,14 +46,14 @@ module Async
 		# Wait for the value to be resolved.
 		#
 		# @returns [Object] The resolved value.
-		def value
+		def wait
 			@condition&.wait
 			return @value
 		end
 		
-		# Alias for {#value}.
-		def wait
-			self.value
+		# Alias for {#wait}.
+		def value
+			self.wait
 		end
 	end
 end

data/lib/async/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Async
-	VERSION = "2.14.2"
+	VERSION = "2.23.1"
 end

data/lib/async/waiter.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2024, by Patrik Wenger.
 
 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}.

data/lib/async/worker_pool.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require "etc"
+
+module Async
+	# A simple work pool that offloads work to a background thread.
+	#
+	# @private
+	class WorkerPool
+		# Used to augment the scheduler to add support for blocking operations.
+		module BlockingOperationWait
+			# Wait for the given work to be executed.
+			#
+			# @public Since *Async v2.19* and *Ruby v3.4*.
+			# @asynchronous May be non-blocking.
+			#
+			# @parameter work [Proc] The work to execute on a background thread.
+			# @returns [Object] The result of the work.
+			def blocking_operation_wait(work)
+				@worker_pool.call(work)
+			end
+		end
+		
+		# Execute the given work in a background thread.
+		class Promise
+			# Create a new promise.
+			#
+			# @parameter work [Proc] The work to be done.
+			def initialize(work)
+				@work = work
+				@state = :pending
+				@value = nil
+				@guard = ::Mutex.new
+				@condition = ::ConditionVariable.new
+				@thread = nil
+			end
+			
+			# Execute the work and resolve the promise.
+			def call
+				work = nil
+				
+				@guard.synchronize do
+					@thread = ::Thread.current
+					
+					return unless work = @work
+				end
+				
+				resolve(work.call)
+			rescue Exception => error
+				reject(error)
+			end
+			
+			private def resolve(value)
+				@guard.synchronize do
+					@work = nil
+					@thread = nil
+					@value = value
+					@state = :resolved
+					@condition.broadcast
+				end
+			end
+			
+			private def reject(error)
+				@guard.synchronize do
+					@work = nil
+					@thread = nil
+					@value = error
+					@state = :failed
+					@condition.broadcast
+				end
+			end
+			
+			# Cancel the work and raise an exception in the background thread.
+			def cancel
+				return unless @work
+				
+				@guard.synchronize do
+					@work = nil
+					@state = :cancelled
+					@thread&.raise(Interrupt)
+				end
+			end
+			
+			# Wait for the work to be done.
+			#
+			# @returns [Object] The result of the work.
+			def wait
+				@guard.synchronize do
+					while @state == :pending
+						@condition.wait(@guard)
+					end
+					
+					if @state == :failed
+						raise @value
+					else
+						return @value
+					end
+				end
+			end
+		end
+		
+		# A background worker thread.
+		class Worker
+			# Create a new worker.
+			def initialize
+				@work = ::Thread::Queue.new
+				@thread = ::Thread.new(&method(:run))
+			end
+			
+			# Execute work until the queue is closed.
+			def run
+				while work = @work.pop
+					work.call
+				end
+			end
+			
+			# Close the worker thread.
+			def close
+				if thread = @thread
+					@thread = nil
+					thread.kill
+				end
+			end
+			
+			# Call the work and notify the scheduler when it is done.
+			def call(work)
+				promise = Promise.new(work)
+				
+				@work.push(promise)
+				
+				begin
+					return promise.wait
+				ensure
+					promise.cancel
+				end
+			end
+		end
+		
+		# Create a new work pool.
+		#
+		# @parameter size [Integer] The number of threads to use.
+		def initialize(size: Etc.nprocessors)
+			@ready = ::Thread::Queue.new
+			
+			size.times do
+				@ready.push(Worker.new)
+			end
+		end
+		
+		# Close the work pool. Kills all outstanding work.
+		def close
+			if ready = @ready
+				@ready = nil
+				ready.close
+				
+				while worker = ready.pop
+					worker.close
+				end
+			end
+		end
+		
+		# Offload work to a thread.
+		#
+		# @parameter work [Proc] The work to be done.
+		def call(work)
+			if ready = @ready
+				worker = ready.pop
+				
+				begin
+					worker.call(work)
+				ensure
+					ready.push(worker)
+				end
+			else
+				raise RuntimeError, "No worker available!"
+			end
+		end
+	end
+end

data/lib/async/wrapper.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2017, by Kent Gruber.
 
+warn "Async::Wrapper is deprecated and will be removed on 2025-03-31. Please use native interfaces instead.", uplevel: 1, category: :deprecated
+
 module Async
 	# Represents an asynchronous IO within a reactor.
 	# @deprecated With no replacement. Prefer native interfaces.

data/lib/async.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2024, by Samuel Williams.
 # Copyright, 2020, by Salim Semaoune.
 
 require_relative "async/version"

data/lib/kernel/async.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative "../async/reactor"
 
@@ -19,11 +19,13 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous May block until given block completes executing.
 	def Async(...)
 		if current = ::Async::Task.current?
 			return current.async(...)
+		elsif scheduler = Fiber.scheduler
+			::Async::Task.run(scheduler, ...)
 		else
 			# This calls Fiber.set_scheduler(self):
 			reactor = ::Async::Reactor.new

data/lib/kernel/sync.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 # Copyright, 2020, by Brian Morearty.
+# Copyright, 2024, by Patrik Wenger.
 
 require_relative "../async/reactor"
 
@@ -13,17 +14,23 @@ module Kernel
 	# @yields {|task| ...} The block that will execute asynchronously.
 	# 	@parameter task [Async::Task] The task that is executing the given block.
 	#
-	# @public Since `stable-v1`.
+	# @public Since *Async v1*.
 	# @asynchronous Will block until given block completes executing.
-	def Sync(&block)
+	def Sync(annotation: nil, &block)
 		if task = ::Async::Task.current?
-			yield task
+			if annotation
+				task.annotate(annotation) {yield task}
+			else
+				yield task
+			end
+		elsif scheduler = Fiber.scheduler
+			::Async::Task.run(scheduler, &block).wait
 		else
 			# This calls Fiber.set_scheduler(self):
 			reactor = Async::Reactor.new
 			
 			begin
-				return reactor.run(finished: ::Async::Condition.new, &block).wait
+				return reactor.run(annotation: annotation, finished: ::Async::Condition.new, &block).wait
 			ensure
 				Fiber.set_scheduler(nil)
 			end

data/lib/metrics/provider/async/task.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "../../../async/task"
+require "metrics/provider"
+
+Metrics::Provider(Async::Task) do
+	ASYNC_TASK_SCHEDULED = Metrics.metric("async.task.scheduled", :counter, description: "The number of tasks scheduled.")
+	ASYNC_TASK_FINISHED = Metrics.metric("async.task.finished", :counter, description: "The number of tasks finished.")
+	
+	def schedule(&block)
+		ASYNC_TASK_SCHEDULED.emit(1)
+		
+		super(&block)
+	ensure
+		ASYNC_TASK_FINISHED.emit(1)
+	end
+end

data/lib/metrics/provider/async.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "async/task"

data/lib/traces/provider/async/barrier.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+require_relative "../../../async/barrier"
+require "traces/provider"
+
+Traces::Provider(Async::Barrier) do
+	def wait
+		attributes = {
+			"size" => self.size
+		}
+		
+		Traces.trace("async.barrier.wait", attributes: attributes) {super}
+	end
+end

data/lib/traces/provider/async/task.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2022, by Samuel Williams.
+
+require_relative "../../../async/task"
+require "traces/provider"
+
+Traces::Provider(Async::Task) do
+	def schedule(&block)
+		# If we are not actively tracing anything, then we can skip this:
+		unless Traces.active?
+			return super(&block)
+		end
+		
+		unless self.transient?
+			trace_context = Traces.trace_context
+		end
+		
+		attributes = {
+			# We use the instance variable as it corresponds to the user-provided block.
+			"block" => @block,
+			"transient" => self.transient?,
+		}
+		
+		# Run the trace in the context of the child task:
+		super do
+			Traces.trace_context = trace_context
+			
+			if annotation = self.annotation
+				attributes["annotation"] = annotation
+			end
+			
+			Traces.trace("async.task", attributes: attributes) do
+				# Yes, this is correct, we already called super above:
+				yield
+			end
+		end
+	end
+end

data/lib/traces/provider/async.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+require_relative "async/task"
+require_relative "async/barrier"

data/license.md

@@ -11,7 +11,7 @@ Copyright, 2020-2023, by Olle Jonsson.
 Copyright, 2020, by Salim Semaoune.  
 Copyright, 2020, by Brian Morearty.  
 Copyright, 2020, by Stefan Wrobel.  
-Copyright, 2020, by Patrik Wenger.  
+Copyright, 2020-2024, by Patrik Wenger.  
 Copyright, 2020, by Ken Muryoi.  
 Copyright, 2020, by Jun Jiang.  
 Copyright, 2020-2022, by Bruno Sutic.  
@@ -26,6 +26,7 @@ Copyright, 2023, by Math Ieu.
 Copyright, 2023, by Emil Tin.  
 Copyright, 2023, by Gert Goet.  
 Copyright, 2024, by Dimitar Peychinov.  
+Copyright, 2024, by Jamie McCarthy.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -23,7 +23,7 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
   - [Asynchronous Tasks](https://socketry.github.io/async/guides/asynchronous-tasks/index) - This guide explains how asynchronous tasks work and how to use them.
 
-  - [Event Loop](https://socketry.github.io/async/guides/event-loop/index) - This guide gives an overview of how the event loop is implemented.
+  - [Scheduler](https://socketry.github.io/async/guides/scheduler/index) - This guide gives an overview of how the scheduler is implemented.
 
   - [Compatibility](https://socketry.github.io/async/guides/compatibility/index) - This guide gives an overview of the compatibility of Async with Ruby and other frameworks.
 
@@ -31,23 +31,39 @@ Please see the [project documentation](https://socketry.github.io/async/) for mo
 
   - [Debugging](https://socketry.github.io/async/guides/debugging/index) - This guide explains how to debug issues with programs that use Async.
 
-## Contributing
+## Releases
 
-We welcome contributions to this project.
+Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
-1.  Fork it.
-2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
-4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+### v2.23.0
 
-### Developer Certificate of Origin
+  - Rename `ASYNC_SCHEDULER_DEFAULT_WORKER_POOL` to `ASYNC_SCHEDULER_WORKER_POOL`.
+  - [Fiber Stall Profiler](https://socketry.github.io/async/releases/index#fiber-stall-profiler)
+
+### v2.21.1
+
+  - [Worker Pool](https://socketry.github.io/async/releases/index#worker-pool)
+
+### v2.20.0
+
+  - [Traces and Metrics Providers](https://socketry.github.io/async/releases/index#traces-and-metrics-providers)
+
+### v2.19.0
+
+  - [Async::Scheduler Debugging](https://socketry.github.io/async/releases/index#async::scheduler-debugging)
+  - [Console Shims](https://socketry.github.io/async/releases/index#console-shims)
+
+### v2.18.0
+
+  - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+### v2.17.0
 
-### Contributor Covenant
+  - Introduce `Async::Queue#push` and `Async::Queue#pop` for compatibility with `::Queue`.
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+### v2.16.0
+
+  - [Better Handling of Async and Sync in Nested Fibers](https://socketry.github.io/async/releases/index#better-handling-of-async-and-sync-in-nested-fibers)
 
 ## See Also
 
@@ -57,3 +73,21 @@ This project is governed by the [Contributor Covenant](https://www.contributor-c
   - [falcon](https://github.com/socketry/falcon) — A rack compatible server built on top of `async-http`.
   - [rubydns](https://github.com/ioquatix/rubydns) — An easy to use Ruby DNS server.
   - [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot) — A client for making slack bots.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,121 @@
+# Releases
+
+## v2.23.0
+
+  - Rename `ASYNC_SCHEDULER_DEFAULT_WORKER_POOL` to `ASYNC_SCHEDULER_WORKER_POOL`.
+
+### Fiber Stall Profiler
+
+After several iterations of experimentation, we are officially introducing the fiber stall profiler, implemented using the optional `fiber-profiler` gem. This gem is not included by default, but can be added to your project:
+
+``` bash
+$ bundle add fiber-profiler
+```
+
+After adding the gem, you can enable the fiber stall profiler by setting the `FIBER_PROFILER_CAPTURE=true` environment variable:
+
+``` bash
+$ FIBER_PROFILER_CAPTURE=true bundle exec ruby -rasync -e 'Async{Fiber.blocking{sleep 0.1}}'
+Fiber stalled for 0.105 seconds
+-e:1 in c-call '#<Class:Fiber>#blocking' (0.105s)
+	-e:1 in c-call 'Kernel#sleep' (0.105s)
+Skipped 1 calls that were too short to be meaningful.
+```
+
+The fiber profiler will help you find problems with your code that cause the event loop to stall, which can be a common source of performance issues in asynchronous code.
+
+## v2.21.1
+
+### Worker Pool
+
+Ruby 3.4 will feature a new fiber scheduler hook, `blocking_operation_wait` which allows the scheduler to redirect the work given to `rb_nogvl` to a worker pool.
+
+The Async scheduler optionally supports this feature using a worker pool, by using the following environment variable:
+
+    ASYNC_SCHEDULER_WORKER_POOL=true
+
+This will cause the scheduler to use a worker pool for general blocking operations, rather than blocking the event loop.
+
+It should be noted that this isn't a net win, as the overhead of using a worker pool can be significant compared to the `rb_nogvl` work. As such, it is recommended to benchmark your application with and without the worker pool to determine if it is beneficial.
+
+## v2.20.0
+
+### Traces and Metrics Providers
+
+Async now has [traces](https://github.com/socketry/traces) and [metrics](https://github.com/socketry/metrics) providers for various core classes. This allows you to emit traces and metrics to a suitable backend (including DataDog, New Relic, OpenTelemetry, etc.) for monitoring and debugging purposes.
+
+To take advantage of this feature, you will need to introduce your own `config/traces.rb` and `config/metrics.rb`. Async's own repository includes these files for testing purposes, you could copy them into your own project and modify them as needed.
+
+## v2.19.0
+
+### Async::Scheduler Debugging
+
+Occasionally on issues, I encounter people asking for help and I need more information. Pressing Ctrl-C to exit a hung program is common, but it usually doesn't provide enough information to diagnose the problem. Setting the `CONSOLE_LEVEL=debug` environment variable will now print additional information about the scheduler when you interrupt it, including a backtrace of the current tasks.
+
+    > CONSOLE_LEVEL=debug bundle exec ruby ./test.rb
+    ^C  0.0s    debug: Async::Reactor [oid=0x974] [ec=0x988] [pid=9116] [2024-11-08 14:12:03 +1300]
+                   | Scheduler interrupted: Interrupt
+                   | #<Async::Reactor:0x0000000000000974 1 children (running)>
+                   | 	#<Async::Task:0x000000000000099c /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer' (running)>
+                   | 	→ /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `transfer'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:185:in `block'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:207:in `kernel_sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleep'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:7:in `sleepy'
+                   | 	  /Users/samuel/Developer/socketry/async/test.rb:12:in `block in <top (required)>'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+                   | 	  /Users/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+    /Users/samuel/Developer/socketry/async/lib/async/scheduler.rb:317:in `select': Interrupt
+    ... (backtrace continues) ...
+
+This gives better visibility into what the scheduler is doing, and should help diagnose issues.
+
+### Console Shims
+
+The `async` gem depends on `console` gem, because my goal was to have good logging by default without thinking about it too much. However, some users prefer to avoid using the `console` gem for logging, so I've added an experimental set of shims which should allow you to bypass the `console` gem entirely.
+
+``` ruby
+require 'async/console'
+require 'async'
+
+Async{raise "Boom"}
+```
+
+Will now use `Kernel#warn` to print the task failure warning:
+
+    #<Async::Task:0x00000000000012d4 /home/samuel/Developer/socketry/async/lib/async/task.rb:104:in `backtrace' (running)>
+    Task may have ended with unhandled exception.
+    (irb):4:in `block in <top (required)>': Boom (RuntimeError)
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:197:in `block in run'
+    	from /home/samuel/Developer/socketry/async/lib/async/task.rb:420:in `block in schedule'
+
+## v2.18.0
+
+  - Add support for `Sync(annotation:)`, so that you can annotate the block with a description of what it does, even if it doesn't create a new task.
+
+## v2.17.0
+
+  - Introduce `Async::Queue#push` and `Async::Queue#pop` for compatibility with `::Queue`.
+
+## v2.16.0
+
+### Better Handling of Async and Sync in Nested Fibers
+
+Interleaving bare fibers within `Async` and `Sync` blocks should not cause problems, but it presents a number of issues in the current implementation. Tracking the parent-child relationship between tasks, when they are interleaved with bare fibers, is difficult. The current implementation assumes that if there is no parent task, then it should create a new reactor. This is not always the case, as the parent task might not be visible due to nested Fibers. As a result, `Async` will create a new reactor, trying to stop the existing one, causing major internal consistency issues.
+
+I encountered this issue when trying to use `Async` within a streaming response in Rails. The `protocol-rack` [uses a normal fiber to wrap streaming responses](https://github.com/socketry/protocol-rack/blob/cb1ca44e9deadb9369bdb2ea03416556aa927c5c/lib/protocol/rack/body/streaming.rb#L24-L28), and if you try to use `Async` within it, it will create a new reactor, causing the server to lock up.
+
+Ideally, `Async` and `Sync` helpers should work when any `Fiber.scheduler` is defined. Right now, it's unrealistic to expect `Async::Task` to work in any scheduler, but at the very least, the following should work:
+
+``` ruby
+reactor = Async::Reactor.new # internally calls Fiber.set_scheduler
+
+# This should run in the above reactor, rather than creating a new one.
+Async do
+  puts "Hello World"
+end
+```
+
+In order to do this, bare `Async` and `Sync` blocks should use `Fiber.scheduler` as a parent if possible.
+
+See <https://github.com/socketry/async/pull/340> for more details.