async 2.21.1 → 2.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dda1de8f976c85bf6dcbd0156c27c30f85f88d5ffaf32f3397b9838aa920bab
-  data.tar.gz: 0f09cde08880db4456bc03e9a4351903b9a96ca7099e7305c76fdee7f8edc0ed
+  metadata.gz: dedd26d802fb259e0eff2223a86a54f42b46753ab43014b091a83b97610346a0
+  data.tar.gz: 682ab4c4b3798df642e3937b902f4a0d0762ce0dfd91f5c2430205775b2bbe8a
 SHA512:
-  metadata.gz: 980cd5e5832ddd71846785e10b23d18d11cb1f0eee33ccbdf33ed40feb4ac51dd99f7cf3d7f93055d0ad52de2abe0103c1b433d41f5bac1728c04435e35655db
-  data.tar.gz: d9c7c1c69e49acd89738f44900502bc83aea08341b84a9f8d9e02588261889a24a935dfa6509394514a575a4b17d8dcf0ca512518e8b0e089369a8fd37b44d52
+  metadata.gz: d45d3a428c1403b999be51a831e44206ed1636bbfd7603cee7c4e71d03ec2e2e3941b329deb30b18aa4b1021f0b0360726898017ee48933a2262ebaf6c1980df
+  data.tar.gz: da44d07b913e0efff2aff07ff545f5996806601b33ca69b707c5e462d0858ad85e613b5ad6b8d4d53cdd21dd1d80852acf5b71b7359b3b26c2ab10437730873c

data/lib/async/barrier.md

@@ -18,7 +18,7 @@ Sync do
 	# Sleep sort the numbers:
 	numbers.each do |number|
 		barrier.async do |task|
-			task.sleep(number)
+			sleep(number)
 			sorted << number
 		end
 	end

data/lib/async/clock.rb

@@ -61,5 +61,14 @@ module Async
 			
 			return total
 		end
+		
+		# Reset the total elapsed time. If the clock is currently running, reset the start time to now.
+		def reset!
+			@total = 0
+			
+			if @started
+				@started = Clock.now
+			end
+		end
 	end
 end

data/lib/async/condition.md

@@ -15,7 +15,7 @@ Sync do
 	end
 	
 	Async do |task|
-		task.sleep(1)
+		sleep(1)
 		Console.info "Signalling condition..."
 		condition.signal("Hello World")
 	end

data/lib/async/limited_queue.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Samuel Williams.
+
+# The implementation lives in `queue.rb` but later we may move it here for better autoload/inference.
+require_relative "queue"

data/lib/async/queue.rb

@@ -45,7 +45,9 @@ module Async
 		end
 		
 		# Compatibility with {::Queue#push}.
-		alias << push
+		def <<(item)
+			self.push(item)
+		end
 		
 		# Add multiple items to the queue.
 		def enqueue(*items)
@@ -64,7 +66,9 @@ module Async
 		end
 		
 		# Compatibility with {::Queue#pop}.
-		alias pop dequeue
+		def pop
+			self.dequeue
+		end
 		
 		# Process each item in the queue.
 		#
@@ -125,7 +129,7 @@ module Async
 		# 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 <<(item)
+		def push(item)
 			while limited?
 				@full.wait
 			end

data/lib/async/scheduler.rb

@@ -15,9 +15,17 @@ require "console"
 require "resolv"
 
 module Async
+	begin
+		require "fiber/profiler"
+		Profiler = Fiber::Profiler
+	rescue LoadError
+		# Fiber::Profiler is not available.
+		Profiler = nil
+	end
+	
 	# Handles scheduling of fibers. Implements the fiber scheduler interface.
 	class Scheduler < Node
-		DEFAULT_WORKER_POOL = ENV.fetch("ASYNC_SCHEDULER_DEFAULT_WORKER_POOL", nil).then do |value|
+		WORKER_POOL = ENV.fetch("ASYNC_SCHEDULER_WORKER_POOL", nil).then do |value|
 			value == "true" ? true : nil
 		end
 		
@@ -42,10 +50,12 @@ module Async
 		# @public Since *Async v1*.
 		# @parameter parent [Node | Nil] The parent node to use for task hierarchy.
 		# @parameter selector [IO::Event::Selector] The selector to use for event handling.
