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.TimeUnit;
022
023/**
024 * Produces proxies that impose a time limit on method calls to the proxied object. For example, to
025 * return the value of {@code target.someMethod()}, but substitute {@code DEFAULT_VALUE} if this
026 * method call takes over 50 ms, you can use this code:
027 *
028 * <pre>
029 *   TimeLimiter limiter = . . .;
030 *   TargetType proxy = limiter.newProxy(
031 *       target, TargetType.class, 50, TimeUnit.MILLISECONDS);
032 *   try {
033 *     return proxy.someMethod();
034 *   } catch (UncheckedTimeoutException e) {
035 *     return DEFAULT_VALUE;
036 *   }
037 * </pre>
038 *
039 * <p>Please see {@code SimpleTimeLimiterTest} for more usage examples.
040 *
041 * @author Kevin Bourrillion
042 * @since 1.0
043 */
044@Beta
045@GwtIncompatible
046public interface TimeLimiter {
047
048  /**
049   * Returns an instance of {@code interfaceType} that delegates all method calls to the
050   * {@code target} object, enforcing the specified time limit on each call. This time-limited
051   * delegation is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and
052   * {@link Object#toString}.
053   *
054   * <p>If the target method call finishes before the limit is reached, the return value or
055   * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is
056   * reached, the proxy will attempt to abort the call to the target, and will throw an
057   * {@link UncheckedTimeoutException} to the caller.
058   *
059   * <p>It is important to note that the primary purpose of the proxy object is to return control to
060   * the caller when the timeout elapses; aborting the target method call is of secondary concern.
061   * The particular nature and strength of the guarantees made by the proxy is
062   * implementation-dependent. However, it is important that each of the methods on the target
063   * object behaves appropriately when its thread is interrupted.
064   *
065   * @param target the object to proxy
066   * @param interfaceType the interface you wish the returned proxy to implement
067   * @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to
068   *     wait on each method call to the proxy
069   * @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to
070   *     wait on each method call to the proxy
071   * @return a time-limiting proxy
072   * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or
073   *     annotation type, rather than an interface
074   */
075  <T> T newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit);
076
077  /**
078   * Invokes a specified Callable, timing out after the specified time limit. If the target method
079   * call finished before the limit is reached, the return value or exception is propagated to the
080   * caller exactly as-is. If, on the other hand, the time limit is reached, we attempt to abort the
081   * call to the target, and throw an {@link UncheckedTimeoutException} to the caller.
082   *
083   * @param callable the Callable to execute
084   * @param timeoutDuration with timeoutUnit, the maximum length of time to wait
085   * @param timeoutUnit with timeoutDuration, the maximum length of time to wait
086   * @param interruptible whether to respond to thread interruption by aborting the operation and
087   *     throwing InterruptedException; if false, the operation is allowed to complete or time out,
088   *     and the current thread's interrupt status is re-asserted.
089   * @return the result returned by the Callable
090   * @throws InterruptedException if {@code interruptible} is true and our thread is interrupted
091   *     during execution
092   * @throws UncheckedTimeoutException if the time limit is reached
093   */
094  @CanIgnoreReturnValue
095  <T> T callWithTimeout(
096      Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit, boolean interruptible)
097      throws Exception;
098}