Module io.github.bucket4j.core
Package io.github.bucket4j

Class Refill

  • public class Refill
extends Object
    Specifies the speed of tokens regeneration.

    • Method Detail

      • greedy

        public static Refill greedy​(long tokens,
                            Duration period)
        Creates the Refill that does refill of tokens in greedy manner, it will try to add the tokens to bucket as soon as possible. For example refill "10 tokens per 1 second" will add 1 token per each 100 millisecond, in other words refill will not wait 1 second to regenerate whole bunch of 10 tokens.

        The three refills bellow do refill of tokens with same speed: 

              Refill.greedy(600, Duration.ofMinutes(1));
      Refill.greedy(10, Duration.ofSeconds(1));
      Refill.greedy(1, Duration.ofMillis(100));

        If greediness is undesired then you can specify the fixed interval refill via intervally(long, Duration)

        Parameters:
        tokens - amount of tokens
        period - the period within tokens will be fully regenerated
        Returns:
        the Refill that does refill of tokens in of manner

      • intervally

        public static Refill intervally​(long tokens,
                                Duration period)
        Creates the Refill that does refill of tokens in intervally manner. "Intervally" in opposite to "greedy" will wait until whole period will be elapsed before regenerate tokens
        Parameters:
        tokens - amount of tokens
        period - the period within tokens will be fully regenerated
        Returns:
        the Refill that does refill of tokens in intervally manner

      • intervallyAligned

        public static Refill intervallyAligned​(long tokens,
                                       Duration period,
                                       Instant timeOfFirstRefill,
                                       boolean useAdaptiveInitialTokens)
        Creates the Refill that does refill of tokens in intervally manner. "Intervally" in opposite to "greedy" will wait until whole period will be elapsed before regenerate tokens.
        In additional to intervally(long, Duration) it is possible to specify the time when first refill should happen via timeOfFirstRefill. This option can be used to configure clear interval boundary i.e. start of second, minute, hour, day.

        Special notes about useAdaptiveInitialTokens:
        If useAdaptiveInitialTokens == true and timeOfFirstRefill is a moment in the future, then initial amount of tokens in the bandwidth will be calculated by following formula: 

        
     Math.min(capacity, Math.max(0, bandwidthCapacity - refillTokens) + (timeOfFirstRefillMillis - nowMillis)/refillPeriod * refillTokens)

        Bellow the list of examples of how does this formula can be applied: 
         
         // imagine that wall clock is 16:20, the first refill will happen at 17:00
         // first refill will happen in the beginning of next hour
         Instant firstRefillTime = ZonedDateTime.now()
                 .truncatedTo(ChronoUnit.HOURS)
                 .plus(1, ChronoUnit.HOURS)
                 .toInstant();

        // initial tokens 266 will be
        Bandwidth.classic(400, Refill.intervallyAligned(400, Duration.ofHours(1), firstRefillTime, true));
        // calculated by formula min(400, max(0, 400 - 400) +  40/60*400) = min(400, 0 + 266) = 266

        // initial tokens will be 300
        Bandwidth.classic(400, Refill.intervallyAligned(300, Duration.ofHours(1), firstRefillTime, true));
        // calculated by formula min(400, max(0, 400 - 300) +  40/60*300) = min(400, 100 + 200) = 300

        // initial tokens will be 333
        Bandwidth.classic(400, Refill.intervallyAligned(200, Duration.ofHours(1), firstRefillTime, true));
        // calculated by formula min(400, max(0, 400 - 200) +  40/60*200) = min(400, 200 + 133) = 333

        // initial tokens will be 366
        Bandwidth.classic(400, Refill.intervallyAligned(100, Duration.ofHours(1), firstRefillTime, true));
        // calculated by formula min(400, max(0, 400 - 100) +  40/60*100) = min(400, 300 + 66) = 366
        Restrictions:
        Parameters:
        tokens - amount of tokens
        period - the period within tokens will be fully regenerated
        timeOfFirstRefill - the time of first refill, typically it should be a moment in the future
        useAdaptiveInitialTokens - if true then initialTokens may be reduced
        Returns:
        the Refill that does refill of tokens in intervally manner