async 2.33.0 → 2.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c7cade6749e8ff99e40808a8aaf7f334312e1975e4f4e349b96271cbc157caf
-  data.tar.gz: 42d523251a8904087917cb000f26d5b17c5bb69ec45d88cfbb6deebaade1923f
+  metadata.gz: 05c05a5ba6d2dc436a12de9ff3cb562b3376892fd8c6615be8c4eb654d570fef
+  data.tar.gz: 2cb04cbecc3237b4476e5f42e4e130e8116ea10890c1b766140b238451c13f81
 SHA512:
-  metadata.gz: 13d7fedf21c2ecf283d5e541af4e11f523eefe0c8cc084b7a174483a5483fe6f58d50d8472cd60e393e537d3c12c5312500b54be0f13092ae01ac1ebddd64488
-  data.tar.gz: 2cbd88bab04832b9fc23773977e74dd494f4a9cc8b53e9ec45af04fa80bcdbbbe411c3c8b661a4205e36f7d70f1a789b70e20e1b3c4a77ded4d5b5a96658a5a2
+  metadata.gz: 16d4488b9d5fa9702bba6fead00c9c772402f792817daba79596cdf573e9f7b111ab77b85166d9b7b93c92babd9a717bf8fe11aa56ae67beded351fda99eaa7b
+  data.tar.gz: 289f3a854fcda83b35e92a1ebc14425722fdc856f8dfaa60e29f630ba79b3d72269816f7f01f940aa8926685701cd5ef1ba285a0576f91354107083cfaf96905

data/lib/async/idler.rb

@@ -13,10 +13,13 @@ module Async
 		# @parameter maximum_load [Numeric] The maximum load before we start shedding work.
 		# @parameter backoff [Numeric] The initial backoff time, used for delaying work.
 		# @parameter parent [Interface(:async) | Nil] The parent task to use for async operations.
-		def initialize(maximum_load = 0.8, backoff: 0.01, parent: nil)
+		def initialize(maximum_load = 0.8, backoff: 0.001, parent: nil)
 			@maximum_load = maximum_load
 			@backoff = backoff
+			@current = backoff
+			
 			@parent = parent
+			@mutex = Mutex.new
 		end
 		
 		# Wait until the system is idle, then execute the given block in a new task.
@@ -38,20 +41,29 @@ module Async
 		#
 		# If the scheduler is overloaded, this method will sleep for an exponentially increasing amount of time.
 		def wait
-			scheduler = Fiber.scheduler
-			backoff = nil
-			
-			while true
-				load = scheduler.load
-				
-				break if load < @maximum_load
+			@mutex.synchronize do
+				scheduler = Fiber.scheduler
 				
-				if backoff
-					sleep(backoff)
-					backoff *= 2.0
-				else
-					scheduler.yield
-					backoff = @backoff
+				while true
+					load = scheduler.load
+					
+					if load <= @maximum_load
+						# Even though load is okay, if @current is high, we were recently overloaded. Sleep proportionally to prevent burst after load drop:
+						if @current > @backoff
+							# Sleep a fraction of @current to rate limit:
+							sleep(@current - @backoff)
+							
+							# Decay @current gently towards @backoff:
+							alpha = 0.99
+							@current *= alpha + (1.0 - alpha) * (load / @maximum_load)
+						end
+						
+						break
+					else
+						# We're overloaded, so increase backoff:
+						@current *= (load / @maximum_load)
+						sleep(@current)
+					end
 				end
 			end
 		end

data/lib/async/version.rb

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

data/lib/async.rb

@@ -9,6 +9,7 @@ require_relative "async/reactor"
 
 require_relative "kernel/async"
 require_relative "kernel/sync"
+require_relative "kernel/barrier"
 
 # Asynchronous programming framework.
 module Async

data/lib/kernel/barrier.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "sync"
+require_relative "../async/barrier"
+require_relative "../async/idler"
+
+module Kernel
+	# Create a barrier, yield it to the block, and then wait for all tasks to complete.
+	#
+	# If no scheduler is running, one will be created automatically for the duration of the block.
+	#
+	# By default, the barrier uses an `Async::Idler` to manage load, but this can be overridden by providing a different parent or `nil` to disable load management.
+	#
+	# @parameter parent [Task | Semaphore | Nil] The parent for holding any children tasks.
+	# @parameter **options [Hash] Additional options passed to {Kernel::Sync}.
+	# @public Since *Async v2.34*.
+	def Barrier(parent: Async::Idler.new, **options)
+		Sync(**options) do |task|
+			barrier = ::Async::Barrier.new(parent: parent)
+			
+			yield barrier
+			
+			barrier.wait
+		ensure
+			barrier&.stop
+		end
+	end
+end

data/readme.md

@@ -35,6 +35,10 @@ 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.34.0
+
+  - [`Kernel::Barrier` Convenience Interface](https://socketry.github.io/async/releases/index#kernel::barrier-convenience-interface)
+
 ### v2.33.0
 
   - Introduce `Async::Promise.fulfill` for optional promise resolution.
@@ -80,10 +84,6 @@ This release introduces thread-safety as a core concept of Async. Many core clas
 
   - Suppress excessive warning in `Async::Scheduler#async`.
 
-### v2.27.3
-
-  - Ensure trace attributes are strings, fixes integration with OpenTelemetry.
-
 ## See Also
 
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client/server.

data/releases.md

@@ -1,5 +1,28 @@
 # Releases
 
+## v2.34.0
+
+### `Kernel::Barrier` Convenience Interface
+
+Starting multiple concurrent tasks and waiting for them to finish is a common pattern. This change introduces a small ergonomic helper, `Barrier`, defined in `Kernel`, that encapsulates this behavior: it creates an `Async::Barrier`, yields it to a block, waits for completion (using `Sync` to run a reactor if needed), and ensures remaining tasks are stopped on exit.
+
+``` ruby
+require 'async'
+
+Barrier do |barrier|
+	3.times do |i|
+		barrier.async do |task|
+			sleep(rand * 0.1)  # Simulate work
+			puts "Task #{i} completed"
+		end
+	end
+end
+
+# All tasks are guaranteed to complete or be stopped when the block exits.
+```
+
+If an exception is raised by a task, it will be propagated to the caller, and any remaining tasks will be stopped. The `parent:` parameter can be used to specify a parent task for the barrier, otherwise it will use the current task if available, or create a new reactor if not.
+
 ## v2.33.0
 
   - Introduce `Async::Promise.fulfill` for optional promise resolution.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.33.0
+  version: 2.34.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -180,6 +180,7 @@ files:
 - lib/async/version.rb
 - lib/async/waiter.rb
 - lib/kernel/async.rb
+- lib/kernel/barrier.rb
 - lib/kernel/sync.rb
 - lib/metrics/provider/async.rb
 - lib/metrics/provider/async/task.rb