async-limiter 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b6e7e0d162f4068ced173efa8f365f53e809bf36b80fb41c21988865ea558b
-  data.tar.gz: d6ed3ed9482da942bf2fdec9403d2c842174eaa090cf0ea61036cf839c731d9c
+  metadata.gz: 20ea7fcd7cb0c04777113d99878872f59f2275d7df572555eb23e5176173103a
+  data.tar.gz: 65bd9ebbc338f9cb786adb711f01085b8e3fdade9ed5d8a5614a3710023a5863
 SHA512:
-  metadata.gz: 496cd5748700aa4c7eb897fc2c47720ea10c7650ab2407e0d15394ce56d44c1d7bd82a31f4138b9437d1e0e474449defe2a5f190d2140f41bc44afafa68bfe8b
-  data.tar.gz: 8733a7138915188e423fee9f9b4213cc087d93b86f69a43e3ac7954272e94eb15ef99e2ea100ccfd621aebc6d4f292267c298d609f559448f92e45c7c8ffb0dd
+  metadata.gz: dbd5950c897046843d3cd9da278843aab29a46d5a4e6f2915dc971596353e97edeec4da100553f243eb31661243a51a05fbc3232758521fdf8840ddcddd7fd58
+  data.tar.gz: 4e1a47617c6239470ba15351d22f310d082062358159e7c9595f42a160ea87a694f9cd52a25daaaa19a6d42983c0869dd5580e31f97a7dcd3603de4e056d84cf

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,17 +25,25 @@ 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
 			
+			# @attribute [Timing] Strategy for timing constraints.        
+			attr :timing
+			
 			# @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 +76,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/token.rb

@@ -14,7 +14,8 @@ module Async
 		# re-acquisition with modified parameters while maintaining the original context.
 		#
 		# The token automatically tracks release state using the resource itself as the
-		# state indicator (nil = released, non-nil = acquired).
+		# state indicator (nil = released, non-nil = acquired). A closed token also
+		# clears its limiter reference, which prevents future re-acquisition.
 		class Token
 			# Acquire a token from a limiter.
 			#
@@ -61,6 +62,12 @@ module Async
 				end
 			end
 			
+			# Close the token and prevent future re-acquisition.
+			def close
+				self.release
+				@limiter = nil
+			end
+			
 			# Re-acquire the resource with modified options.
 			#
 			# This allows changing acquisition parameters (timeout, cost, priority, etc.)
@@ -74,6 +81,7 @@ module Async
 			# @asynchronous
 			def acquire(**options, &block)
 				raise "Token already acquired!" if @resource
+				return nil unless @limiter
 				
 				@resource = @limiter.acquire(reacquire: true, **options)
 				
@@ -97,6 +105,12 @@ module Async
 			def released?
 				!@resource
 			end
+			
+			# Check if the token has been closed.
+			# @returns [Boolean] True if the token has been closed.
+			def closed?
+				!@limiter
+			end
 		end
 	end
 end

data/lib/async/limiter/version.rb

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

data/readme.md

@@ -24,6 +24,15 @@ 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.3.0
+
+  - Add `Async::Limiter::Token#close` to release and permanently invalidate a token.
+  - Expose `Async::Limiter::Generic#timing`.
+
+### 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,14 @@
 # Releases
 
+## v2.3.0
+
+  - Add `Async::Limiter::Token#close` to release and permanently invalidate a token.
+  - Expose `Async::Limiter::Generic#timing`.
+
+## 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.tar.gz.sig

@@ -1,5 +1 @@
-d���U��=���>jZ"�8UM1j_#���	�s2)����l��ٱ1�4�$ob@�/��6cf;"�Q�}fDhvת�^gn[\W�_m�к̔EM�޾��i�
-���A�V3�\�|�v����w]1�u�'���U��;x�6�b���
-��St�B74,�>�����NaZC�pmC���ȴHN�/cG"�'��e�*
-t��m�L2��	��#��/q��!@E��EYg]
-;L`�E�)�J��{�5����tD�J��ҍ�q��m�o���=:&#ݗ��M��x��>{�d���˅e�uh�. ��~(�d�1-R�hM:;�{- e�ȭ�c�QX��q���G�
+_��rG��1K���S~��n�w7`I)Q����6Z

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-limiter
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.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: []
@@ -86,7 +100,7 @@ files:
 - license.md
 - readme.md
 - releases.md
-homepage: https://github.com/bruno-/async-limiter
+homepage: https://github.com/socketry/async-limiter
 licenses:
 - MIT
 metadata:
@@ -106,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Execution rate limiting for Async
 test_files: []