Class LocalRatelimiter

  • All Implemented Interfaces:
    Ratelimiter


    public class LocalRatelimiter
    extends Object
    implements Ratelimiter
    An implementation of Ratelimiter that allows for simple local ratelimits.

    To compensate for misalignment with the real global ratelimit bucket, it is recommended to not set the value to the exact global ratelimit but a lower value. If the global ratelimit for your bot is 50 requests / 1 second (the default), you should choose a value that prevents overlapping with the real bucket. This can be achieved with the following rules:

    • Choose an amount that is between 1 and half of the real amount (in this example 1 - 25).
    • Calculate the bucketDuration using (amount * realDuration) / (realAmount - amount).
    For the 50 requests / 1 second ratelimit, these rules allow the following ratelimits (only a subset):
    • About 1 request per 20.5 ms (amount = 1 and bucketDuration = Duration.ofMillis((long) Math.ceil(1D / 49D)))
    • About 5 request per 111.1 ms (amount = 5 and bucketDuration = Duration.ofMillis((long) Math.ceil(5D / 45D))).
    • 10 request per 250 ms (amount = 10 and bucketDuration = Duration.ofMillis((long) Math.ceil(10D / 40D))).
    • 25 request per 1 sec (amount = 25 and bucketDuration = Duration.ofMillis((long) Math.ceil(10D / 40D))).
    Choosing a lower amount increases the maximum throughput but can limits your ability to perform actions in bulk.
    See Also:
    Related wiki article, DiscordApiBuilder.setGlobalRatelimiter(Ratelimiter)
    • Constructor Detail

      • LocalRatelimiter

        @Deprecated
        public LocalRatelimiter​(int amount,
                                int seconds)
        Deprecated. Use LocalRatelimiter(int, Duration) instead.
        Creates a new local ratelimiter.
        Parameters:
        amount - The amount available per reset interval.
        seconds - The time to wait until the available quota resets.
      • LocalRatelimiter

        public LocalRatelimiter​(int amount,
                                Duration bucketDuration)
        Creates a new local ratelimiter.
        Parameters:
        amount - The amount available per reset interval.
        bucketDuration - The time to wait until the available quota resets.
    • Method Detail

      • getAmount

        public int getAmount​()
        Gets the amount available per reset interval.
        Returns:
        The amount.
      • getBucketDuration

        public Duration getBucketDuration​()
        Gets the time to wait until the available quota resets.
        Returns:
        The time to wait until the available quota resets.
      • getSeconds

        @Deprecated
        public int getSeconds​()
        Deprecated. Use getBucketDuration() instead.
        Gets the time to wait until the available quota resets in seconds.
        Returns:
        The time to wait until the available quota resets.
      • getNextResetNanos

        public long getNextResetNanos​()
        Gets the next time the quota resets.

        Use System.nanoTime() to calculate the absolute difference.

        Returns:
        The next time the quota resets. Can be in the past.
      • getRemainingQuota

        public int getRemainingQuota​()
        Gets the remaining quota in the current reset interval.
        Returns:
        The remaining quota.
      • requestQuota

        public void requestQuota​()
                          throws InterruptedException
        Description copied from interface: Ratelimiter
        Blocks the requesting thread until a quota becomes available.
        Specified by:
        requestQuota in interface Ratelimiter
        Throws:
        InterruptedException - if any thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.