Package org.javacord.api.util.ratelimit

Class LocalRatelimiter

  • All Implemented Interfaces:
    Ratelimiter
    public class LocalRatelimiter
extends java.lang.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 21 ms (amount = 1 and bucketDuration = Duration.ofMillis((long) Math.ceil(1000D / 49D)))
    • About 5 request per 112 ms (amount = 5 and bucketDuration = Duration.ofMillis((long) Math.ceil(5000D / 45D))).
    • 10 request per 250 ms (amount = 10 and bucketDuration = Duration.ofMillis((long) Math.ceil(10000D / 40D))).
    • 25 request per 1 sec (amount = 25 and bucketDuration = Duration.ofMillis((long) Math.ceil(25000D / 25D))).
    Choosing a lower amount increases the maximum throughput but can limit your ability to perform actions in bulk.
    See Also:
    Related wiki article, DiscordApiBuilder.setGlobalRatelimiter(Ratelimiter)

    • Constructor Summary

      Constructors 
      Constructor Description
      LocalRatelimiter​(int amount, java.time.Duration bucketDuration)
      Creates a new local ratelimiter.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int getAmount()
      Gets the amount available per reset interval.
      java.time.Duration getBucketDuration()
      Gets the time to wait until the available quota resets.
      long getNextResetNanos()
      Gets the next time the quota resets.
      int getRemainingQuota()
      Gets the remaining quota in the current reset interval.
      void requestQuota()
      Blocks the requesting thread until a quota becomes available.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • LocalRatelimiter

        public LocalRatelimiter​(int amount,
                        java.time.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 java.time.Duration getBucketDuration()
        Gets the time to wait until the available quota resets.
        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 java.lang.InterruptedException
        Description copied from interface: Ratelimiter
        Blocks the requesting thread until a quota becomes available.
        Specified by:
        requestQuota in interface Ratelimiter
        Throws:
        java.lang.InterruptedException - if any thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.