Class AimdCapacityLimiterBuilder

java.lang.Object
io.servicetalk.capacity.limiter.api.AimdCapacityLimiterBuilder

public final class AimdCapacityLimiterBuilder extends Object
Builder for the AimdCapacityLimiter capacity limiter.
  • Method Details

    • name

      public AimdCapacityLimiterBuilder name(String name)
      Defines a name for this CapacityLimiter.
      Parameters:
      name - the name to be used when building this CapacityLimiter.
      Returns:
      this.
    • limits

      public AimdCapacityLimiterBuilder limits(int initial, int min, int max)
      Define min and max concurrency limits for this CapacityLimiter. The active concurrency will fluctuate between these limits starting from the min and never going beyond max. AIMD will keep incrementing the limit by 1 everytime a successful response is received, and will decrement by the onDrop limits(int, int, int) ratio, for every dropped request (i.e. rejected or timeout).

      The limit translates to a concurrency figure, eg. how many requests can be in-flight simultaneously and doesn't represent a constant rate (i.e. has no notion of time).*

      The lower the min is, the slower the ramp up will be, and the bigger it is the more aggressive the service will be, keep concurrently issuing min requests to meet this limit. The defaults are within sane ranges, but depending on the number of clients hitting a service, you may want to decrease the min even further.

      Min must always be less than max, and ideally max should be greater by 10x.

      Parameters:
      initial - The initial concurrency allowed, helps with faster start.
      min - The minimum concurrency allowed, this can not be less than 1 to allow progress.
      max - The maximum concurrency allowed.
      Returns:
      this.
    • backoffRatio

      public AimdCapacityLimiterBuilder backoffRatio(float onDrop, float onLimit)
      Defines the backoff ratios for AIMD. Ratios are used to alter the limit of the CapacityLimiter by the provided multiplier on different conditions as identified by their name.

      The formula for the backoff ratio used is: NewLimit = OldLimit * BackoffRatio, always respecting the min and max values.

      Both limits must be between 0 and 1 exclusively.

      Parameters:
      onDrop - The backoff ratio used to bring the limit down by that amount, when a request is dropped either by a server response identified as a rejection, or by a local timeout.
      onLimit - The backoff ratio used to bring the limit down by that amount, when the maximum limit is reached.
      Returns:
      this.
    • increment

      public AimdCapacityLimiterBuilder increment(float increment)
      Defines the additive factor of this algorithm. Tuning this preference allows to control the speed that the limit can grow within a certain cool-down period.
      Parameters:
      increment - The incremental step of the limit during a successful response after a cool-down period.
      Returns:
      this.
    • cooldown

      public AimdCapacityLimiterBuilder cooldown(Duration duration)
      Defines a period during which the additive part of the algorithm doesn't kick-in. This period helps to allow the transport to adjust on the new limits before more adjustments happen. Tuning this allows more stable limits rather than continuous increases and decreases.
      Parameters:
      duration - The period during which no more additive adjustments will take place.
      Returns:
      this.
    • stateObserver

      A observer to consume the current limit of this CapacityLimiter and its consumed capacity, respectively. Useful to monitor the limit through logging or metrics, or just debugging.

      The rate of reporting limit and consumption to the observer is based on the rate of change to this CapacityLimiter.

      It's expected that this AimdCapacityLimiterBuilder.StateObserver is not going to block the thread that invokes it.

      Parameters:
      observer - The AimdCapacityLimiterBuilder.StateObserver to inform about the current capacity and consumption of this CapacityLimiter.
      Returns:
      this.
    • build

      public CapacityLimiter build()
      Builds an AIMD dynamic CapacityLimiter based on config options of this builder.
      Returns:
      A dynamic CapacityLimiter based on the options of this builder.