async 2.21.0 → 2.21.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a5bc2e233137c26a571123a0edc0cd22fe32278f780fe801c166a2c7968dc83
-  data.tar.gz: 2c2aab55da8cfe72e2806a6bb1e4a18e3b20d7162ff929bcb91de019eb9c6da3
+  metadata.gz: '0821852f6bb8e8b82506934a6ad8e921270f121636453303a2fd6409cacd83e2'
+  data.tar.gz: 56992a10ff23bcba8dfa535f7c134ac2870a10dd62f7776ea9e109d5e14e0b05
 SHA512:
-  metadata.gz: 9f3490b820e58aa4e6a3a95051bc36b699903f617918832f557b4a3369c7101a9c36cf878b34ab274caa1379591c30fef0f56cac79dbf1da482b16472c9cde1d
-  data.tar.gz: 8c911bdb5a50dadc299ee4d7ed0cd6d16371b84fe622fb1542190fc5a586f914dca4a5396de481f826c8606d547df831357f783f3ee67da3de18e49dd5ad7dd6
+  metadata.gz: 17791af587852dbb46ab3cb6b5584c10d7073997d1ba21eabed248fe1dc6a9107902ac34cf8741efacdfa01e87d57aa515f22635310fa35697ee56acd5cd03ee
+  data.tar.gz: e0a7fc1d5cd13632ceaa93e9ccb41ff89ec38648d8ca6d5eb2831ea39cb014d2fb8046c3226d94d7101a5d289cecaff338fcf65c440627ae76cdd44a93e624a6

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

@@ -7,6 +7,7 @@
 
 require_relative "clock"
 require_relative "task"
+require_relative "worker_pool"
 
 require "io/event"
 
@@ -16,6 +17,10 @@ require "resolv"
 module Async
 	# 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|
+			value == "true" ? true : nil
+		end
+		
 		# Raised when an operation is attempted on a closed scheduler.
 		class ClosedError < RuntimeError
 			# Create a new error.
@@ -37,7 +42,7 @@ 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)
+		def initialize(parent = nil, selector: nil, worker_pool: DEFAULT_WORKER_POOL)
 			super(parent)
 			
 			@selector = selector || ::IO::Event::Selector.new(Fiber.current)
@@ -49,6 +54,15 @@ module Async
 			@idle_time = 0.0
 			
 			@timers = ::IO::Event::Timers.new
+			if worker_pool == true
+				@worker_pool = WorkerPool.new
+			else
+				@worker_pool = worker_pool
+			end
+			
+			if @worker_pool
+				self.singleton_class.prepend(WorkerPool::BlockingOperationWait)
+			end
 		end
 		
 		# Compute the scheduler load according to the busy and idle times that are updated by the run loop.
@@ -112,6 +126,11 @@ module Async
 			
 			selector&.close
 			
+			worker_pool = @worker_pool
+			@worker_pool = nil
+			
+			worker_pool&.close
+			
 			consume
 		end
 		
@@ -169,8 +188,11 @@ module Async
 		
 		# Invoked when a fiber tries to perform a blocking operation which cannot continue. A corresponding call {unblock} must be performed to allow this fiber to continue.
 		#
-
+		# @public Since *Async v2*.
 		# @asynchronous May only be called on same thread as fiber scheduler.
+		#
+		# @parameter blocker [Object] The object that is blocking the fiber.
+		# @parameter timeout [Float | Nil] The maximum time to block, or if nil, indefinitely.
 		def block(blocker, timeout)
 			# $stderr.puts "block(#{blocker}, #{Fiber.current}, #{timeout})"
 			fiber = Fiber.current
@@ -338,25 +360,6 @@ module Async
 			return @selector.process_wait(Fiber.current, pid, flags)
 		end
 		
-		# 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)
-			thread = Thread.new(&work)
-			
-			result = thread.join
-			
-			thread = nil
-			
-			return result
-		ensure
-			thread&.kill
-		end
-		
 		# Run one iteration of the event loop.
 		#
 		# When terminating the event loop, we already know we are finished. So we don't need to check the task tree. This is a logical requirement because `run_once` ignores transient tasks. For example, a single top level transient task is not enough to keep the reactor running, but during termination we must still process it in order to terminate child tasks.

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.0"
+	VERSION = "2.21.2"
 end

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/traces/provider/async/task.rb

@@ -12,13 +12,17 @@ Traces::Provider(Async::Task) do
 			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?,
+		}
+		
 		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

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
 
@@ -35,6 +36,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.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)

data/releases.md

@@ -1,5 +1,19 @@
 # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async
 version: !ruby/object:Gem::Version
-  version: 2.21.0
+  version: 2.21.2
 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-21 00:00:00.000000000 Z
+date: 2025-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: console
@@ -113,8 +112,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.6.5
-description:
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -127,6 +124,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
@@ -141,6 +139,7 @@ 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
@@ -159,7 +158,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
@@ -174,8 +172,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: []