async-limiter 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 324fe64138f3bd6854bc8d5349b8404a01d6bd11ee64f5b0ad204d4154efa15b
-  data.tar.gz: 4cc2963430befada104733f236d4e59b900750c1e3eeeb73fc18f2dece26c5b2
+  metadata.gz: d153319af347142e9837f3a8e7523f47f2bbd28d56e497d03c0fd7279302af8f
+  data.tar.gz: 9d1da2a75240ba77a68d26141abf50b677d5248b9bf191a50e8821aac3bceee7
 SHA512:
-  metadata.gz: 815670fb97ad80d90e9a5a6ec9034f51242fe793784220af2b3ce769b3afd49389a03a0d53ac042aa98638affef8636607976f6908f834e667ab31ac96fbb628
-  data.tar.gz: 5f8df98d26156a041023d05e9c758a17eeefca437cd9ffa34c9a102df820a3e45380dbda8e09b23dd14e189014a49554745349ff13de70647d59a7a5abe33d4d
+  metadata.gz: a35d89989f3d8faf3cd203a84b2e04125809ae07d6609ce0dc205214f97bc1bf11ab099bbc46542a3fa701674185e641461d548f67bb1d1325b8badce9b6c6cc
+  data.tar.gz: df563bd337ae1e9157df61f0b47ae35d1e536b15ad5c0e7cb6fe7ebf48f32bf18249185307aa07d287c3c54df90f8463ce014531763536bd8f92428c0d13e0f9

data/context/generic-limiter.md

@@ -35,7 +35,7 @@ require "async/limiter"
 
 Async do
 	limiter = Async::Limiter::Generic.new
-
+	
 	# Create async tasks through the limiter:
 	tasks = 5.times.map do |i|
 		limiter.async do |task|
@@ -81,7 +81,7 @@ Async do
 	# Allow unlimited concurrency but rate limit to 10 operations per second:
 	timing = Async::Limiter::Timing::LeakyBucket.new(10.0, 50.0)
 	limiter = Async::Limiter::Generic.new(timing: timing)
-
+	
 	# All tasks start immediately, but timing strategy controls rate:
 	100.times do |i|
 		limiter.async do |task|

data/context/getting-started.md

@@ -86,7 +86,7 @@ Async do
 	
 	limiter.acquire(timeout: 3)
 	# => nil
-
+	
 	limiter.acquire(timeout: 3) do
 		puts "Acquired."
 	end or puts "Timed out!"
@@ -199,8 +199,8 @@ fair_limiter.acquire(cost: 8.0) do
 end
 
 # These must wait even though they need fewer tokens
-fair_limiter.acquire(cost: 0.5) { puts "Quick op 1" }  # Blocked
-fair_limiter.acquire(cost: 0.5) { puts "Quick op 2" }  # Blocked
+fair_limiter.acquire(cost: 0.5){puts "Quick op 1"}  # Blocked
+fair_limiter.acquire(cost: 0.5){puts "Quick op 2"}  # Blocked
 ```
 
 #### Choosing the Right Strategy

data/context/limited-limiter.md

@@ -89,16 +89,16 @@ The limiter prevents convoy effects where quick timeouts aren't blocked by slow
 limiter = Async::Limiter::Limited.new(1)
 Async do
 	limiter.acquire  # Fill to capacity.
-
+	
 	results = []
-
+	
 	# Start multiple tasks with different timeouts:
 	tasks = [
-		Async {limiter.acquire(timeout: 1.0); results << "Long timeout."},
-		Async {limiter.acquire(timeout: 0.1); results << "Short timeout."},
-		Async {limiter.acquire(timeout: 0);   results << "Non-blocking."},
+		Async{limiter.acquire(timeout: 1.0); results << "Long timeout."},
+		Async{limiter.acquire(timeout: 0.1); results << "Short timeout."},
+		Async{limiter.acquire(timeout: 0);   results << "Non-blocking."},
 	]
-
+	
 	# All tasks complete quickly, even with a long timeout task present:
 	tasks.map(&:wait)
 	puts results

data/context/queued-limiter.md

@@ -42,7 +42,7 @@ For fine-grained control over resource lifecycle:
 
 ```ruby
 queue = Async::Queue.new
