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
017import com.google.common.annotations.Beta;
018import com.google.common.annotations.GwtIncompatible;
019import com.google.errorprone.annotations.CanIgnoreReturnValue;
020import java.util.concurrent.Callable;
021import java.util.concurrent.ExecutionException;
022import java.util.concurrent.TimeUnit;
023import java.util.concurrent.TimeoutException;
024
025/**
026 * Imposes a time limit on method calls.
027 *
028 * @author Kevin Bourrillion
029 * @author Jens Nyman
030 * @since 1.0
031 */
032@Beta
033@GwtIncompatible
034@SuppressWarnings("GoodTime") // should have java.time.Duration overloads
035public interface TimeLimiter {
036
037  /**
038   * Returns an instance of {@code interfaceType} that delegates all method calls to the {@code
039   * target} object, enforcing the specified time limit on each call. This time-limited delegation
040   * is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link
041   * Object#toString}.
042   *
043   * <p>If the target method call finishes before the limit is reached, the return value or
044   * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is
045   * reached, the proxy will attempt to abort the call to the target, and will throw an {@link
046   * UncheckedTimeoutException} to the caller.
047   *
048   * <p>It is important to note that the primary purpose of the proxy object is to return control to
049   * the caller when the timeout elapses; aborting the target method call is of secondary concern.
050   * The particular nature and strength of the guarantees made by the proxy is
051   * implementation-dependent. However, it is important that each of the methods on the target
052   * object behaves appropriately when its thread is interrupted.
053   *
054   * <p>For example, to return the value of {@code target.someMethod()}, but substitute {@code
055   * DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code:
056   *
057   * <pre>
058   *   TimeLimiter limiter = . . .;
059   *   TargetType proxy = limiter.newProxy(
060   *       target, TargetType.class, 50, TimeUnit.MILLISECONDS);
061   *   try {
062   *     return proxy.someMethod();
063   *   } catch (UncheckedTimeoutException e) {
064   *     return DEFAULT_VALUE;
065   *   }
066   * </pre>
067   *
068   * @param target the object to proxy
069   * @param interfaceType the interface you wish the returned proxy to implement
070   * @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to
071   *     wait on each method call to the proxy
072   * @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to
073   *     wait on each method call to the proxy
074   * @return a time-limiting proxy
075   * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or
076   *     annotation type, rather than an interface
077   */
078  <T> T newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit);
079
080  /**
081   * Invokes a specified Callable, timing out after the specified time limit. If the target method
082   * call finishes before the limit is reached, the return value or a wrapped exception is
083   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
084   * the target, and throw a {@link TimeoutException} to the caller.
085   *
086   * @param callable the Callable to execute
087   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
088   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
089   * @return the result returned by the Callable
090   * @throws TimeoutException if the time limit is reached
091   * @throws InterruptedException if the current thread was interrupted during execution
092   * @throws ExecutionException if {@code callable} throws a checked exception
093   * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
094   * @throws ExecutionError if {@code callable} throws an {@code Error}
095   * @since 22.0
096   */
097  @CanIgnoreReturnValue
098  <T> T callWithTimeout(Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit)
099      throws TimeoutException, InterruptedException, ExecutionException;
100
101  /**
102   * Invokes a specified Callable, timing out after the specified time limit. If the target method
103   * call finishes before the limit is reached, the return value or a wrapped exception is
104   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to
105   * the target, and throw a {@link TimeoutException} to the caller.
106   *
107   * <p>The difference with {@link #callWithTimeout(Callable, long, TimeUnit)} is that this method
108   * will ignore interrupts on the current thread.
109   *
110   * @param callable the Callable to execute
111   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
112   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
113   * @return the result returned by the Callable
114   * @throws TimeoutException if the time limit is reached
115   * @throws ExecutionException if {@code callable} throws a checked exception
116   * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException}
117   * @throws ExecutionError if {@code callable} throws an {@code Error}
118   * @since 22.0
119   */
120  @CanIgnoreReturnValue
121  <T> T callUninterruptiblyWithTimeout(
122      Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit)
123      throws TimeoutException, ExecutionException;
124
125  /**
126   * Invokes a specified Runnable, timing out after the specified time limit. If the target method
127   * run finishes before the limit is reached, this method returns or a wrapped exception is
128   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
129   * throw a {@link TimeoutException} to the caller.
130   *
131   * @param runnable the Runnable to execute
132   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
133   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
134   * @throws TimeoutException if the time limit is reached
135   * @throws InterruptedException if the current thread was interrupted during execution
136   * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
137   * @throws ExecutionError if {@code runnable} throws an {@code Error}
138   * @since 22.0
139   */
140  void runWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
141      throws TimeoutException, InterruptedException;
142
143  /**
144   * Invokes a specified Runnable, timing out after the specified time limit. If the target method
145   * run finishes before the limit is reached, this method returns or a wrapped exception is
146   * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and
147   * throw a {@link TimeoutException} to the caller.
148   *
149   * <p>The difference with {@link #runWithTimeout(Runnable, long, TimeUnit)} is that this method
150   * will ignore interrupts on the current thread.
151   *
152   * @param runnable the Runnable to execute
153   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
154   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
155   * @throws TimeoutException if the time limit is reached
156   * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException}
157   * @throws ExecutionError if {@code runnable} throws an {@code Error}
158   * @since 22.0
159   */
160  void runUninterruptiblyWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit)
161      throws TimeoutException;
162}