async-limiter 1.5.4 → 2.1.0

data/context/token-usage.md

@@ -0,0 +1,85 @@
+# Token Usage
+
+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.
+
+## What Are Tokens?
+
+Tokens encapsulate acquired resources and provide advanced resource management capabilities:
+
+- **Re-acquisition**: Re-acquire resources after release with new options.
+- **Resource tracking**: Know whether a token is active or released.
+- **Automatic cleanup**: Guaranteed resource release with block usage
+
+## Usage
+
+Use `Token.acquire` instead of limiter-specific methods:
+
+```ruby
+require "async"
+require "async/limiter"
+
+limiter = Async::Limiter::Limited.new(5)
+
+# Acquire a token:
+token = Async::Limiter::Token.acquire(limiter)
+puts "Acquired: #{token.resource}"
+
+# Use the resource
+perform_operation(token.resource)
+
+# Release when done:
+token.release
+```
+
+For most limiters, `token.resource` will simply be the value `true`.
+
+### Block-Based Token Usage
+
+For automatic cleanup, use blocks:
+
+```ruby
+# Automatic release with blocks:
+Async::Limiter::Token.acquire(limiter) do |token|
+	puts "Using: #{token.resource}"
+	perform_operation(token.resource)
+	# Automatically released when block exits.
+end
+```
+
+## Re-Acquisition
+
+Tokens can be released and re-acquired:
+
+```ruby
+# Initial acquisition:
+token = Async::Limiter::Token.acquire(limiter)
+
+# Use and release:
+perform_operation(token.resource)
+token.release
+
+# Re-acquire later with new options:
+token.acquire(priority: 5, cost: 2.0)
+puts "Re-acquired: #{token.resource}"
+
+token.release
+```
+
+If you specify a timeout, and the limiter cannot be acquired, `nil` will be returned.
+
+### Re-Acquisition with Blocks
+
+```ruby
+token = Async::Limiter::Token.acquire(limiter)
+
+# Use the resource:
+perform_operation(token.resource)
+token.release
+
+# Re-acquire and execute with automatic cleanup:
+result = token.acquire(cost: 2.0) do |resource|
+	perform_expensive_operation(resource)
+end
+
+puts "Operation result: #{result}"
+```

