async 2.12.1 → 2.22.0

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,22 @@
+# 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)
+	rescue => error
+		raise
+	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

@@ -1,4 +1,4 @@
-# ![Async](logo.svg)
+# ![Async](assets/logo.webp)
 
 Async is a composable asynchronous I/O framework for Ruby based on [io-event](https://github.com/socketry/io-event).
 
@@ -7,6 +7,7 @@ Async is a composable asynchronous I/O framework for Ruby based on [io-event](ht
 > beautifully designed." *– [janko](https://github.com/janko)*
 
 [![Development Status](https://github.com/socketry/async/workflows/Test/badge.svg)](https://github.com/socketry/async/actions?workflow=Test)
+[<img src="https://api.gitsponsors.com/api/badge/img?id=87380483" height="20"/>](https://api.gitsponsors.com/api/badge/link?p=U4gCxvzG7eUksiJSe0MSlPHWWhBYryqj6i48tx5L7/r/2NgkAToKb6dEm31bAftU3H+7BVwk3VhUBtE4GHqHJTPfWPR6xo2BQVoT15rFAGAsLFgdT2kKopIfCGV/QDOm7BrkodS2//R7NUMksAdaCQ==)
 
 ## Features
 
@@ -19,51 +20,70 @@ Async is a composable asynchronous I/O framework for Ruby based on [io-event](ht
 
 Please see the [project documentation](https://socketry.github.io/async/) for more details.
 
-  - [Getting Started](https://socketry.github.io/async/guides/getting-started/index) - This guide shows how to add
-    async to your project and run code asynchronously.
+  - [Getting Started](https://socketry.github.io/async/guides/getting-started/index) - This guide shows how to add async to your project and run code asynchronously.
 
-  - [Asynchronous Tasks](https://socketry.github.io/async/guides/asynchronous-tasks/index) - This guide explains how
-    asynchronous tasks work and how to use them.
+  - [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.
+  - [Compatibility](https://socketry.github.io/async/guides/compatibility/index) - This guide gives an overview of the compatibility of Async with Ruby and other frameworks.
 
-  - [Best Practices](https://socketry.github.io/async/guides/best-practices/index) - This guide gives an overview of
-    best practices for using Async.
+  - [Best Practices](https://socketry.github.io/async/guides/best-practices/index) - This guide gives an overview of best practices for using Async.
 
-## Contributing
+  - [Debugging](https://socketry.github.io/async/guides/debugging/index) - This guide explains how to debug issues with programs that use Async.
 
-We welcome contributions to this project.
+## 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.
+Please see the [project releases](https://socketry.github.io/async/releases/index) for all releases.
 
-### Developer Certificate of Origin
+### v2.21.1
+
+  - [Worker Pool](https://socketry.github.io/async/releases/index#worker-pool)
 
-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.20.0
 
-### Contributor Covenant
+  - [Traces and Metrics Providers](https://socketry.github.io/async/releases/index#traces-and-metrics-providers)
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+### 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.
+
+### 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](https://socketry.github.io/async/releases/index#better-handling-of-async-and-sync-in-nested-fibers)
 
 ## See Also
 
-  - [async-io](https://github.com/socketry/async-io) — Asynchronous networking and sockets.
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.
-  - [async-process](https://github.com/socketry/async-process) — Asynchronous process spawning/waiting.
   - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server websockets.
   - [async-dns](https://github.com/socketry/async-dns) — Asynchronous DNS resolver and server.
-  - [async-rspec](https://github.com/socketry/async-rspec) — Shared contexts for running async specs.
-
-### Projects Using Async
-
-  - [ciri](https://github.com/ciri-ethereum/ciri) — An Ethereum implementation written in Ruby.
   - [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,97 @@
+# Releases
+
+## 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_DEFAULT_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.

metadata

@@ -1,15 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.12.1
+  version: 2.22.0
 platform: ruby
 authors:
 - Samuel Williams
 - Bruno Sutic
 - Jeremy Jung
 - Olle Jonsson
+- Patrik Wenger
 - Devin Christensen
 - Emil Tin
+- Jamie McCarthy
 - Kent Gruber
 - Brian Morearty
 - Colin Kelley
@@ -23,14 +25,12 @@ authors:
 - Masafumi Okura
 - Masayuki Yamamoto
 - Math Ieu
-- Patrik Wenger
 - Ryan Musgrave
 - Salim Semaoune
 - Shannon Skipper
 - Sokolov Yura
 - Stefan Wrobel
 - Trevor Turk
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -62,7 +62,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-06-23 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -70,20 +70,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.25'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.25.2
+        version: '1.29'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.25'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.25.2
+        version: '1.29'
 - !ruby/object:Gem::Dependency
   name: fiber-annotation
   requirement: !ruby/object:Gem::Requirement
@@ -104,22 +98,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: traces
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.5
+        version: '0.15'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: metrics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.6.5
-description:
-email:
+        version: '0.12'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -130,7 +144,9 @@ files:
 - lib/async/clock.rb
 - lib/async/condition.md
 - lib/async/condition.rb
+- lib/async/console.rb
 - lib/async/idler.rb
+- lib/async/limited_queue.rb
 - lib/async/list.rb
 - lib/async/node.rb
 - lib/async/notification.rb
@@ -145,11 +161,18 @@ files:
 - lib/async/version.rb
 - lib/async/waiter.md
 - lib/async/waiter.rb
+- lib/async/worker_pool.rb
 - lib/async/wrapper.rb
 - lib/kernel/async.rb
 - lib/kernel/sync.rb
+- lib/metrics/provider/async.rb
+- lib/metrics/provider/async/task.rb
+- lib/traces/provider/async.rb
+- lib/traces/provider/async/barrier.rb
+- lib/traces/provider/async/task.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/async
 licenses:
 - MIT
@@ -157,7 +180,6 @@ metadata:
   documentation_uri: https://socketry.github.io/async/
   funding_uri: https://github.com/sponsors/ioquatix/
   source_code_uri: https://github.com/socketry/async.git
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -165,15 +187,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.1
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A concurrency framework for Ruby.
 test_files: []