Misc tiny improvements

- Guard against nanoseconds overflowing a long in RateLimiter
- Clarify javadocs

Author: jhalterman

src/main/java/dev/failsafe/CircuitBreaker.java

@@ -77,7 +77,8 @@ static <R> CircuitBreakerBuilder<R> builder(CircuitBreakerConfig<R> config) {
   /**
    * Creates a count based CircuitBreaker that opens after a {@link CircuitBreakerBuilder#withFailureThreshold(int)
    * single failure}, closes after a {@link CircuitBreakerBuilder#withSuccessThreshold(int) single success}, and has a 1
-   * minute {@link CircuitBreakerBuilder#withDelay(Duration) delay} by default.
+   * minute {@link CircuitBreakerBuilder#withDelay(Duration) delay} by default. To configure additional options on a
+   * CircuitBreaker, use {@link #builder()} instead.
    *
    * @see #builder()
    */
@@ -121,8 +122,8 @@ default void acquirePermit() {
   }
 
   /**
-   * Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired. Permission will
-   * be automatically released when a result or failure is recorded.
+   * Tries to acquire a permit to use the circuit breaker and returns whether a permit was acquired. Permission will be
+   * automatically released when a result or failure is recorded.
    *
    * @see #recordResult(Object)
    * @see #recordFailure(Throwable)

src/main/java/dev/failsafe/CircuitBreakerOpenException.java

@@ -16,7 +16,7 @@
 package dev.failsafe;
 
 /**
- * Thrown when an execution is attempted while a configured {@link CircuitBreaker} is open.
+ * Thrown when an execution is attempted against a {@link CircuitBreaker} that is open.
  *
  * @author Jonathan Halterman
  */

src/main/java/dev/failsafe/RetryPolicy.java

@@ -45,9 +45,10 @@ static <R> RetryPolicyBuilder<R> builder(RetryPolicyConfig<R> config) {
   }
 
   /**
-   * Creates a RetryPolicy that allows 3 execution attempts max with no delay.
+   * Creates a RetryPolicy that allows 3 execution attempts max with no delay. To configure additional options on a
+   * RetryPolicy, use {@link #builder()} instead.
    *
-   * @see #builder() 
+   * @see #builder()
    */
   static <R> RetryPolicy<R> ofDefaults() {
     return RetryPolicy.<R>builder().build();

src/main/java/dev/failsafe/Timeout.java

@@ -70,14 +70,16 @@ static <R> TimeoutBuilder<R> builder(TimeoutConfig<R> config) {
 
   /**
    * Returns a {@link Timeout} that fails an execution with {@link TimeoutExceededException TimeoutExceededException} if
-   * it exceeds the {@code timeout}. Alias for {@code Timeout.builder(timeout).build()}. To configure other options on a
-   * Timeout, use {@link #builder(Duration)} instead.
+   * it exceeds the {@code timeout}. Alias for {@code Timeout.builder(timeout).build()}. To configure additional options
+   * on a Timeout, use {@link #builder(Duration)} instead.
    *
    * @param timeout the duration after which an execution is failed with {@link TimeoutExceededException
    * TimeoutExceededException}.
    * @param <R> result type
    * @throws NullPointerException If {@code timeout} is null
    * @throws IllegalArgumentException If {@code timeout} is <= 0
+   *
+   * @see #builder(Duration)
    */
   static <R> Timeout<R> of(Duration timeout) {
     return new TimeoutImpl<>(new TimeoutConfig<>(timeout, false));

src/main/java/dev/failsafe/internal/RateLimiterImpl.java

@@ -19,6 +19,7 @@
 import dev.failsafe.RateLimiterConfig;
 import dev.failsafe.internal.RateLimiterStats.Stopwatch;
 import dev.failsafe.internal.util.Assert;
+import dev.failsafe.internal.util.Durations;
 import dev.failsafe.spi.PolicyExecutor;
 
 import java.time.Duration;
@@ -68,7 +69,7 @@ public boolean tryAcquirePermits(int permits) {
   public boolean tryAcquirePermits(int permits, Duration maxWaitTime) throws InterruptedException {
     Assert.isTrue(permits > 0, "permits must be > 0");
     Assert.notNull(maxWaitTime, "maxWaitTime");
-    long waitNanos = stats.acquirePermits(permits, maxWaitTime);
+    long waitNanos = stats.acquirePermits(permits, Durations.ofSafeNanos(maxWaitTime));
     if (waitNanos == -1)
       return false;
     if (waitNanos > 0)