data/lib/async/limiter/generic.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# 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"
+
+module Async
+	module Limiter
+		# Generic limiter class with unlimited concurrency by default.
+		#
+		# This provides the foundation for rate limiting and concurrency control.
+		# Subclasses can override methods to implement specific limiting behaviors.
+		#
+		# The Generic limiter coordinates timing strategies with concurrency control,
+		# providing thread-safe acquisition with deadline tracking and cost-based consumption.
+		class Generic
+			# 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)
+				@timing = timing
+				@parent = parent
+				@tags = tags
+				
+				@mutex = Mutex.new
+			end
+			
+			# @attribute [Array(String)] Tags associated with this limiter for identification or categorization.
+			attr :tags
+			
+			# @returns [Boolean] Whether this limiter is currently limiting concurrency.
+			def limited?
+				false
+			end
+			
+			# Execute a task asynchronously with unlimited concurrency.
+			# @parameter parent [Async::Task] Parent task for the new task.
+			# @parameter options [Hash] Additional options passed to {Async::Task#async}.
+			# @yields {|task| ...} The block to execute within the limiter constraints.
+			#   @parameter task [Async::Task] The async task context.
+			# @returns [Async::Task] The created task.
+			# @asynchronous
+			def async(parent: (@parent || Task.current), **options)
+				acquire
+				parent.async(**options) do |task|
+					yield task
+				ensure
+					release
+				end
+			end
+			
+			# Execute a task synchronously with unlimited concurrency.
+			# @yields {|task| ...} The block to execute within the limiter constraints.
+			#   @parameter task [Async::Task] The current task context.
+			# @asynchronous
+			def sync
+				acquire do
+					yield(Task.current)
+				end
+			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
+			# - Deadline tracking to prevent timeout violations
+			# - Automatic resource cleanup with block usage
+			#
+			# @parameter timeout [Numeric, nil] Timeout in seconds (nil = wait forever, 0 = non-blocking).
+			# @parameter cost [Numeric] The cost/weight of this operation for timing strategies (default: 1).
+			# @parameter options [Hash] Additional options passed to concurrency acquisition.
+			# @yields {|resource| ...} Optional block executed with automatic resource release.
+			#   @parameter resource [Object] The acquired resource.
+			# @returns [Object, nil] The acquired resource, or nil if acquisition failed/timed out.
+			#   When used with a block, returns the result of the block execution.
+			# @raises [ArgumentError] If cost exceeds the timing strategy's maximum supported cost.
+			# @asynchronous
+			def acquire(timeout: nil, cost: 1, **options)
+				# Validate cost against timing strategy capacity:
+				maximum_cost = @timing.maximum_cost
+				if cost > maximum_cost
+					raise ArgumentError, "Cost #{cost} exceeds maximum supported cost #{maximum_cost} for timing strategy!"
+				end
+				
+				resource = nil
+				deadline = Deadline.start(timeout)
+				
+				# Atomically handle timing constraints and concurrency logic:
+				acquire_synchronized(timeout, cost, **options) do
+					# Wait for timing constraints to be satisfied (mutex released during sleep)
+					return nil unless @timing.wait(@mutex, deadline, cost)
+					
+					# Execute the concurrency-specific acquisition logic
+					resource = acquire_resource(deadline, **options)
+					
+					# Record timing acquisition if successful
+					if resource
+						@timing.acquire(cost)
+					else
+						# `acquire_concurrency` should return nil if deadline reached:
+						return nil
+					end
+					
+					resource
+				end
+				
+				return resource unless block_given?
+				
+				begin
+					yield(resource)
+				ensure
+					release(resource)
+				end
+			end
+			
+			# Release a previously acquired resource.
+			def release(resource = true)
+				release_resource(resource)
+			end
+			
+			# Get current limiter statistics.
+			# @returns [Hash] Statistics hash with current state.
+			def statistics
+				@mutex.synchronize do
+					{
+						timing: @timing.statistics
+					}
+				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)
+				@mutex.synchronize do
+					yield
+				end
+			end
+			
+			# Default resource acquisition for unlimited semaphore.
+			# Subclasses should override this method.
+			def acquire_resource(deadline, **options)
+				# Default unlimited behavior - always succeeds
+				true
+			end
+			
+			# Default resource release for unlimited semaphore.
+			# Subclasses should override this method.
+			def release_resource(resource)
+				# Default implementation - subclasses should override.
+			end
+		end
+	end
+end

