async-limiter 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1e4bf6b1b1477475fc5bf247364592ebd062e86cd5039614a9963cfdc9e23ab
-  data.tar.gz: 82f5fc81a61d6d8cc0400d86b4a84977379f3edc8f6951bba738e2215e1e3445
+  metadata.gz: 6d203b60d1b006ce7dc199fd37dbfeac43468324a083a02a233dbf7fe1ebc61f
+  data.tar.gz: f7cd17453e047205743648458058f30365d795514fba956dca1aa910ab34816e
 SHA512:
-  metadata.gz: 8c2698448ec6846405dc647c0e11b37616fbd80027b92a03e28a849d511164835909d4982ddbe6cfff7e963b00bedc6699dd90dbc33067f52969480170bc1c4a
-  data.tar.gz: 62e777daf244f5cfe6b9ef89cdcdd8b07791808324713db58a7242825cf9d3d82f4978c920639bbc603dae625fbe819a41fdb7b95897d3f619d8d80eb9195794
+  metadata.gz: 2721ba28df1d8aca742ba974ace3146d136734e9482c39429957dd0ff9022843eef5dc6bdbda9c9aa60017c019ab2011907a31a6d30d8a16f7392b2c70daf04a
+  data.tar.gz: 7ea2cbb70d1f192d947d42594711fdf37da8f86a56d624925ec3b8fdb31957248ecbb1b945f62f7c4dfc755c947ede0ec65f8035c2806fd942ebd60ab430194d

data/lib/async/limiter.rb

@@ -1,114 +1,10 @@
-require "async/task"
+require_relative "limiter/concurrent"
+require_relative "limiter/unlimited"
+require_relative "limiter/window/continuous"
+require_relative "limiter/window/fixed"
+require_relative "limiter/window/sliding"
 
 module Async
-  # Base class for all the limiters.
-  class Limiter
-    Error = Class.new(StandardError)
-    ArgumentError = Class.new(Error)
-
-    MAX_LIMIT = Float::INFINITY
-    MIN_LIMIT = Float::MIN
-
-    attr_reader :count
-
-    attr_reader :limit
-
-    attr_reader :waiting
-
-    def initialize(limit = 1, parent: nil,
-      max_limit: MAX_LIMIT, min_limit: MIN_LIMIT)
-      @count = 0
-      @limit = limit
-      @waiting = []
-      @parent = parent
-      @max_limit = max_limit
-      @min_limit = min_limit
-
-      validate!
-    end
-
-    def blocking?
-      @count >= @limit
-    end
-
-    def async(parent: (@parent or Task.current), **options)
-      acquire
-      parent.async(**options) do |task|
-        yield task
-      ensure
-        release
-      end
-    end
-
-    def acquire
-      wait
-      @count += 1
-    end
-
-    def release
-      @count -= 1
-
-      while under_limit? && (fiber = @waiting.shift)
-        fiber.resume if fiber.alive?
-      end
-    end
-
-    def increase_limit(number = 1)
-      new_limit = @limit + number
-      return false if new_limit > @max_limit
-
-      @limit = new_limit
-    end
-
-    def decrease_limit(number = 1)
-      new_limit = @limit - number
-      return false if new_limit < @min_limit
-
-      @limit = new_limit
-    end
-
-    def waiting_count
-      @waiting.size
-    end
-
-    private
-
-    def under_limit?
-      available_units.positive?
-    end
-
-    def available_units
-      @limit - @count
-    end
-
-    def wait
-      fiber = Fiber.current
-
-      if blocking?
-        @waiting << fiber
-        Task.yield while blocking?
-      end
-    rescue Exception
-      @waiting.delete(fiber)
-      raise
-    end
-
-    def validate!
-      if @max_limit < @min_limit
-        raise ArgumentError, "max_limit is lower than min_limit"
-      end
-
-      unless @max_limit.positive?
-        raise ArgumentError, "max_limit must be positive"
-      end
-
-      unless @min_limit.positive?
-        raise ArgumentError, "min_limit must be positive"
-      end
-
-      unless @limit.between?(@min_limit, @max_limit)
-        raise ArgumentError, "limit not between min_limit and max_limit"
-      end
-    end
+  module Limiter
   end
 end

