async-limiter 1.5.3 → 2.0.0

data/license.md

@@ -0,0 +1,25 @@
+# MIT License
+
+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.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,45 @@
+# Async Limiter
+
+A Ruby gem providing flexible concurrency and rate limiting for async applications.
+
+[![Development Status](https://github.com/socketry/async-limiter/workflows/Test/badge.svg)](https://github.com/socketry/async-limiter/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-limiter/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-limiter/guides/getting-started/index) - This guide explains how to get started the `async-limiter` gem for controlling concurrency and rate limiting in Ruby applications.
+
+  - [Generic Limiter](https://socketry.github.io/async-limiter/guides/generic-limiter/index) - This guide explains the <code class="language-ruby">Async::Limiter::Generic</code> class, which provides unlimited concurrency by default and serves as the base implementation for all other limiters. It's ideal when you need timing constraints without concurrency limits, or when building custom limiter implementations.
+
+  - [Limited Limiter](https://socketry.github.io/async-limiter/guides/limited-limiter/index) - This guide explains the <code class="language-ruby">Async::Limiter::Limited</code> class, which provides semaphore-style concurrency control, enforcing a maximum number of concurrent operations. It's perfect for controlling concurrency when you have limited capacity or want to prevent system overload.
+
+  - [Queued Limiter](https://socketry.github.io/async-limiter/guides/queued-limiter/index) - This guide explains the <code class="language-ruby">Async::Limiter::Queued</code> class, which provides priority-based task scheduling with optional resource management. Its key feature is priority-based acquisition where higher priority tasks get access first, with optional support for distributing specific resources from a pre-populated queue.
+
+  - [Timing Strategies](https://socketry.github.io/async-limiter/guides/timing-strategies/index) - This guide explains how to use timing strategies to provide rate limiting and timing constraints that can be combined with any limiter. They control *when* operations can execute, while limiters control *how many* can execute concurrently.
+
+  - [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.
+
+## See Also
+
+  - [falcon](https://github.com/socketry/falcon) - A high-performance web server
+  - [async-http](https://github.com/socketry/async-http) - Asynchronous HTTP client and server
+  - [async](https://github.com/socketry/async) - The core async framework
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### 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.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,50 @@
+# Releases
+
+## 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)
+
+  - **New**: `Async::Limiter::Generic` - Unlimited concurrency with timing coordination (replaces `Async::Limiter::Unlimited`).
+  - **New**: `Async::Limiter::Limited` - Counting semaphore with configurable limits (replaces `Async::Limiter::Concurrent`).
+  - **New**: `Async::Limiter::Queued` - Queue-based resource distribution with priority/timeout support (completely new functionality).
+
+### Advanced Timeout Features
+
+  - **New**: Unified timeout API - `acquire(timeout: 0/nil/seconds)` provides non-blocking and timed acquisition.
+  - **New**: Precise deadline tracking using `Async::Deadline` (requires async v2.31.0+).
+  - **New**: Convoy effect prevention - quick timeout operations not blocked by slow operations.
+  - **New**: Accurate timeout propagation - remaining time correctly passed through timing and concurrency layers.
+
+### Cost-Based Acquisition
+
+  - **New**: Cost-based acquisition - `acquire(cost: 1.5)` for proportional resource consumption.
+  - **New**: Starvation prevention - validates cost against timing strategy `maximum_cost` capacity.
+  - **New**: Flexible operation weighting - light operations consume fewer resources than heavy ones.
+
+### Enhanced Timing Strategies
+
+  - Add `Async::Limiter::Timing::LeakyBucket` for token bucket rate limiting with automatic leaking.
+  - Add `Async::Limiter::Timing::FixedWindow` for discrete time boundary enforcement.
+  - Rename `Async::Limiter::Timing::Window` to `Async::Limiter::Timing::SlidingWindow` for clarity.
+  - **Breaking**: Remove `release` methods from timing strategies (consumption-only model).
+  - **Breaking**: Remove `try_acquire` methods from timing strategies (unified timeout API).
+
+### Token-Based Resource Management
+
+  - **New**: `acquire_token` method returns `Token` objects for advanced resource management.
+  - **New**: Token re-acquisition with different options - `token.acquire(priority: 5)`.
+  - **New**: Automatic token cleanup with block usage.
+
+### Thread Safety and Performance
+
+  - **New**: Race condition elimination by moving timing coordination inside mutex.
+  - **New**: Fast path optimizations using `deadline.expired?` checks.
+  - **New**: Atomic timing coordination prevents race conditions in concurrent access.
+  - **Improved**: Test performance using time simulation instead of actual sleep calls.

metadata

@@ -1,105 +1,97 @@
 --- !ruby/object:Gem::Specification
 name: async-limiter
 version: !ruby/object:Gem::Version
-  version: 1.5.3
+  version: 2.0.0
 platform: ruby
 authors:
 - Bruno Sutic
-autorequire:
+- Shopify Inc.
+- Samuel Williams
+- Francisco Mejia
+- William
 bindir: bin
-cert_chain: []
-date: 2021-01-10 00:00:00.000000000 Z
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.27'
+        version: '2.31'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.27'
-- !ruby/object:Gem::Dependency
-  name: async-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.15'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.10'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: standard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-description:
-email: code@brunosutic.com
+        version: '2.31'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- context/generic-limiter.md
+- context/getting-started.md
+- context/index.yaml
+- context/limited-limiter.md
+- context/queued-limiter.md
+- context/timing-strategies.md
+- context/token-usage.md
 - lib/async/limiter.rb
-- lib/async/limiter/concurrent.rb
-- lib/async/limiter/constants.rb
-- lib/async/limiter/unlimited.rb
+- lib/async/limiter/generic.rb
+- lib/async/limiter/limited.rb
+- lib/async/limiter/queued.rb
+- lib/async/limiter/timing/burst.rb
+- lib/async/limiter/timing/fixed_window.rb
+- lib/async/limiter/timing/leaky_bucket.rb
+- lib/async/limiter/timing/none.rb
+- lib/async/limiter/timing/ordered.rb
+- lib/async/limiter/timing/sliding_window.rb
+- lib/async/limiter/token.rb
 - lib/async/limiter/version.rb
-- lib/async/limiter/window.rb
-- lib/async/limiter/window/continuous.rb
-- lib/async/limiter/window/fixed.rb
-- lib/async/limiter/window/sliding.rb
+- lib/metrics/provider/async/limiter.rb
+- lib/metrics/provider/async/limiter/generic.rb
+- lib/traces/provider/async/limiter.rb
+- lib/traces/provider/async/limiter/generic.rb
+- license.md
+- readme.md
+- releases.md
 homepage: https://github.com/bruno-/async-limiter
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  documentation_uri: https://socketry.github.io/async-limiter/
+  source_code_uri: https://github.com/socketry/async-limiter.git
 rdoc_options: []
 require_paths:
 - lib
@@ -107,15 +99,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Async limiters
+summary: Execution rate limiting for Async
 test_files: []

data/lib/async/limiter/concurrent.rb

@@ -1,101 +0,0 @@
-require "async/task"
-require_relative "constants"
-
-module Async
-  module Limiter
-    class Concurrent
-      attr_reader :count
-
-      attr_reader :limit
-
-      def initialize(limit = 1, parent: nil, queue: [])
-        @count = 0
-        @limit = limit
-        @waiting = queue
-        @parent = parent
-
-        validate!
-      end
-
-      def blocking?
-        limit_blocking?
-      end
-
-      def async(*queue_args, parent: (@parent || Task.current), **options)
-        acquire(*queue_args)
-        parent.async(**options) do |task|
-          yield task
-        ensure
-          release
-        end
-      end
-
-      def sync(*queue_args)
-        acquire(*queue_args) do
-          yield(@parent || Task.current)
-        end
-      end
-
-      def acquire(*queue_args)
-        wait(*queue_args)
-        @count += 1
-
-        return unless block_given?
-
-        begin
-          yield
-        ensure
-          release
-        end
-      end
-
-      def release
-        @count -= 1
-
-        resume_waiting
-      end
-
-      def limit=(new_limit)
-        validate_limit!(new_limit)
-
-        @limit = new_limit
-      end
-
-      private
-
-      def limit_blocking?
-        @count >= @limit
-      end
-
-      def wait(*queue_args)
-        fiber = Fiber.current
-
-        if blocking?
-          @waiting.push(fiber, *queue_args) # queue_args used for custom queues
-          Task.yield while blocking?
-        end
-      rescue Exception # rubocop:disable Lint/RescueException
-        @waiting.delete(fiber)
-        raise
-      end
-
-      def resume_waiting
-        while !blocking? && (fiber = @waiting.shift)
-          fiber.resume if fiber.alive?
-        end
-      end
-
-      def validate!
-        if @limit.finite? && (@limit % 1).nonzero?
-          raise ArgumentError, "limit must be a whole number"
-        end
-
-        validate_limit!
-      end
-
-      def validate_limit!(value = @limit)
-        raise ArgumentError, "limit must be greater than 1" if value < 1
-      end
-    end
-  end
-end

data/lib/async/limiter/constants.rb

@@ -1,6 +0,0 @@
-module Async
-  module Limiter
-    Error = Class.new(StandardError)
-    ArgumentError = Class.new(Error)
-  end
-end

data/lib/async/limiter/unlimited.rb

@@ -1,53 +0,0 @@
-require "async/task"
-
-module Async
-  module Limiter
-    class Unlimited
-      attr_reader :count
-
-      def initialize(parent: nil)
-        @count = 0
-        @parent = parent
-      end
-
-      def limit
-        Float::INFINITY
-      end
-
-      def blocking?
-        false
-      end
-
-      def async(parent: (@parent || Task.current), **options)
-        acquire
-        parent.async(**options) do |task|
-          yield task
-        ensure
-          release
-        end
-      end
-
-      def sync(*queue_args)
-        acquire(*queue_args) do
-          yield(@parent || Task.current)
-        end
-      end
-
-      def acquire
-        @count += 1
-
-        return unless block_given?
-
-        begin
-          yield
-        ensure
-          release
-        end
-      end
-
-      def release
-        @count -= 1
-      end
-    end
-  end
-end

data/lib/async/limiter/window/continuous.rb

@@ -1,21 +0,0 @@
-require_relative "../window"
-
-module Async
-  module Limiter
-    class Window
-      class Continuous < Window
-        def initialize(limit = 1, window: 1, parent: nil, lock: true, queue: [])
-          super(
-            limit,
-            type: :sliding, # type doesn't matter, but sliding is less work
-            burstable: false,
-            window: window,
-            parent: parent,
-            lock: lock,
-            queue: queue
-          )
-        end
-      end
-    end
-  end
-end

data/lib/async/limiter/window/fixed.rb

@@ -1,21 +0,0 @@
-require_relative "../window"
-
-module Async
-  module Limiter
-    class Window
-      class Fixed < Window
-        def initialize(limit = 1, window: 1, parent: nil, lock: true, queue: [])
-          super(
-            limit,
-            type: :fixed,
-            burstable: true,
-            window: window,
-            parent: parent,
-            lock: lock,
-            queue: queue
-          )
-        end
-      end
-    end
-  end
-end

data/lib/async/limiter/window/sliding.rb

@@ -1,21 +0,0 @@
-require_relative "../window"
-
-module Async
-  module Limiter
-    class Window
-      class Sliding < Window
-        def initialize(limit = 1, window: 1, parent: nil, lock: true, queue: [])
-          super(
-            limit,
-            type: :sliding,
-            burstable: true,
-            window: window,
-            parent: parent,
-            lock: lock,
-            queue: queue
-          )
-        end
-      end
-    end
-  end
-end