async-limiter 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 324fe64138f3bd6854bc8d5349b8404a01d6bd11ee64f5b0ad204d4154efa15b
-  data.tar.gz: 4cc2963430befada104733f236d4e59b900750c1e3eeeb73fc18f2dece26c5b2
+  metadata.gz: d9b6e7e0d162f4068ced173efa8f365f53e809bf36b80fb41c21988865ea558b
+  data.tar.gz: d6ed3ed9482da942bf2fdec9403d2c842174eaa090cf0ea61036cf839c731d9c
 SHA512:
-  metadata.gz: 815670fb97ad80d90e9a5a6ec9034f51242fe793784220af2b3ce769b3afd49389a03a0d53ac042aa98638affef8636607976f6908f834e667ab31ac96fbb628
-  data.tar.gz: 5f8df98d26156a041023d05e9c758a17eeefca437cd9ffa34c9a102df820a3e45380dbda8e09b23dd14e189014a49554745349ff13de70647d59a7a5abe33d4d
+  metadata.gz: 496cd5748700aa4c7eb897fc2c47720ea10c7650ab2407e0d15394ce56d44c1d7bd82a31f4138b9437d1e0e474449defe2a5f190d2140f41bc44afafa68bfe8b
+  data.tar.gz: 8733a7138915188e423fee9f9b4213cc087d93b86f69a43e3ac7954272e94eb15ef99e2ea100ccfd621aebc6d4f292267c298d609f559448f92e45c7c8ffb0dd

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,12 @@
 # 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 "json"
 require_relative "timing/none"
 require_relative "timing/sliding_window"
 require_relative "token"
@@ -135,6 +136,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"
@@ -28,6 +28,8 @@ module Async
 				
 				@limit = limit
 				@count = 0
+				@waiting_count = 0
+				@reacquire_waiting_count = 0
 				
 				@available = ConditionVariable.new
 			end
@@ -38,6 +40,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
+				@mutex.synchronize{@waiting_count}
+			end
+			
+			# @returns [Integer] Current count of reacquiring tasks waiting for capacity.
+			def reacquire_waiting_count
+				@mutex.synchronize{@reacquire_waiting_count}
+			end
+			
 			# Check if a new task can be acquired.
 			# @returns [Boolean] True if under the limit.
 			def limited?
@@ -64,6 +86,10 @@ module Async
 					{
 						limit: @limit,
 						count: @count,
+						acquired_count: @count,
+						available_count: @limit - @count,
+						waiting_count: @waiting_count,
+						reacquire_waiting_count: @reacquire_waiting_count,
 						timing: @timing.statistics
 					}
 				end
@@ -72,15 +98,23 @@ 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
+				
 				# Wait for capacity with deadline tracking
 				while @count >= @limit
 					remaining = deadline&.remaining
 					return nil if remaining && remaining <= 0
 					
+					unless waiting
+						@waiting_count += 1
+						@reacquire_waiting_count += 1 if reacquire
+						waiting = true
+					end
+					
 					unless @available.wait(@mutex, remaining)
 						return nil  # Timeout exceeded
 					end
@@ -89,6 +123,11 @@ module Async
 				@count += 1
 				
 				return true
+			ensure
+				if waiting
+					@waiting_count -= 1
+					@reacquire_waiting_count -= 1 if reacquire
+				end
 			end
 			
 			# Release resource.

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"
@@ -33,11 +33,33 @@ module Async
 			def initialize(queue = self.class.default_queue, timing: Timing::None, parent: nil)
 				super(timing: timing, parent: parent)
 				@queue = queue
+				@acquired_count = 0
+				@reacquire_waiting_count = 0
 			end
 			
 			# @attribute [Queue] The queue managing resources.
 			attr_reader :queue
 			
+			# @returns [Integer] Current count of acquired resources.
+			def acquired_count
+				@mutex.synchronize{@acquired_count}
+			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
+				@mutex.synchronize{@reacquire_waiting_count}
+			end
+			
 			# Check if a new task can be acquired.
 			# @returns [Boolean] True if resources are available.
 			def limited?
@@ -60,6 +82,10 @@ module Async
 					{
 						waiting: @queue.waiting_count,
 						available: @queue.size,
+						acquired_count: @acquired_count,
+						available_count: @queue.size,
+						waiting_count: @queue.waiting_count,
+						reacquire_waiting_count: @reacquire_waiting_count,
 						timing: @timing.statistics
 					}
 				end
@@ -69,14 +95,23 @@ module Async
 			
 			# Acquire a resource from the queue with optional deadline.
 			def acquire_resource(deadline, reacquire: false, **options)
+				@reacquire_waiting_count += 1 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 -= 1 if reacquire
+				@acquired_count += 1 if resource
 			end
 			
 			# Release a previously acquired resource back to the queue.
 			def release_resource(value)
+				@mutex.synchronize do
+					@acquired_count -= 1 if @acquired_count > 0
+				end
+				
 				# Return a default resource to the queue:
 				@queue.push(value)
 			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.1.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,31 @@ 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.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 +61,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,11 @@
 # Releases
 
+## 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.1.0
 platform: ruby
 authors:
 - Bruno Sutic
 - Shopify Inc.
 - Samuel Williams
+- William T. Nelson
 - Francisco Mejia
-- William
 bindir: bin
 cert_chain:
 - |
@@ -99,14 +99,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: []