data/lib/async/limiter/concurrent.rb

@@ -1,10 +1,87 @@
-require_relative "../limiter"
+require "async/task"
+require_relative "constants"
 
 module Async
-  class Limiter
-    # Allows running x units of work concurrently.
-    # Has the same logic as Async::Semaphore.
-    class Concurrent < Limiter
+  module Limiter
+    class Concurrent
+      attr_reader :count
+
+      attr_reader :limit
+
+      def initialize(limit = 1, parent: nil)
+        @count = 0
+        @limit = limit
+        @waiting = []
+        @parent = parent
+
+        validate!
+      end
+
+      def blocking?
+        limit_blocking?
+      end
+
+      def async(parent: (@parent || Task.current), **options)
+        acquire
+        parent.async(**options) do |task|
+          yield task
+        ensure
+          release
+        end
+      end
+
+      def acquire
+        wait
+        @count += 1
+      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
+        fiber = Fiber.current
+
+        if blocking?
+          @waiting << fiber
+          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

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

data/lib/async/limiter/unlimited.rb

@@ -0,0 +1,39 @@
+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 acquire
+        @count += 1
+      end
+
+      def release
+        @count -= 1
+      end
+    end
+  end
+end

data/lib/async/limiter/version.rb

@@ -1,5 +1,5 @@
 module Async
-  class Limiter
-    VERSION = "0.0.1"
+  module Limiter
+    VERSION = "1.0.0"
   end
 end

data/lib/async/limiter/window.rb

