async-limiter 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b6e7e0d162f4068ced173efa8f365f53e809bf36b80fb41c21988865ea558b
-  data.tar.gz: d6ed3ed9482da942bf2fdec9403d2c842174eaa090cf0ea61036cf839c731d9c
+  metadata.gz: d153319af347142e9837f3a8e7523f47f2bbd28d56e497d03c0fd7279302af8f
+  data.tar.gz: 9d1da2a75240ba77a68d26141abf50b677d5248b9bf191a50e8821aac3bceee7
 SHA512:
-  metadata.gz: 496cd5748700aa4c7eb897fc2c47720ea10c7650ab2407e0d15394ce56d44c1d7bd82a31f4138b9437d1e0e474449defe2a5f190d2140f41bc44afafa68bfe8b
-  data.tar.gz: 8733a7138915188e423fee9f9b4213cc087d93b86f69a43e3ac7954272e94eb15ef99e2ea100ccfd621aebc6d4f292267c298d609f559448f92e45c7c8ffb0dd
+  metadata.gz: a35d89989f3d8faf3cd203a84b2e04125809ae07d6609ce0dc205214f97bc1bf11ab099bbc46542a3fa701674185e641461d548f67bb1d1325b8badce9b6c6cc
+  data.tar.gz: df563bd337ae1e9157df61f0b47ae35d1e536b15ad5c0e7cb6fe7ebf48f32bf18249185307aa07d287c3c54df90f8463ce014531763536bd8f92428c0d13e0f9

data/lib/async/limiter/generic.rb

@@ -6,6 +6,7 @@
 
 require "async/task"
 require "async/deadline"
+require "async/utilization"
 require "json"
 require_relative "timing/none"
 require_relative "timing/sliding_window"
@@ -24,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
@@ -35,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
@@ -67,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

data/lib/async/limiter/limited.rb

@@ -20,18 +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
-				@waiting_count = 0
-				@reacquire_waiting_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.
@@ -52,12 +56,12 @@ module Async
 			
 			# @returns [Integer] Current count of tasks waiting for capacity.
 			def waiting_count
-				@mutex.synchronize{@waiting_count}
+				@waiting_count_metric.value
 			end
 			
 			# @returns [Integer] Current count of reacquiring tasks waiting for capacity.
 			def reacquire_waiting_count
-				@mutex.synchronize{@reacquire_waiting_count}
+				@reacquire_waiting_count_metric.value
 			end
 			
 			# Check if a new task can be acquired.
@@ -73,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
@@ -88,8 +93,8 @@ module Async
 						count: @count,
 						acquired_count: @count,
 						available_count: @limit - @count,
-						waiting_count: @waiting_count,
-						reacquire_waiting_count: @reacquire_waiting_count,
+						waiting_count: @waiting_count_metric.value,
+						reacquire_waiting_count: @reacquire_waiting_count_metric.value,
 						timing: @timing.statistics
 					}
 				end
@@ -103,6 +108,7 @@ module Async
 				return nil if deadline&.expired? && @count >= @limit
 				
 				waiting = false
+				acquired = false
 				
 				# Wait for capacity with deadline tracking
 				while @count >= @limit
@@ -110,8 +116,8 @@ module Async
 					return nil if remaining && remaining <= 0
 					
 					unless waiting
-						@waiting_count += 1
-						@reacquire_waiting_count += 1 if reacquire
+						@waiting_count_metric.increment
+						@reacquire_waiting_count_metric.increment if reacquire
 						waiting = true
 					end
 					
@@ -121,22 +127,33 @@ module Async
 				end
 				
 				@count += 1
+				acquired = true
 				
 				return true
 			ensure
 				if waiting
-					@waiting_count -= 1
-					@reacquire_waiting_count -= 1 if reacquire
+					@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

@@ -28,13 +28,17 @@ 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 = 0
-				@reacquire_waiting_count = 0
+				
+				@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.
@@ -42,7 +46,7 @@ module Async
 			
 			# @returns [Integer] Current count of acquired resources.
 			def acquired_count
-				@mutex.synchronize{@acquired_count}
+				@acquired_count_metric.value
 			end
 			
 			# @returns [Integer] Current count of available resources.
@@ -57,7 +61,7 @@ module Async
 			
 			# @returns [Integer] Current count of reacquiring tasks waiting for resources.
 			def reacquire_waiting_count
-				@mutex.synchronize{@reacquire_waiting_count}
+				@reacquire_waiting_count_metric.value
 			end
 			
 			# Check if a new task can be acquired.
@@ -73,6 +77,8 @@ module Async
 				count.times do
 					@queue.push(value)
 				end
+				
+				update_utilization_metrics
 			end
 			
 			# Get current limiter statistics.
@@ -82,10 +88,10 @@ module Async
 					{
 						waiting: @queue.waiting_count,
 						available: @queue.size,
-						acquired_count: @acquired_count,
+						acquired_count: @acquired_count_metric.value,
 						available_count: @queue.size,
 						waiting_count: @queue.waiting_count,
-						reacquire_waiting_count: @reacquire_waiting_count,
+						reacquire_waiting_count: @reacquire_waiting_count_metric.value,
 						timing: @timing.statistics
 					}
 				end
@@ -95,25 +101,36 @@ module Async
 			
 			# Acquire a resource from the queue with optional deadline.
 			def acquire_resource(deadline, reacquire: false, **options)
-				@reacquire_waiting_count += 1 if reacquire
+				@reacquire_waiting_count_metric.increment if reacquire
+				update_utilization_metrics if reacquire
 				
 				@mutex.unlock
 				resource = @queue.pop(timeout: deadline&.remaining, **options)
 				return resource
 			ensure
 				@mutex.lock
-				@reacquire_waiting_count -= 1 if reacquire
-				@acquired_count += 1 if resource
+				@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 -= 1 if @acquired_count > 0
+					@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/version.rb

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

data/readme.md

@@ -24,6 +24,10 @@ Please see the [project documentation](https://socketry.github.io/async-limiter/
 
 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.

data/releases.md

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-limiter
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Bruno Sutic
@@ -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: []