com.google.common.util.concurrent.TimeLimiter Maven / Gradle / Ivy
Show all versions of guava Show documentation
/*
* Copyright (C) 2006 The Guava Authors
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
* in compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package com.google.common.util.concurrent;
import static com.google.common.util.concurrent.Internal.toNanosSaturated;
import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtIncompatible;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import com.google.errorprone.annotations.DoNotMock;
import java.time.Duration;
import java.util.concurrent.Callable;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import org.checkerframework.checker.nullness.qual.Nullable;
/**
* Imposes a time limit on method calls.
*
* @author Kevin Bourrillion
* @author Jens Nyman
* @since 1.0
*/
@Beta
@DoNotMock("Use FakeTimeLimiter")
@GwtIncompatible
@ElementTypesAreNonnullByDefault
public interface TimeLimiter {
/**
* Returns an instance of {@code interfaceType} that delegates all method calls to the {@code
* target} object, enforcing the specified time limit on each call. This time-limited delegation
* is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link
* Object#toString}.
*
* If the target method call finishes before the limit is reached, the return value or
* exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is
* reached, the proxy will attempt to abort the call to the target, and will throw an {@link
* UncheckedTimeoutException} to the caller.
*
*
It is important to note that the primary purpose of the proxy object is to return control to
* the caller when the timeout elapses; aborting the target method call is of secondary concern.
* The particular nature and strength of the guarantees made by the proxy is
* implementation-dependent. However, it is important that each of the methods on the target
* object behaves appropriately when its thread is interrupted.
*
*
For example, to return the value of {@code target.someMethod()}, but substitute {@code
* DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code:
*
*
* TimeLimiter limiter = . . .;
* TargetType proxy = limiter.newProxy(
* target, TargetType.class, 50, TimeUnit.MILLISECONDS);
* try {
* return proxy.someMethod();
* } catch (UncheckedTimeoutException e) {
* return DEFAULT_VALUE;
* }
*
*
* @param target the object to proxy
* @param interfaceType the interface you wish the returned proxy to implement
* @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to
* wait on each method call to the proxy
* @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to
* wait on each method call to the proxy
* @return a time-limiting proxy
* @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or
* annotation type, rather than an interface
*/
@SuppressWarnings("GoodTime") // should accept a java.time.Duration
T newProxy(T target, Class interfaceType, long timeoutDuration, TimeUnit timeoutUnit);
/**
* Returns an instance of {@code interfaceType} that delegates all method calls to the {@code
* target} object, enforcing the specified time limit on each call. This time-limited delegation
* is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link
* Object#toString}.
*
* If the target method call finishes before the limit is reached, the return value or
* exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is
* reached, the proxy will attempt to abort the call to the target, and will throw an {@link
* UncheckedTimeoutException} to the caller.
*
*
It is important to note that the primary purpose of the proxy object is to return control to
* the caller when the timeout elapses; aborting the target method call is of secondary concern.
* The particular nature and strength of the guarantees made by the proxy is
* implementation-dependent. However, it is important that each of the methods on the target
* object behaves appropriately when its thread is interrupted.
*
*
For example, to return the value of {@code target.someMethod()}, but substitute {@code
* DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code:
*
*
* TimeLimiter limiter = . . .;
* TargetType proxy = limiter.newProxy(target, TargetType.class, Duration.ofMillis(50));
* try {
* return proxy.someMethod();
* } catch (UncheckedTimeoutException e) {
* return DEFAULT_VALUE;
* }
*
*
* @param target the object to proxy
* @param interfaceType the interface you wish the returned proxy to implement
* @param timeout the maximum length of time that callers are willing to wait on each method call
* to the proxy
* @return a time-limiting proxy
* @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or
* annotation type, rather than an interface
* @since 28.0
*/
default T newProxy(T target, Class interfaceType, Duration timeout) {
return newProxy(target, interfaceType, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
}
/**
* Invokes a specified Callable, timing out after the specified time limit. If the target method
* call finishes before the limit is reached, the return value or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
* the target, and throw a {@link TimeoutException} to the caller.
*
* @param callable the Callable to execute
* @param timeoutDuration with timeoutUnit, the maximum length of time to wait
* @param timeoutUnit with timeoutDuration, the maximum length of time to wait
* @return the result returned by the Callable
* @throws TimeoutException if the time limit is reached
* @throws InterruptedException if the current thread was interrupted during execution
* @throws ExecutionException if {@code callable} throws a checked exception
* @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code callable} throws an {@code Error}
* @since 22.0
*/
@SuppressWarnings("GoodTime") // should accept a java.time.Duration
@CanIgnoreReturnValue
T callWithTimeout(
Callable callable, long timeoutDuration, TimeUnit timeoutUnit)
throws TimeoutException, InterruptedException, ExecutionException;
/**
* Invokes a specified Callable, timing out after the specified time limit. If the target method
* call finishes before the limit is reached, the return value or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
* the target, and throw a {@link TimeoutException} to the caller.
*
* @param callable the Callable to execute
* @param timeout the maximum length of time to wait
* @return the result returned by the Callable
* @throws TimeoutException if the time limit is reached
* @throws InterruptedException if the current thread was interrupted during execution
* @throws ExecutionException if {@code callable} throws a checked exception
* @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code callable} throws an {@code Error}
* @since 28.0
*/
@CanIgnoreReturnValue
default T callWithTimeout(Callable callable, Duration timeout)
throws TimeoutException, InterruptedException, ExecutionException {
return callWithTimeout(callable, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
}
/**
* Invokes a specified Callable, timing out after the specified time limit. If the target method
* call finishes before the limit is reached, the return value or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
* the target, and throw a {@link TimeoutException} to the caller.
*
* The difference with {@link #callWithTimeout(Callable, long, TimeUnit)} is that this method
* will ignore interrupts on the current thread.
*
* @param callable the Callable to execute
* @param timeoutDuration with timeoutUnit, the maximum length of time to wait
* @param timeoutUnit with timeoutDuration, the maximum length of time to wait
* @return the result returned by the Callable
* @throws TimeoutException if the time limit is reached
* @throws ExecutionException if {@code callable} throws a checked exception
* @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code callable} throws an {@code Error}
* @since 22.0
*/
@SuppressWarnings("GoodTime") // should accept a java.time.Duration
@CanIgnoreReturnValue
T callUninterruptiblyWithTimeout(
Callable callable, long timeoutDuration, TimeUnit timeoutUnit)
throws TimeoutException, ExecutionException;
/**
* Invokes a specified Callable, timing out after the specified time limit. If the target method
* call finishes before the limit is reached, the return value or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
* the target, and throw a {@link TimeoutException} to the caller.
*
* The difference with {@link #callWithTimeout(Callable, Duration)} is that this method will
* ignore interrupts on the current thread.
*
* @param callable the Callable to execute
* @param timeout the maximum length of time to wait
* @return the result returned by the Callable
* @throws TimeoutException if the time limit is reached
* @throws ExecutionException if {@code callable} throws a checked exception
* @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code callable} throws an {@code Error}
* @since 28.0
*/
@CanIgnoreReturnValue
default T callUninterruptiblyWithTimeout(
Callable callable, Duration timeout) throws TimeoutException, ExecutionException {
return callUninterruptiblyWithTimeout(
callable, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
}
/**
* Invokes a specified Runnable, timing out after the specified time limit. If the target method
* run finishes before the limit is reached, this method returns or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
* throw a {@link TimeoutException} to the caller.
*
* @param runnable the Runnable to execute
* @param timeoutDuration with timeoutUnit, the maximum length of time to wait
* @param timeoutUnit with timeoutDuration, the maximum length of time to wait
* @throws TimeoutException if the time limit is reached
* @throws InterruptedException if the current thread was interrupted during execution
* @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code runnable} throws an {@code Error}
* @since 22.0
*/
@SuppressWarnings("GoodTime") // should accept a java.time.Duration
void runWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
throws TimeoutException, InterruptedException;
/**
* Invokes a specified Runnable, timing out after the specified time limit. If the target method
* run finishes before the limit is reached, this method returns or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
* throw a {@link TimeoutException} to the caller.
*
* @param runnable the Runnable to execute
* @param timeout the maximum length of time to wait
* @throws TimeoutException if the time limit is reached
* @throws InterruptedException if the current thread was interrupted during execution
* @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code runnable} throws an {@code Error}
* @since 28.0
*/
default void runWithTimeout(Runnable runnable, Duration timeout)
throws TimeoutException, InterruptedException {
runWithTimeout(runnable, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
}
/**
* Invokes a specified Runnable, timing out after the specified time limit. If the target method
* run finishes before the limit is reached, this method returns or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
* throw a {@link TimeoutException} to the caller.
*
* The difference with {@link #runWithTimeout(Runnable, long, TimeUnit)} is that this method
* will ignore interrupts on the current thread.
*
* @param runnable the Runnable to execute
* @param timeoutDuration with timeoutUnit, the maximum length of time to wait
* @param timeoutUnit with timeoutDuration, the maximum length of time to wait
* @throws TimeoutException if the time limit is reached
* @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code runnable} throws an {@code Error}
* @since 22.0
*/
@SuppressWarnings("GoodTime") // should accept a java.time.Duration
void runUninterruptiblyWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
throws TimeoutException;
/**
* Invokes a specified Runnable, timing out after the specified time limit. If the target method
* run finishes before the limit is reached, this method returns or a wrapped exception is
* propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
* throw a {@link TimeoutException} to the caller.
*
*
The difference with {@link #runWithTimeout(Runnable, Duration)} is that this method will
* ignore interrupts on the current thread.
*
* @param runnable the Runnable to execute
* @param timeout the maximum length of time to wait
* @throws TimeoutException if the time limit is reached
* @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
* @throws ExecutionError if {@code runnable} throws an {@code Error}
* @since 28.0
*/
default void runUninterruptiblyWithTimeout(Runnable runnable, Duration timeout)
throws TimeoutException {
runUninterruptiblyWithTimeout(runnable, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
}
}