@@ -0,0 +1,263 @@
+require "async/clock"
+require "async/task"
+require_relative "constants"
+
+module Async
+  module Limiter
+    class Window
+      TYPES = %i[fixed sliding].freeze
+      NULL_TIME = -1
+
+      attr_reader :count
+
+      attr_reader :type
+
+      attr_reader :lock
+
+      def initialize(limit = 1, type: :fixed, window: 1, parent: nil,
+        burstable: true, lock: true)
+        @count = 0
+        @input_limit = @limit = limit
+        @type = type
+        @input_window = @window = window
+        @parent = parent
+        @burstable = burstable
+        @lock = lock
+
+        @waiting = []
+        @scheduler_task = nil
+
+        @window_frame_start_time = NULL_TIME
+        @window_start_time = NULL_TIME
+        @window_count = 0
+
+        update_concurrency
+        validate!
+      end
+
+      def limit
+        @input_limit
+      end
+
+      def window
+        @input_window
+      end
+
+      def blocking?
+        limit_blocking? || window_blocking? || window_frame_blocking?
+      end
+
+      def async(parent: (@parent || Task.current), **options)
+        acquire
+        parent.async(**options) do |task|
+          yield task
+        ensure
+          release
+        end
+      end
+
+      def acquire
+        wait
+        @count += 1
+
+        current_time = Clock.now
+
+        if window_changed?(current_time)
+          @window_start_time =
+            if @type == :sliding
+              current_time
+            elsif @type == :fixed
+              (current_time / @window).to_i * @window
+            else
+              raise "invalid type #{@type}"
+            end
+
+          @window_count = 1
+        else
+          @window_count += 1
+        end
+
+        @window_frame_start_time = current_time
+      end
+
+      def release
+        @count -= 1
+
+        # We're resuming waiting fibers when lock is released.
+        resume_waiting if @lock
+      end
+
+      def limit=(new_limit)
+        validate_limit!(new_limit)
+        @input_limit = @limit = new_limit
+
+        update_concurrency
+        resume_waiting
+        reschedule if reschedule?
+
+        limit
+      end
+
+      def window=(new_window)
+        validate_window!(new_window)
+        @input_window = @window = new_window
+
+        update_concurrency
+        resume_waiting
+        reschedule if reschedule?
+
+        window
+      end
+
+      private
+
+      def limit_blocking?
+        @lock && @count >= @limit
+      end
+
+      def window_blocking?
+        return false unless @burstable
+        return false if window_changed?
+
+        @window_count >= @limit
+      end
+
+      def window_frame_blocking?
+        return false if @burstable
+        return false if window_frame_changed?
+
+        true
+      end
+
+      def window_changed?(time = Clock.now)
+        @window_start_time + @window <= time
+      end
+
+      def window_frame_changed?
+        @window_frame_start_time + window_frame <= Clock.now
+      end
+
+      def wait
+        fiber = Fiber.current
+
+        # @waiting.any? check prevents fibers resumed via scheduler from
+        # slipping in operations before other waiting fibers get resumed.
+        if blocking? || @waiting.any?
+          @waiting << fiber
+          schedule if schedule?
+          loop do
+            Task.yield # run this line at least once
+            break unless blocking?
+          end
+        end
+      rescue Exception # rubocop:disable Lint/RescueException
+        @waiting.delete(fiber)
+        raise
+      end
+
+      def schedule?
+        @scheduler_task.nil? &&
+          @waiting.any? &&
+          !limit_blocking?
+      end
+
+      # Schedule resuming waiting tasks.
+      def schedule(parent: @parent || Task.current)
+        @scheduler_task ||=
+          parent.async { |task|
+            while @waiting.any? && !limit_blocking?
+              delay = [next_acquire_time - Async::Clock.now, 0].max
+              task.sleep(delay) if delay.positive?
+              resume_waiting
+            end
+
+            @scheduler_task = nil
+          }
+      end
+
+      def reschedule?
+        @scheduler_task &&
+          @waiting.any? &&
+          !limit_blocking?
+      end
+
+      def reschedule
+        @scheduler_task.stop
+        @scheduler_task = nil
+
+        schedule
+      end
+
+      def resume_waiting
+        while !blocking? && (fiber = @waiting.shift)
+          fiber.resume if fiber.alive?
+        end
+
+        # Long running non-burstable tasks may end while
+        # #window_frame_blocking?. Start a scheduler if one is not running.
+        schedule if schedule?
+      end
+
+      def next_acquire_time
+        if @burstable
+          @window_start_time + @window # next window start time
+        else
+          @window_frame_start_time + window_frame # next window frame start time
+        end
+      end
+
+      def window_frame
+        @window.to_f / @limit
+      end
+
+      # If limit is a decimal number (e.g. 0.5) it needs to be adjusted.
+      # Make @limit a whole number and adjust @window appropriately.
+      def update_concurrency
+        # reset @limit and @window
+        @limit = @input_limit
+        @window = @input_window
+
+        return if @input_limit.infinite?
+        return if (@input_limit % 1).zero?
+
+        # @input_limit is a decimal number
+        case @input_limit
+        when 0...1
+          @window = @input_window / @input_limit
+          @limit = 1
+        when (1..)
+          if @input_window >= 2
+            @window = @input_window * @input_limit.floor / @input_limit
+            @limit = @input_limit.floor
+          else
+            @window = @input_window * @input_limit.ceil / @input_limit
+            @limit = @input_limit.ceil
+          end
+        else
+          raise "invalid limit #{@input_limit}"
+        end
+      end
+
+      def validate!
+        unless TYPES.include?(@type)
+          raise ArgumentError, "invalid type #{@type.inspect}"
+        end
+
+        validate_limit!
+        validate_window!
+      end
+
+      def validate_limit!(value = @input_limit)
+        unless value.positive?
+          raise ArgumentError, "limit must be positive number"
+        end
+      end
+
+      def validate_window!(value = @input_window)
+        unless value.positive?
+          raise ArgumentError, "window must be positive number"
+        end
+      end
+    end
+  end
+end

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

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

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

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

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: async-limiter
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Bruno Sutic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-03 00:00:00.000000000 Z
+date: 2020-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -24,6 +24,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.26'
+- !ruby/object:Gem::Dependency
+  name: async-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.43'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.43'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -46,10 +88,13 @@ extra_rdoc_files: []
 files:
 - lib/async/limiter.rb
 - lib/async/limiter/concurrent.rb
