Package dev.failsafe

Interface RateLimiter<R>

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      default void acquirePermit()
      Attempts to acquire a permit to perform an execution against the rate limiter, waiting until one is available or the thread is interrupted.
      default void acquirePermit​(java.time.Duration maxWaitTime)
      Attempts to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until one is available, else throwing RateLimitExceededException if a permit will not be available in time.
      void acquirePermits​(int permits)
      Attempts to acquire the requested permits to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.
      default void acquirePermits​(int permits, java.time.Duration maxWaitTime)
      Attempts to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available, else throwing RateLimitExceededException if the permits will not be available in time.
      static <R> RateLimiterBuilder<R> builder​(RateLimiterConfig<R> config)
      Creates a new RateLimiterBuilder that will be based on the config.
      static <R> RateLimiterBuilder<R> burstyBuilder​(long maxExecutions, java.time.Duration period)
      Returns a bursty RateLimiterBuilder for the maxExecutions per period.
      RateLimiterConfig<R> getConfig()
      Returns the RateLimiterConfig that the RateLimiter was built with.
      default boolean isBursty()
      Returns whether the rate limiter is bursty.
      default boolean isSmooth()
      Returns whether the rate limiter is smooth.
      default java.time.Duration reservePermit()
      Reserves a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit.
      java.time.Duration reservePermits​(int permits)
      Reserves the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits.
      static <R> RateLimiterBuilder<R> smoothBuilder​(long maxExecutions, java.time.Duration period)
      Returns a smooth RateLimiterBuilder for the maxExecutions and period, which control how frequently an execution is permitted.
      static <R> RateLimiterBuilder<R> smoothBuilder​(java.time.Duration maxRate)
      Returns a smooth RateLimiterBuilder for the maxRate, which controls how frequently an execution is permitted.
      default boolean tryAcquirePermit()
      Tries to acquire a permit to perform an execution against the rate limiter, returning immediately without waiting.
      default boolean tryAcquirePermit​(java.time.Duration maxWaitTime)
      Tries to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until they are available.
      boolean tryAcquirePermits​(int permits)
      Tries to acquire the requested permits to perform executions against the rate limiter, returning immediately without waiting.
      boolean tryAcquirePermits​(int permits, java.time.Duration maxWaitTime)
      Tries to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available.
      default java.time.Duration tryReservePermit​(java.time.Duration maxWaitTime)
      Tries to reserve a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit, as long as it's less than the maxWaitTime.
      java.time.Duration tryReservePermits​(int permits, java.time.Duration maxWaitTime)
      Tries to reserve the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits, as long as it's less than the maxWaitTime.
    • Method Detail

      • smoothBuilder

        static <R> RateLimiterBuilder<R> smoothBuilder​(long maxExecutions,
                                                       java.time.Duration period)
        Returns a smooth RateLimiterBuilder for the maxExecutions and period, which control how frequently an execution is permitted. The individual execution rate is computed as period / maxExecutions. For example, with maxExecutions of 100 and a period of 1000 millis, individual executions will be permitted at a max rate of one every 10 millis.

        By default, the returned RateLimiterBuilder will have a max wait time of 0.

        Executions are performed with no delay until they exceed the max rate, after which executions are either rejected or will block and wait until the max wait time is exceeded.

        Parameters:
        maxExecutions - The max number of permitted executions per period
        period - The period after which permitted executions are reset to the maxExecutions
      • smoothBuilder

        static <R> RateLimiterBuilder<R> smoothBuilder​(java.time.Duration maxRate)
        Returns a smooth RateLimiterBuilder for the maxRate, which controls how frequently an execution is permitted. For example, a maxRate of Duration.ofMillis(10) would allow up to one execution every 10 milliseconds.

        By default, the returned RateLimiterBuilder will have a max wait time of 0.

        Executions are performed with no delay until they exceed the maxRate, after which executions are either rejected or will block and wait until the max wait time is exceeded.

        Parameters:
        maxRate - at which individual executions should be permitted
      • burstyBuilder

        static <R> RateLimiterBuilder<R> burstyBuilder​(long maxExecutions,
                                                       java.time.Duration period)
        Returns a bursty RateLimiterBuilder for the maxExecutions per period. For example, a maxExecutions value of 100 with a period of Duration.ofSeconds(1) would allow up to 100 executions every 1 second.

        By default, the returned RateLimiterBuilder will have a max wait time of 0.

        Executions are performed with no delay up until the maxExecutions are reached for the current period, after which executions are either rejected or will block and wait until the max wait time is exceeded.

        Parameters:
        maxExecutions - The max number of permitted executions per period
        period - The period after which permitted executions are reset to the maxExecutions
      • acquirePermit

        default void acquirePermit()
                            throws java.lang.InterruptedException
        Attempts to acquire a permit to perform an execution against the rate limiter, waiting until one is available or the thread is interrupted.
        Throws:
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire a permit
        See Also:
        tryAcquirePermit(), reservePermit()
      • acquirePermits

        void acquirePermits​(int permits)
                     throws java.lang.InterruptedException
        Attempts to acquire the requested permits to perform executions against the rate limiter, waiting until they are available or the thread is interrupted.
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire the permits
        See Also:
        tryAcquirePermits(int), reservePermits(int)
      • acquirePermit

        default void acquirePermit​(java.time.Duration maxWaitTime)
                            throws java.lang.InterruptedException
        Attempts to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until one is available, else throwing RateLimitExceededException if a permit will not be available in time.
        Throws:
        java.lang.NullPointerException - if maxWaitTime is null
        RateLimitExceededException - if the rate limiter cannot acquire a permit within the maxWaitTime
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire a permit
        See Also:
        tryAcquirePermit(Duration)
      • acquirePermits

        default void acquirePermits​(int permits,
                                    java.time.Duration maxWaitTime)
                             throws java.lang.InterruptedException
        Attempts to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available, else throwing RateLimitExceededException if the permits will not be available in time.
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        java.lang.NullPointerException - if maxWaitTime is null
        RateLimitExceededException - if the rate limiter cannot acquire a permit within the maxWaitTime
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire the permits
        See Also:
        tryAcquirePermits(int, Duration)
      • reservePermit

        default java.time.Duration reservePermit()
        Reserves a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit. Returns 0 if the permit is immediately available and no waiting is needed.
        See Also:
        acquirePermit(), tryAcquirePermit()
      • reservePermits

        java.time.Duration reservePermits​(int permits)
        Reserves the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits. Returns 0 if the permits are immediately available and no waiting is needed.
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        See Also:
        acquirePermits(int), tryAcquirePermits(int)
      • tryReservePermit

        default java.time.Duration tryReservePermit​(java.time.Duration maxWaitTime)
        Tries to reserve a permit to perform an execution against the rate limiter, and returns the time that the caller is expected to wait before acting on the permit, as long as it's less than the maxWaitTime.
        • Returns the expected wait time for the permit if it was successfully reserved.
        • Returns 0 if the permit was successfully reserved and no waiting is needed.
        • Returns -1 nanoseconds if the permit was not reserved because the wait time would be greater than the maxWaitTime.
        Throws:
        java.lang.NullPointerException - if maxWaitTime is null
        See Also:
        acquirePermit(Duration), tryAcquirePermit(Duration)
      • tryReservePermits

        java.time.Duration tryReservePermits​(int permits,
                                             java.time.Duration maxWaitTime)
        Tries to reserve the permits to perform executions against the rate limiter, and returns the time that the caller is expected to wait before acting on the permits, as long as it's less than the maxWaitTime.
        • Returns the expected wait time for the permits if they were successfully reserved.
        • Returns 0 if the permits were successfully reserved and no waiting is needed.
        • Returns -1 nanoseconds if the permits were not reserved because the wait time would be greater than the maxWaitTime.
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        java.lang.NullPointerException - if maxWaitTime is null
        See Also:
        acquirePermit(Duration), tryAcquirePermit(Duration)
      • tryAcquirePermit

        default boolean tryAcquirePermit()
        Tries to acquire a permit to perform an execution against the rate limiter, returning immediately without waiting.
        Returns:
        whether the requested permits are successfully acquired or not
        See Also:
        acquirePermit(), reservePermits(int)
      • tryAcquirePermits

        boolean tryAcquirePermits​(int permits)
        Tries to acquire the requested permits to perform executions against the rate limiter, returning immediately without waiting.
        Returns:
        whether the requested permits are successfully acquired or not
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        See Also:
        acquirePermits(int)
      • tryAcquirePermit

        default boolean tryAcquirePermit​(java.time.Duration maxWaitTime)
                                  throws java.lang.InterruptedException
        Tries to acquire a permit to perform an execution against the rate limiter, waiting up to the maxWaitTime until they are available.
        Returns:
        whether a permit is successfully acquired
        Throws:
        java.lang.NullPointerException - if maxWaitTime is null
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire a permit
        See Also:
        acquirePermit(Duration)
      • tryAcquirePermits

        boolean tryAcquirePermits​(int permits,
                                  java.time.Duration maxWaitTime)
                           throws java.lang.InterruptedException
        Tries to acquire the requested permits to perform executions against the rate limiter, waiting up to the maxWaitTime until they are available.
        Returns:
        whether the requested permits are successfully acquired or not
        Throws:
        java.lang.IllegalArgumentException - if permits is < 1
        java.lang.NullPointerException - if maxWaitTime is null
        java.lang.InterruptedException - if the current thread is interrupted while waiting to acquire the permits
        See Also:
        acquirePermits(int, Duration)