-3.times { |i| queue.push("resource_#{i}") }
+3.times{|i| queue.push("resource_#{i}")}
 
 limiter = Async::Limiter::Queued.new(queue)
 
@@ -71,7 +71,7 @@ Async do
 	queue = Async::PriorityQueue.new
 	limiter = Async::Limiter::Queued.new(queue)
 	results = []
-
+	
 	# Start tasks with different priorities
 	tasks = [
 		Async do
@@ -100,9 +100,9 @@ Async do
 	2.times do |i|
 		limiter.release("worker_#{i}")
 	end
-
+	
 	tasks.each(&:wait)
-
+	
 	puts results
 	# High priority task gets resource first, then medium, then low.
 end

data/context/timing-strategies.md

@@ -385,7 +385,7 @@ require "async/queue"
 
 # Create resource queue
 queue = Async::Queue.new
-3.times { |i| queue.push("worker_#{i}") }
+3.times{|i| queue.push("worker_#{i}")}
 
 # Add timing constraint
 timing = Async::Limiter::Timing::FixedWindow.new(2.0,
@@ -437,8 +437,8 @@ class RateLimitedAPIClient
 	
 	def make_request(endpoint, cost: 1.0)
 		@limiter.acquire(cost: cost) do
-		# Make actual HTTP request:
-		puts "Making request to #{endpoint} at #{Time.now}"
+			# Make actual HTTP request:
+			puts "Making request to #{endpoint} at #{Time.now}"
 			simulate_http_request(endpoint)
 		end
 	end

data/lib/async/limiter/generic.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
 require "async/task"
 require "async/deadline"
+require "async/utilization"
+require "json"
 require_relative "timing/none"
 require_relative "timing/sliding_window"
 require_relative "token"
@@ -23,10 +25,12 @@ module Async
 			# Initialize a new generic limiter.
 			# @parameter timing [#acquire, #wait, #maximum_cost] Strategy for timing constraints.
 			# @parameter parent [Async::Task, nil] Parent task for creating child tasks.
-			def initialize(timing: Timing::None, parent: nil, tags: nil)
+			# @parameter utilization [#metric] Registry-like object for utilization metrics.
+			def initialize(timing: Timing::None, parent: nil, tags: nil, utilization: Async::Utilization::Registry.new)
 				@timing = timing
 				@parent = parent
 				@tags = tags
+				@utilization = utilization
 				
 				@mutex = Mutex.new
 			end
@@ -34,6 +38,9 @@ module Async
 			# @attribute [Array(String)] Tags associated with this limiter for identification or categorization.
 			attr :tags
 			
+			# @attribute [#metric] Registry-like object for utilization metrics.
+			attr :utilization
+			
 			# @returns [Boolean] Whether this limiter is currently limiting concurrency.
 			def limited?
 				false
@@ -66,7 +73,7 @@ module Async
 			end
 			
 			# Manually acquire a resource with timing and concurrency coordination.
-			# 
+			#
 			# This method provides the core acquisition logic with support for:
 			# - Flexible timeout handling (blocking, non-blocking, timed)
 			# - Cost-based consumption for timing strategies
@@ -135,6 +142,18 @@ module Async
 				end
 			end
 			
+			# Get a JSON-compatible representation of the limiter statistics.
+			# @returns [Hash] Statistics hash with current state.
+			def as_json(...)
+				statistics
+			end
+			
+			# Get a JSON string representation of the limiter statistics.
+			# @returns [String] JSON encoded statistics.
+			def to_json(...)
+				as_json.to_json(...)
+			end
+			
 			protected
 			
 			def acquire_synchronized(timeout, cost, **options)

data/lib/async/limiter/limited.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2020, by Bruno Sutic.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "generic"
@@ -20,16 +20,22 @@ module Async
 		class Limited < Generic
 			# Initialize a limited concurrency limiter.
 			# @parameter limit [Integer] Maximum concurrent tasks allowed.
-			# @parameter timing [#acquire, #wait, #maximum_cost] Strategy for timing constraints.
-			# @parameter parent [Async::Task, nil] Parent task for creating child tasks.
+			# @parameter options [Hash] Options passed to {Generic#initialize}.
 			# @raises [ArgumentError] If limit is not positive.
-			def initialize(limit = 1, timing: Timing::None, parent: nil)
-				super(timing: timing, parent: parent)
+			def initialize(limit = 1, **options)
+				super(**options)
 				
 				@limit = limit
 				@count = 0
 				
 				@available = ConditionVariable.new
+				
+				@acquired_count_metric = @utilization.metric(:acquired_count)
+				@available_count_metric = @utilization.metric(:available_count)
+				@waiting_count_metric = @utilization.metric(:waiting_count)
+				@reacquire_waiting_count_metric = @utilization.metric(:reacquire_waiting_count)
+				
+				update_utilization_metrics
 			end
 			
 			# @attribute [Integer] The maximum number of concurrent tasks.
@@ -38,6 +44,26 @@ module Async
 			# @attribute [Integer] Current count of active tasks.
 			attr_reader :count
 			
+			# @returns [Integer] Current count of active tasks.
+			def acquired_count
+				@mutex.synchronize{@count}
+			end
+			
+			# @returns [Integer] Current count of available capacity.
+			def available_count
+				@mutex.synchronize{@limit - @count}
+			end
+			
+			# @returns [Integer] Current count of tasks waiting for capacity.
+			def waiting_count
+				@waiting_count_metric.value
+			end
+			
+			# @returns [Integer] Current count of reacquiring tasks waiting for capacity.
+			def reacquire_waiting_count
+				@reacquire_waiting_count_metric.value
+			end
+			
 			# Check if a new task can be acquired.
 			# @returns [Boolean] True if under the limit.
 			def limited?
@@ -51,6 +77,7 @@ module Async
 				@mutex.synchronize do
 					old_limit = @limit
 					@limit = new_limit
+					update_utilization_metrics
 					
 					# Wake up waiting tasks if limit increased:
 					@available.broadcast if new_limit > old_limit
@@ -64,6 +91,10 @@ module Async
 					{
 						limit: @limit,
 						count: @count,
+						acquired_count: @count,
+						available_count: @limit - @count,
+						waiting_count: @waiting_count_metric.value,
+						reacquire_waiting_count: @reacquire_waiting_count_metric.value,
 						timing: @timing.statistics
 					}
 				end
@@ -72,32 +103,57 @@ module Async
 			protected
 			
 			# Acquire resource with optional deadline.
-			def acquire_resource(deadline, **options)
+			def acquire_resource(deadline, reacquire: false, **options)
 				# Fast path: immediate return for expired deadlines, but only if at capacity
 				return nil if deadline&.expired? && @count >= @limit
 				
+				waiting = false
+				acquired = false
+				
 				# Wait for capacity with deadline tracking
 				while @count >= @limit
 					remaining = deadline&.remaining
 					return nil if remaining && remaining <= 0
 					
+					unless waiting
+						@waiting_count_metric.increment
+						@reacquire_waiting_count_metric.increment if reacquire
+						waiting = true
+					end
+					
 					unless @available.wait(@mutex, remaining)
 						return nil  # Timeout exceeded
 					end
 				end
 				
 				@count += 1
+				acquired = true
 				
 				return true
+			ensure
+				if waiting
+					@waiting_count_metric.decrement
+					@reacquire_waiting_count_metric.decrement if reacquire
+				end
+				
+				update_utilization_metrics if acquired
 			end
 			
 			# Release resource.
 			def release_resource(resource)
 				@mutex.synchronize do
 					@count -= 1
+					update_utilization_metrics
 					@available.signal
 				end
 			end
+			
+			private
+			
+			def update_utilization_metrics
+				@acquired_count_metric.set(@count)
+				@available_count_metric.set(@limit - @count)
+			end
 		end
 	end
 end

data/lib/async/limiter/queued.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Francisco Mejia.
-# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025-2026, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "generic"
@@ -28,16 +28,42 @@ module Async
 			
 			# Initialize a queue-based limiter.
 			# @parameter queue [#push, #pop, #empty?] Thread-safe queue containing pre-existing resources.
-			# @parameter timing [#acquire, #wait, #maximum_cost] Strategy for timing constraints.
-			# @parameter parent [Async::Task, nil] Parent task for creating child tasks.
-			def initialize(queue = self.class.default_queue, timing: Timing::None, parent: nil)
-				super(timing: timing, parent: parent)
+			# @parameter options [Hash] Options passed to {Generic#initialize}.
+			def initialize(queue = self.class.default_queue, **options)
+				super(**options)
 				@queue = queue
+				
+				@acquired_count_metric = @utilization.metric(:acquired_count)
+				@available_count_metric = @utilization.metric(:available_count)
+				@waiting_count_metric = @utilization.metric(:waiting_count)
+				@reacquire_waiting_count_metric = @utilization.metric(:reacquire_waiting_count)
+				
+				update_utilization_metrics
 			end
 			
 			# @attribute [Queue] The queue managing resources.
 			attr_reader :queue
 			
+			# @returns [Integer] Current count of acquired resources.
+			def acquired_count
+				@acquired_count_metric.value
+			end
+			
+			# @returns [Integer] Current count of available resources.
+			def available_count
+				@queue.size
+			end
+			
+			# @returns [Integer] Current count of tasks waiting for resources.
+			def waiting_count
+				@queue.waiting_count
+			end
+			
+			# @returns [Integer] Current count of reacquiring tasks waiting for resources.
+			def reacquire_waiting_count
+				@reacquire_waiting_count_metric.value
+			end
+			
 			# Check if a new task can be acquired.
 			# @returns [Boolean] True if resources are available.
 			def limited?
@@ -51,6 +77,8 @@ module Async
 				count.times do
 					@queue.push(value)
 				end
+				
+				update_utilization_metrics
 			end
 			
 			# Get current limiter statistics.
@@ -60,6 +88,10 @@ module Async
 					{
 						waiting: @queue.waiting_count,
 						available: @queue.size,
+						acquired_count: @acquired_count_metric.value,
+						available_count: @queue.size,
+						waiting_count: @queue.waiting_count,
+						reacquire_waiting_count: @reacquire_waiting_count_metric.value,
 						timing: @timing.statistics
 					}
 				end
@@ -69,16 +101,36 @@ module Async
 			
 			# Acquire a resource from the queue with optional deadline.
 			def acquire_resource(deadline, reacquire: false, **options)
+				@reacquire_waiting_count_metric.increment if reacquire
+				update_utilization_metrics if reacquire
+				
 				@mutex.unlock
-				return @queue.pop(timeout: deadline&.remaining, **options)
+				resource = @queue.pop(timeout: deadline&.remaining, **options)
+				return resource
 			ensure
 				@mutex.lock
+				@reacquire_waiting_count_metric.decrement if reacquire
+				@acquired_count_metric.increment if resource
+				update_utilization_metrics if reacquire || resource
 			end
 			
 			# Release a previously acquired resource back to the queue.
 			def release_resource(value)
+				@mutex.synchronize do
+					@acquired_count_metric.decrement if @acquired_count_metric.value > 0
+					update_utilization_metrics
+				end
+				
 				# Return a default resource to the queue:
 				@queue.push(value)
+				update_utilization_metrics
+			end
+			
+			private
+			
+			def update_utilization_metrics
+				@available_count_metric.set(@queue.size)
+				@waiting_count_metric.set(@queue.waiting_count)
 			end
 		end
 	end

data/lib/async/limiter/timing/fixed_window.rb

@@ -4,6 +4,7 @@
 # Copyright, 2020, by Bruno Sutic.
 # Copyright, 2025, by Shopify Inc.
 # Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by William T. Nelson.
 
 require_relative "sliding_window"
 
@@ -25,8 +26,6 @@ module Async
 				# Get current timing strategy statistics.
 				# @returns [Hash] Statistics hash with current state.
 				def statistics
-					current_time = Time.now
-					
 					{
 						name: "FixedWindow",
 						window_duration: @duration,

data/lib/async/limiter/version.rb

@@ -7,6 +7,6 @@
 
 module Async
 	module Limiter
-		VERSION = "2.0.0"
+		VERSION = "2.2.0"
 	end
 end

data/license.md

@@ -2,9 +2,9 @@
 
 Copyright, 2020-2021, by Bruno Sutic.  
 Copyright, 2025, by Francisco Mejia.  
-Copyright, 2025, by Shopify Inc.  
-Copyright, 2025, by Samuel Williams.  
-Copyright, 2025, by William T. Nelson.  
+Copyright, 2025-2026, by Shopify Inc.  
+Copyright, 2025-2026, by Samuel Williams.  
+Copyright, 2025-2026, by William T. Nelson.  
 
 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

@@ -20,6 +20,35 @@ Please see the [project documentation](https://socketry.github.io/async-limiter/
 
   - [Token Usage](https://socketry.github.io/async-limiter/guides/token-usage/index) - This guide explains how to use tokens for advanced resource management with `async-limiter`. Tokens provide sophisticated resource handling with support for re-acquisition and automatic cleanup.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-limiter/releases/index) for all releases.
+
+### v2.2.0
+
+  - Add `async-utilization` metrics for limiter telemetry counters.
+
+### v2.1.0
+
+  - Add telemetry counters to `Async::Limiter::Limited` and `Async::Limiter::Queued`: `acquired_count`, `available_count`, `waiting_count`, and `reacquire_waiting_count` for observability into limiter state.
+  - Add `as_json` and `to_json` methods to `Async::Limiter::Generic` for JSON serialization of limiter statistics.
+  - Fix unused variable warning in `Async::Limiter::Timing::FixedWindow`.
+
+### v2.0.0
+
+The 2.0.x release should be considered somewhat unstable.
+
+  - **Breaking**: Complete API redesign. The v1.x classes (`Async::Limiter::Concurrent`, `Async::Limiter::Unlimited`, etc.) have been replaced with a new inheritance-based architecture.
+  - **Breaking**: Removed `blocking?` method due to inherent race conditions. Use `acquire(timeout: 0)` for non-blocking checks.
+  - **Breaking**: Timing strategies now use consumption-only model (no explicit `release` methods).
+  - **Breaking**: Window classes moved from `limiter/window/` to `limiter/timing/` with renamed classes.
+  - [New Architecture (replaces v1.x classes)](https://socketry.github.io/async-limiter/releases/index#new-architecture-\(replaces-v1.x-classes\))
+  - [Advanced Timeout Features](https://socketry.github.io/async-limiter/releases/index#advanced-timeout-features)
+  - [Cost-Based Acquisition](https://socketry.github.io/async-limiter/releases/index#cost-based-acquisition)
+  - [Enhanced Timing Strategies](https://socketry.github.io/async-limiter/releases/index#enhanced-timing-strategies)
+  - [Token-Based Resource Management](https://socketry.github.io/async-limiter/releases/index#token-based-resource-management)
+  - [Thread Safety and Performance](https://socketry.github.io/async-limiter/releases/index#thread-safety-and-performance)
+
 ## See Also
 
   - [falcon](https://github.com/socketry/falcon) - A high-performance web server
@@ -36,6 +65,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### 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.

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v2.2.0
+
+  - Add `async-utilization` metrics for limiter telemetry counters.
+
+## v2.1.0
+
+  - Add telemetry counters to `Async::Limiter::Limited` and `Async::Limiter::Queued`: `acquired_count`, `available_count`, `waiting_count`, and `reacquire_waiting_count` for observability into limiter state.
+  - Add `as_json` and `to_json` methods to `Async::Limiter::Generic` for JSON serialization of limiter statistics.
+  - Fix unused variable warning in `Async::Limiter::Timing::FixedWindow`.
+
 ## v2.0.0
 
 The 2.0.x release should be considered somewhat unstable.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-limiter
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Bruno Sutic
 - Shopify Inc.
 - Samuel Williams
+- William T. Nelson
 - Francisco Mejia
-- William
 bindir: bin
 cert_chain:
 - |
@@ -56,6 +56,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.31'
+- !ruby/object:Gem::Dependency
+  name: async-utilization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -99,14 +113,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Execution rate limiting for Async
 test_files: []