-		def initialize(parent = nil, selector: nil, worker_pool: DEFAULT_WORKER_POOL)
+		def initialize(parent = nil, selector: nil, profiler: Profiler&.default, worker_pool: WORKER_POOL)
 			super(parent)
 			
 			@selector = selector || ::IO::Event::Selector.new(Fiber.current)
+			@profiler = profiler
+			
 			@interrupted = false
 			
 			@blocked = 0
@@ -492,13 +502,19 @@ module Async
 		def run(...)
 			Kernel.raise ClosedError if @selector.nil?
 			
-			initial_task = self.async(...) if block_given?
-			
-			self.run_loop do
-				run_once
+			begin
+				@profiler&.start
+				
+				initial_task = self.async(...) if block_given?
+				
+				self.run_loop do
+					run_once
+				end
+				
+				return initial_task
+			ensure
+				@profiler&.stop
 			end
-			
-			return initial_task
 		end
 		
 		# Start an asynchronous task within the specified reactor. The task will be executed until the first blocking call, at which point it will yield and and this method will return.

data/lib/async/task.rb

@@ -181,7 +181,10 @@ module Async
 			@status == :completed
 		end
 		
-		alias complete? completed?
+		# Alias for {#completed?}.
+		def complete?
+			self.completed?
+		end
 		
 		# @attribute [Symbol] The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.
 		attr :status

data/lib/async/variable.rb

@@ -31,7 +31,10 @@ module Async
 			condition.signal(value)
 		end
 		
-		alias value= resolve
+		# Alias for {#resolve}.
+		def value=(value)
+			self.resolve(value)
+		end
 		
 		# Whether the value has been resolved.
 		#
@@ -48,6 +51,9 @@ module Async
 			return @value
 		end
 		
-		alias value wait
+		# 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.21.1"
+	VERSION = "2.23.0"
 end

data/lib/async/worker_pool.rb

@@ -10,6 +10,7 @@ module Async
 	#
 	# @private
 	class WorkerPool
+		# Used to augment the scheduler to add support for blocking operations.
 		module BlockingOperationWait
 			# Wait for the given work to be executed.
 			#
@@ -23,7 +24,11 @@ module Async
 			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
@@ -33,6 +38,7 @@ module Async
 				@thread = nil
 			end
 			
+			# Execute the work and resolve the promise.
 			def call
 				work = nil
 				
@@ -67,6 +73,7 @@ module Async
 				end
 			end
 			
+			# Cancel the work and raise an exception in the background thread.
 			def cancel
 				return unless @work
 				
@@ -77,6 +84,9 @@ module Async
 				end
 			end
 			
+			# Wait for the work to be done.
+			#
+			# @returns [Object] The result of the work.
 			def wait
 				@guard.synchronize do
 					while @state == :pending
@@ -92,19 +102,22 @@ module Async
 			end
 		end
 		
-		# A handle to the work being done.
+		# 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

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

@@ -8,10 +8,13 @@ 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/traces/provider/async/task.rb

@@ -8,20 +8,31 @@ 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
-				}
+				attributes["annotation"] = annotation
 			end
 			
 			Traces.trace("async.task", attributes: attributes) do
+				# Yes, this is correct, we already called super above:
 				yield
 			end
 		end

data/readme.md

@@ -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
 
@@ -23,7 +24,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.
 
@@ -35,6 +36,11 @@ 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.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)
+
 ### v2.21.1
 
   - [Worker Pool](https://socketry.github.io/async/releases/index#worker-pool)

data/releases.md

@@ -1,5 +1,29 @@
 # 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
@@ -8,7 +32,7 @@ Ruby 3.4 will feature a new fiber scheduler hook, `blocking_operation_wait` whic
 
 The Async scheduler optionally supports this feature using a worker pool, by using the following environment variable:
 
-    ASYNC_SCHEDULER_DEFAULT_WORKER_POOL=true
+    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.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.21.1
+  version: 2.23.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -31,7 +31,6 @@ authors:
 - Sokolov Yura
 - Stefan Wrobel
 - Trevor Turk
-autorequire:
 bindir: bin
 cert_chain:
 - |
@@ -63,7 +62,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-27 00:00:00.000000000 Z
+date: 2025-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -99,22 +98,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.6'
-    - - ">="
+        version: '1.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !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: []
@@ -127,6 +146,7 @@ files:
 - 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
@@ -160,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
@@ -175,8 +194,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A concurrency framework for Ruby.
 test_files: []