data/lib/async/limiter/limited.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2020, by Bruno Sutic.
+# Copyright, 2025-2026, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "generic"
+
+module Async
+	module Limiter
+		# Limited concurrency limiter that enforces a strict task limit.
+		#
+		# This implements a counting semaphore that limits the number of concurrent
+		# operations. It coordinates with timing strategies to provide both concurrency
+		# and rate limiting.
+		#
+		# The Limited limiter uses a mutex and condition variable for thread-safe
+		# coordination, with support for deadline-aware timeout handling.
+		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.
+			# @raises [ArgumentError] If limit is not positive.
+			def initialize(limit = 1, timing: Timing::None, parent: nil)
+				super(timing: timing, parent: parent)
+				
+				@limit = limit
+				@count = 0
+				@waiting_count = 0
+				@reacquire_waiting_count = 0
+				
+				@available = ConditionVariable.new
+			end
+			
+			# @attribute [Integer] The maximum number of concurrent tasks.
+			attr_reader :limit
+			
+			# @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?
+				@mutex.synchronize{@count >= @limit}
+			end
+			
+			# Update the concurrency limit.
+			# @parameter new_limit [Integer] The new maximum number of concurrent tasks.
+			# @raises [ArgumentError] If new_limit is not positive.
+			def limit=(new_limit)
+				@mutex.synchronize do
+					old_limit = @limit
+					@limit = new_limit
+					
+					# Wake up waiting tasks if limit increased:
+					@available.broadcast if new_limit > old_limit
+				end
+			end
+			
+			# Get current limiter statistics.
+			# @returns [Hash] Statistics hash with current state.
+			def statistics
+				@mutex.synchronize do
+					{
+						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
+			end
+			
+			protected
+			
+			# Acquire resource with optional deadline.
+			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
+				end
+				
+				@count += 1
+				
+				return true
+			ensure
+				if waiting
+					@waiting_count -= 1
+					@reacquire_waiting_count -= 1 if reacquire
+				end
+			end
+			
+			# Release resource.
+			def release_resource(resource)
+				@mutex.synchronize do
+					@count -= 1
+					@available.signal
+				end
+			end
+		end
+	end
+end

data/lib/async/limiter/queued.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Francisco Mejia.
+# Copyright, 2025-2026, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "generic"
+require_relative "token"
+
+module Async
+	module Limiter
+		# Queue-based limiter that distributes pre-existing resources with priority/timeout support.
+		#
+		# This limiter manages a finite set of resources (connections, API keys, etc.)
+		# that are pre-populated in a queue. It provides priority-based allocation
+		# and timeout support for resource acquisition.
+		#
+		# Unlike Limited which counts abstract permits, Queued distributes actual
+		# resource objects and supports priority queues for fair allocation.
+		class Queued < Generic
+			# @returns [Queue] A default queue with a single true value.
+			def self.default_queue
+				Queue.new.tap do |queue|
+					queue.push(true)
+				end
+			end
+			
+			# 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)
+				@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?
+				@queue.empty?
+			end
+			
+			# Expand the queue with additional resources.
+			# @parameter count [Integer] Number of resources to add.
+			# @parameter value [Object] The value to add to the queue.
+			def expand(count, value = true)
+				count.times do
+					@queue.push(value)
+				end
+			end
+			
+			# Get current limiter statistics.
+			# @returns [Hash] Statistics hash with current state.
+			def statistics
+				@mutex.synchronize do
+					{
+						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
+			end
+			
+			protected
+			
+			# Acquire a resource from the queue with optional deadline.
+			def acquire_resource(deadline, reacquire: false, **options)
+				@reacquire_waiting_count += 1 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
+			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
+		end
+	end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module Limiter
+		module Timing
+			# Provides burst control strategies for timing limiters.
+			#
+			# Burst strategies are stateless modules that determine whether tasks can execute
+			# immediately or must wait for frame boundaries, controlling task distribution over time.
+			#
+			# ## Strategy Comparison
+			#
+			# Greedy vs Smooth behavior with 5 tasks per 60-second window:
+			#
+			#   Greedy Strategy (allows clustering):
+			#   |█████     |█████     |█████     |█████     |
+			#   0s         60s        120s       180s
+			#   All 5 tasks execute immediately when window opens
+			#   
+			#   Smooth Strategy (enforces even distribution):
+			#   |█ █ █ █ █ |█ █ █ █ █ |█ █ █ █ █ |█ █ █ █ █ |
+			#   0s         60s        120s       180s
+			#   Tasks spread evenly: 0s, 12s, 24s, 36s, 48s
+			#
+			module Burst
+				# Allows tasks to cluster within windows for high-throughput scenarios.
+				#
+				# Greedy strategies permit multiple tasks to start immediately as long as
+				# the window limit hasn't been exceeded. This creates "bursts" of activity
+				# at window boundaries, maximizing throughput when resources become available.
+				#
+				# ## Greedy Behavior
+				#
+				# Greedy behavior with 3 tasks per 10-second window:
+				#
+				#   Window 1: [Task1, Task2, Task3] at 0s -------- (all immediate)
+				#   Window 2: [Task4, Task5, Task6] at 10s ------- (all immediate)
+				#
+				# Perfect for: Batch processing, high-throughput scenarios
+				module Greedy
+					# Check if a task can be acquired in burstable mode.
+					# @parameter window_count [Integer] Number of tasks started in current window.
+					# @parameter limit [Integer] Maximum tasks allowed in the window.
+					# @parameter frame_changed [Boolean] Ignored in burstable mode.
+					# @returns [Boolean] True if under the window limit.
+					def self.can_acquire?(window_count, limit, frame_changed)
+						window_count < limit
+					end
+					
+					# Calculate the next time a task can be acquired.
+					# @parameter window_start_time [Numeric] When the current window started.
+					# @parameter window_duration [Numeric] Duration of the window.
+					# @parameter frame_start_time [Numeric] Ignored in burstable mode.
+					# @parameter frame_duration [Numeric] Ignored in burstable mode.
+					# @returns [Numeric] The next window start time.
+					def self.next_acquire_time(window_start_time, window_duration, frame_start_time, frame_duration)
+						window_start_time + window_duration
+					end
+					
+					# Check if window constraints are blocking new tasks.
+					# @parameter window_count [Integer] Number of tasks started in current window.
+					# @parameter limit [Integer] Maximum tasks allowed in the window.
+					# @parameter window_changed [Boolean] Whether the window has reset.
+					# @returns [Boolean] True if window is blocking new tasks.
+					def self.window_blocking?(window_count, limit, window_changed)
+						return false if window_changed
+						window_count >= limit
+					end
+					
+					# Check if frame constraints are blocking new tasks.
+					# @parameter frame_changed [Boolean] Whether the frame boundary has been crossed.
+					# @returns [Boolean] Always false for burstable mode.
+					def self.frame_blocking?(frame_changed)
+						false  # Burstable mode doesn't use frame blocking
+					end
+					
+					# Get current burst strategy statistics.
+					# @returns [Hash] Statistics hash with current state.
+					def self.statistics
+						{
+							name: "Greedy",
+						}
+					end
+				end
+				
+				# Enforces even task distribution to prevent clustering.
+				#
+				# Smooth strategies prevent clustering by requiring tasks to wait for
+				# frame boundaries, ensuring smooth and predictable task execution timing.
+				# This creates consistent load patterns and prevents resource spikes.
+				#
+				# ## Smooth Behavior
+				#
+				# Smooth behavior with 3 tasks per 15-second window:
+				#
+				#   Window 1: [Task1] -- [Task2] -- [Task3] ---- (evenly spaced)
+				#             0s      5s      10s     15s
+				#   Window 2: [Task4] -- [Task5] -- [Task6] ---- (evenly spaced)
+				#             15s     20s     25s     30s
+				#
+				# Perfect for: API rate limiting, smooth resource usage
+				module Smooth
+					# Check if a task can be acquired in continuous mode.
+					# @parameter window_count [Integer] Ignored in continuous mode.
+					# @parameter limit [Integer] Ignored in continuous mode.
+					# @parameter frame_changed [Boolean] Whether the frame boundary has been crossed.
+					# @returns [Boolean] True only if the frame boundary has been crossed.
+					def self.can_acquire?(window_count, limit, frame_changed)
+						frame_changed
+					end
+					
+					# Calculate the next time a task can be acquired.
+					# @parameter window_start_time [Numeric] Ignored in continuous mode.
+					# @parameter window_duration [Numeric] Ignored in continuous mode.
+					# @parameter frame_start_time [Numeric] When the current frame started.
+					# @parameter frame_duration [Numeric] Duration of each frame.
+					# @returns [Numeric] The next frame start time.
+					def self.next_acquire_time(window_start_time, window_duration, frame_start_time, frame_duration)
+						frame_start_time + frame_duration
+					end
+					
+					# Check if window constraints are blocking new tasks.
+					# @parameter window_count [Integer] Ignored in continuous mode.
+					# @parameter limit [Integer] Ignored in continuous mode.
+					# @parameter window_changed [Boolean] Ignored in continuous mode.
+					# @returns [Boolean] Always false for continuous mode.
+					def self.window_blocking?(window_count, limit, window_changed)
+						false  # Continuous mode doesn't use window blocking
+					end
+					
+					# Check if frame constraints are blocking new tasks.
+					# @parameter frame_changed [Boolean] Whether the frame boundary has been crossed.
+					# @returns [Boolean] True if frame hasn't changed (blocking until next frame).
+					def self.frame_blocking?(frame_changed)
+						!frame_changed
+					end
+					
+					# Get current burst strategy statistics.
+					# @returns [Hash] Statistics hash with current state.
+					def self.statistics
+						{
+							name: "Smooth",
+						}
+					end
+				end
+			end
+		end
+	end
+end