001/*
002 * Copyright (C) 2006 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.util.concurrent;
016
017
018import com.google.common.annotations.GwtIncompatible;
019import com.google.common.annotations.J2ktIncompatible;
020import com.google.errorprone.annotations.CanIgnoreReturnValue;
021import com.google.errorprone.annotations.DoNotMock;
022import java.util.concurrent.Callable;
023import java.util.concurrent.ExecutionException;
024import java.util.concurrent.TimeUnit;
025import java.util.concurrent.TimeoutException;
026import org.checkerframework.checker.nullness.qual.Nullable;
027
028/**
029 * Imposes a time limit on method calls.
030 *
031 * @author Kevin Bourrillion
032 * @author Jens Nyman
033 * @since 1.0
034 */
035@DoNotMock("Use FakeTimeLimiter")
036@J2ktIncompatible
037@GwtIncompatible
038@SuppressWarnings("GoodTime") // should have java.time.Duration overloads
039@ElementTypesAreNonnullByDefault
040public interface TimeLimiter {
041
042  /**
043   * Returns an instance of {@code interfaceType} that delegates all method calls to the {@code
044   * target} object, enforcing the specified time limit on each call. This time-limited delegation
045   * is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link
046   * Object#toString}.
047   *
048   * <p>If the target method call finishes before the limit is reached, the return value or
049   * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is
050   * reached, the proxy will attempt to abort the call to the target, and will throw an {@link
051   * UncheckedTimeoutException} to the caller.
052   *
053   * <p>It is important to note that the primary purpose of the proxy object is to return control to
054   * the caller when the timeout elapses; aborting the target method call is of secondary concern.
055   * The particular nature and strength of the guarantees made by the proxy is
056   * implementation-dependent. However, it is important that each of the methods on the target
057   * object behaves appropriately when its thread is interrupted.
058   *
059   * <p>For example, to return the value of {@code target.someMethod()}, but substitute {@code
060   * DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code:
061   *
062   * <pre>
063   *   TimeLimiter limiter = . . .;
064   *   TargetType proxy = limiter.newProxy(
065   *       target, TargetType.class, 50, TimeUnit.MILLISECONDS);
066   *   try {
067   *     return proxy.someMethod();
068   *   } catch (UncheckedTimeoutException e) {
069   *     return DEFAULT_VALUE;
070   *   }
071   * </pre>
072   *
073   * @param target the object to proxy
074   * @param interfaceType the interface you wish the returned proxy to implement
075   * @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to
076   *     wait on each method call to the proxy
077   * @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to
078   *     wait on each method call to the proxy
079   * @return a time-limiting proxy
080   * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or
081   *     annotation type, rather than an interface
082   */
083  <T> T newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit);
084
085  /**
086   * Invokes a specified Callable, timing out after the specified time limit. If the target method
087   * call finishes before the limit is reached, the return value or a wrapped exception is
088   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
089   * the target, and throw a {@link TimeoutException} to the caller.
090   *
091   * @param callable the Callable to execute
092   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
093   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
094   * @return the result returned by the Callable
095   * @throws TimeoutException if the time limit is reached
096   * @throws InterruptedException if the current thread was interrupted during execution
097   * @throws ExecutionException if {@code callable} throws a checked exception
098   * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
099   * @throws ExecutionError if {@code callable} throws an {@code Error}
100   * @since 22.0
101   */
102  @CanIgnoreReturnValue
103  @ParametricNullness
104  <T extends @Nullable Object> T callWithTimeout(
105      Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit)
106      throws TimeoutException, InterruptedException, ExecutionException;
107
108  /**
109   * Invokes a specified Callable, timing out after the specified time limit. If the target method
110   * call finishes before the limit is reached, the return value or a wrapped exception is
111   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
112   * the target, and throw a {@link TimeoutException} to the caller.
113   *
114   * <p>The difference with {@link #callWithTimeout(Callable, long, TimeUnit)} is that this method
115   * will ignore interrupts on the current thread.
116   *
117   * @param callable the Callable to execute
118   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
119   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
120   * @return the result returned by the Callable
121   * @throws TimeoutException if the time limit is reached
122   * @throws ExecutionException if {@code callable} throws a checked exception
123   * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
124   * @throws ExecutionError if {@code callable} throws an {@code Error}
125   * @since 22.0
126   */
127  @CanIgnoreReturnValue
128  @ParametricNullness
129  <T extends @Nullable Object> T callUninterruptiblyWithTimeout(
130      Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit)
131      throws TimeoutException, ExecutionException;
132
133  /**
134   * Invokes a specified Runnable, timing out after the specified time limit. If the target method
135   * run finishes before the limit is reached, this method returns or a wrapped exception is
136   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
137   * throw a {@link TimeoutException} to the caller.
138   *
139   * @param runnable the Runnable to execute
140   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
141   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
142   * @throws TimeoutException if the time limit is reached
143   * @throws InterruptedException if the current thread was interrupted during execution
144   * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
145   * @throws ExecutionError if {@code runnable} throws an {@code Error}
146   * @since 22.0
147   */
148  void runWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
149      throws TimeoutException, InterruptedException;
150
151  /**
152   * Invokes a specified Runnable, timing out after the specified time limit. If the target method
153   * run finishes before the limit is reached, this method returns or a wrapped exception is
154   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
155   * throw a {@link TimeoutException} to the caller.
156   *
157   * <p>The difference with {@link #runWithTimeout(Runnable, long, TimeUnit)} is that this method
158   * will ignore interrupts on the current thread.
159   *
160   * @param runnable the Runnable to execute
161   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
162   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
163   * @throws TimeoutException if the time limit is reached
164   * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
165   * @throws ExecutionError if {@code runnable} throws an {@code Error}
166   * @since 22.0
167   */
168  void runUninterruptiblyWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
169      throws TimeoutException;
170}