BlueThrottle (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper.server

## Class BlueThrottle

- java.lang.Object
- - org.apache.zookeeper.server.BlueThrottle

-     public class BlueThrottle
      extends Object

  Implements a token-bucket based rate limiting mechanism with optional probabilistic dropping inspired by the BLUE queue management algorithm [1]. The throttle provides the `checkLimit(int)` method which provides a binary yes/no decision. The core token bucket algorithm starts with an initial set of tokens based on the `maxTokens` setting. Tokens are dispensed each `checkLimit(int)` call, which fails if there are not enough tokens to satisfy a given request. The token bucket refills over time, providing `fillCount` tokens every `fillTime` milliseconds, capping at `maxTokens`. This design allows the throttle to allow short bursts to pass, while still capping the total number of requests per time interval. One issue with a pure token bucket approach for something like request or connection throttling is that the wall clock arrival time of requests affects the probability of a request being allowed to pass or not. Under constant load this can lead to request starvation for requests that constantly arrive later than the majority. In an attempt to combat this, this throttle can also provide probabilistic dropping. This is enabled anytime `freezeTime` is set to a value other than `-1`. The probabilistic algorithm starts with an initial drop probability of 0, and adjusts this probability roughly every `freezeTime` milliseconds. The first request after `freezeTime`, the algorithm checks the token bucket. If the token bucket is empty, the drop probability is increased by `dropIncrease` up to a maximum of `1`. Otherwise, if the bucket has a token deficit less than `decreasePoint * maxTokens`, the probability is decreased by `dropDecrease`. Given a call to `checkLimit(int)`, requests are first dropped randomly based on the current drop probability, and only surviving requests are then checked against the token bucket. When under constant load, the probabilistic algorithm will adapt to a drop frequency that should keep requests within the token limit. When load drops, the drop probability will decrease, eventually returning to zero if possible. [1] "BLUE: A New Class of Active Queue Management Algorithms"

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONNECTION_THROTTLE_DECREASE_RATIO`
    `static String` | `CONNECTION_THROTTLE_DROP_DECREASE`
    `static String` | `CONNECTION_THROTTLE_DROP_INCREASE`
    `static String` | `CONNECTION_THROTTLE_FILL_COUNT`
    `static String` | `CONNECTION_THROTTLE_FILL_TIME`
    `static String` | `CONNECTION_THROTTLE_FREEZE_TIME`
    `static String` | `CONNECTION_THROTTLE_TOKENS`
    `static String` | `GLOBAL_SESSION_WEIGHT`
    `static String` | `LOCAL_SESSION_WEIGHT`
    `static String` | `RENEW_SESSION_WEIGHT`
    `static String` | `WEIGHED_CONNECTION_THROTTLE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BlueThrottle()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkBlue(long now)`
    `boolean` | `checkLimit(int need)`
    `double` | `getDecreasePoint()`
    `int` | `getDeficit()`
    `double` | `getDropChance()`
    `double` | `getDropDecrease()`
    `double` | `getDropIncrease()`
    `int` | `getFillCount()`
    `int` | `getFillTime()`
    `int` | `getFreezeTime()`
    `int` | `getMaxTokens()`
    `int` | `getRequiredTokensForGlobal()`
    `int` | `getRequiredTokensForLocal()`
    `int` | `getRequiredTokensForRenew()`
    `boolean` | `isConnectionWeightEnabled()`
    `protected static void` | `setConnectionWeightEnabled(boolean enabled)`
    `void` | `setDecreasePoint(double ratio)`
    `void` | `setDropDecrease(double decrease)`
    `void` | `setDropIncrease(double increase)`
    `void` | `setFillCount(int count)`
    `void` | `setFillTime(int time)`
    `void` | `setFreezeTime(int time)`
    `void` | `setMaxTokens(int max)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### CONNECTION_THROTTLE_TOKENS

          public static final String CONNECTION_THROTTLE_TOKENS

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_FILL_TIME

          public static final String CONNECTION_THROTTLE_FILL_TIME

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_FILL_COUNT

          public static final String CONNECTION_THROTTLE_FILL_COUNT

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_FREEZE_TIME

          public static final String CONNECTION_THROTTLE_FREEZE_TIME

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_DROP_INCREASE

          public static final String CONNECTION_THROTTLE_DROP_INCREASE

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_DROP_DECREASE

          public static final String CONNECTION_THROTTLE_DROP_DECREASE

      See Also:
        Constant Field Values

    - #### CONNECTION_THROTTLE_DECREASE_RATIO

          public static final String CONNECTION_THROTTLE_DECREASE_RATIO

      See Also:
        Constant Field Values

    - #### WEIGHED_CONNECTION_THROTTLE

          public static final String WEIGHED_CONNECTION_THROTTLE

      See Also:
        Constant Field Values

    - #### GLOBAL_SESSION_WEIGHT

          public static final String GLOBAL_SESSION_WEIGHT

      See Also:
        Constant Field Values

    - #### LOCAL_SESSION_WEIGHT

          public static final String LOCAL_SESSION_WEIGHT

      See Also:
        Constant Field Values

    - #### RENEW_SESSION_WEIGHT

          public static final String RENEW_SESSION_WEIGHT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BlueThrottle

          public BlueThrottle()

  - ### Method Detail

    - #### setConnectionWeightEnabled

          protected static void setConnectionWeightEnabled(boolean enabled)

    - #### setMaxTokens

          public void setMaxTokens(int max)

    - #### setFillTime

          public void setFillTime(int time)

    - #### setFillCount

          public void setFillCount(int count)

    - #### setFreezeTime

          public void setFreezeTime(int time)

    - #### setDropIncrease

          public void setDropIncrease(double increase)

    - #### setDropDecrease

          public void setDropDecrease(double decrease)

    - #### setDecreasePoint

          public void setDecreasePoint(double ratio)

    - #### getMaxTokens

          public int getMaxTokens()

    - #### getFillTime

          public int getFillTime()

    - #### getFillCount

          public int getFillCount()

    - #### getFreezeTime

          public int getFreezeTime()

    - #### getDropIncrease

          public double getDropIncrease()

    - #### getDropDecrease

          public double getDropDecrease()

    - #### getDecreasePoint

          public double getDecreasePoint()

    - #### getDropChance

          public double getDropChance()

    - #### getDeficit

          public int getDeficit()

    - #### getRequiredTokensForGlobal

          public int getRequiredTokensForGlobal()

    - #### getRequiredTokensForLocal

          public int getRequiredTokensForLocal()

    - #### getRequiredTokensForRenew

          public int getRequiredTokensForRenew()

    - #### isConnectionWeightEnabled

          public boolean isConnectionWeightEnabled()

    - #### checkLimit

          public boolean checkLimit(int need)

    - #### checkBlue

          public boolean checkBlue(long now)

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.