-- lib/async/limiter/delay.rb
-- lib/async/limiter/fixed_window.rb
-- lib/async/limiter/sliding_window.rb
+- lib/async/limiter/constants.rb
+- lib/async/limiter/unlimited.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
 homepage: https://github.com/bruno-/async-limiter
 licenses:
 - MIT
@@ -69,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.0.rc.1
 signing_key:
 specification_version: 4
 summary: Async limiters

data/lib/async/limiter/delay.rb

@@ -1,47 +0,0 @@
-require "async/clock"
-require_relative "../limiter"
-
-module Async
-  class Limiter
-    # Ensures units are evenly acquired during the sliding time window.
-    # Example: If limit is 2 you can perform one operation every 500ms. First
-    # operation at 10:10:10.000, and then another one at 10:10:10.500.
-    class Throttle < Limiter
-      attr_reader :window
-
-      def initialize(*args, window: 1, min_limit: 0, **options)
-        super(*args, min_limit: min_limit, **options)
-
-        @window = window
-        @last_acquired_time = -1
-      end
-
-      def blocking?
-        super && current_delay.positive?
-      end
-
-      def acquire
-        super
-        @last_acquired_time = now
-      end
-
-      def delay
-        @window.to_f / @limit
-      end
-
-      private
-
-      def now
-        Clock.now
-      end
-
-      def current_delay
-        [delay - elapsed_time, 0].max
-      end
-
-      def elapsed_time
-        now - @last_acquired_time
-      end
-    end
-  end
-end

data/lib/async/limiter/fixed_window.rb

@@ -1,53 +0,0 @@
-require "async/clock"
-require_relative "../limiter"
-
-module Async
-  class Limiter
-    # Ensures units are acquired during the time window.
-    # Example: You can perform N operations at 10:10:10.999, and then can
-    # perform another N operations at 10:10:11.000.
-    class FixedWindow < Limiter
-      attr_reader :window
-
-      def initialize(*args, window: 1, **options)
-        super(*args, **options)
-
-        @window = window
-        @acquired_window_indexes = []
-      end
-
-      def blocking?
-        super && window_limited?
-      end
-
-      def acquire
-        super
-        @acquired_window_indexes.unshift(window_index)
-        # keep more entries in case a limit is increased
-        @acquired_window_indexes = @acquired_window_indexes.first(keep_limit)
-      end
-
-      private
-
-      def window_limited?
-        first_index_in_limit_scope == window_index
-      end
-
-      def first_index_in_limit_scope
-        @acquired_window_indexes.fetch(@limit - 1) { -1 }
-      end
-
-      def window_index
-        (now / @window).floor
-      end
-
-      def keep_limit
-        @max_limit.infinite? ? @limit * 10 : @max_limit
-      end
-
-      def now
-        Clock.now
-      end
-    end
-  end
-end

data/lib/async/limiter/sliding_window.rb

@@ -1,53 +0,0 @@
-require "async/clock"
-require_relative "../limiter"
-
-module Async
-  class Limiter
-    # Ensures units are acquired during the sliding time window.
-    # Example: You can perform N operations at 10:10:10.999 but can't perform
-    # another N operations until 10:10:11.999.
-    class SlidingWindow < Limiter
-      attr_reader :window
-
-      def initialize(*args, window: 1, min_limit: 0, **options)
-        super(*args, min_limit: min_limit, **options)
-
-        @window = window
-        @acquired_times = []
-      end
-
-      def blocking?
-        super && window_limited?
-      end
-
-      def acquire
-        super
-        @acquired_times.unshift(now)
-        # keep more entries in case a limit is increased
-        @acquired_times = @acquired_times.first(keep_limit)
-      end
-
-      private
-
-      def window_limited?
-        first_time_in_limit_scope >= window_start_time
-      end
-
-      def first_time_in_limit_scope
-        @acquired_times.fetch(@limit - 1) { -1 }
-      end
-
-      def window_start_time
-        now - @window
-      end
-
-      def keep_limit
-        @max_limit.infinite? ? @limit * 10 : @max_limit
-      end
-
-      def now
-        Clock.now
-      end
-    end
-  end
-end