Package io.engineblock.activityapi.ratelimits

Class TokenPool

  • public class TokenPool
extends java.lang.Object

    Synopsis

    This TokenPool represents a finite quantity which can be replenished with regular refills. Extra tokens that do not fit within the active token pool are saved in a waiting token pool and used to backfill when allowed according to the backfill rate. A detailed explanation for how this works will be included at @link "http://docs.engineblock.io/" under dev notes.

    This is the basis for the token-based rate limiters in EngineBlock. This mechanism is easily adaptable to bursting capability as well as a degree of stricter timing at speed. Various methods for doing this in a lock free way were investigated, but the intrinsic locks provided by synchronized method won out for now. This may be revisited when EB is retrofitted for J11.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static double MIN_CONCURRENT_OPS  

    • Constructor Summary

      Constructors 
      Constructor Description
      TokenPool​(long poolsize, double burstRatio)  
      TokenPool​(RateSpec rateSpec)
      This constructor tries to pick reasonable defaults for the token pool for a given rate spec.

    • Method Summary

      Modifier and Type Method Description
      void apply​(RateSpec rateSpec)
      Change the settings of this token pool, and wake any blocked callers just in case it allows them to proceed.
      long blockAndTake()
      wait for the given number of tokens to be available, and then remove them from the pool.
      long blockAndTake​(long tokens)  
      long getActivePool()  
      double getBurstRatio()  
      RateSpec getRateSpec()  
      long getWaitPool()  
      long getWaitTime()  
      long refill​(long newTokens)
      Add the given number of new tokens to the pool, forcing any amount that would spill over the current pool size into the wait token pool, but moving up to the configured burst tokens back from the wait token pool otherwise.
      long restart()  
      long takeUpTo​(long amt)
      Take tokens up to amt tokens form the pool and report the amount of token removed.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • TokenPool

        public TokenPool​(RateSpec rateSpec)
        This constructor tries to pick reasonable defaults for the token pool for a given rate spec. The active pool must be large enough to contain one op worth of time, and the burst ratio
        Parameters:
        rateSpec - a RateSpec

      • TokenPool

        public TokenPool​(long poolsize,
                 double burstRatio)

    • Method Detail

      • apply

        public void apply​(RateSpec rateSpec)
        Change the settings of this token pool, and wake any blocked callers just in case it allows them to proceed.
        Parameters:
        rateSpec - The rate specifier.

      • getBurstRatio

        public double getBurstRatio()

      • takeUpTo

        public long takeUpTo​(long amt)
        Take tokens up to amt tokens form the pool and report the amount of token removed.
        Parameters:
        amt - tokens requested
        Returns:
        actual number of tokens removed, greater to or equal to zero

      • blockAndTake

        public long blockAndTake()
        wait for the given number of tokens to be available, and then remove them from the pool.
        Returns:
        the total number of tokens untaken, including wait tokens

      • blockAndTake

        public long blockAndTake​(long tokens)

      • getWaitTime

        public long getWaitTime()

      • getWaitPool

        public long getWaitPool()

      • getActivePool

        public long getActivePool()

      • refill

        public long refill​(long newTokens)
        Add the given number of new tokens to the pool, forcing any amount that would spill over the current pool size into the wait token pool, but moving up to the configured burst tokens back from the wait token pool otherwise. The amount of backfilling that occurs is controlled by the backfill ratio, based on the number of tokens submitted. This causes normalizes the backfilling rate to the fill rate, so that it is not sensitive to refill scheduling.
        Parameters:
        newTokens - The number of new tokens to add to the token pools
        Returns:
        the total number of tokens in all pools

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getRateSpec

        public RateSpec getRateSpec()

      • restart

        public long restart()