1 /* 2 * Copyright (C) 2006 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.util.concurrent; 18 19 import com.google.common.annotations.Beta; 20 21 import java.util.concurrent.Callable; 22 import java.util.concurrent.TimeUnit; 23 24 /** 25 * Produces proxies that impose a time limit on method 26 * calls to the proxied object. For example, to return the value of 27 * {@code target.someMethod()}, but substitute {@code DEFAULT_VALUE} if this 28 * method call takes over 50 ms, you can use this code: 29 * <pre> 30 * TimeLimiter limiter = . . .; 31 * TargetType proxy = limiter.newProxy( 32 * target, TargetType.class, 50, TimeUnit.MILLISECONDS); 33 * try { 34 * return proxy.someMethod(); 35 * } catch (UncheckedTimeoutException e) { 36 * return DEFAULT_VALUE; 37 * } 38 * </pre> 39 * Please see {@code SimpleTimeLimiterTest} for more usage examples. 40 * 41 * @author Kevin Bourrillion 42 * @since 1.0 43 */ 44 @Beta 45 public interface TimeLimiter { 46 47 /** 48 * Returns an instance of {@code interfaceType} that delegates all method 49 * calls to the {@code target} object, enforcing the specified time limit on 50 * each call. This time-limited delegation is also performed for calls to 51 * {@link Object#equals}, {@link Object#hashCode}, and 52 * {@link Object#toString}. 53 * <p> 54 * If the target method call finishes before the limit is reached, the return 55 * value or exception is propagated to the caller exactly as-is. If, on the 56 * other hand, the time limit is reached, the proxy will attempt to abort the 57 * call to the target, and will throw an {@link UncheckedTimeoutException} to 58 * the caller. 59 * <p> 60 * It is important to note that the primary purpose of the proxy object is to 61 * return control to the caller when the timeout elapses; aborting the target 62 * method call is of secondary concern. The particular nature and strength 63 * of the guarantees made by the proxy is implementation-dependent. However, 64 * it is important that each of the methods on the target object behaves 65 * appropriately when its thread is interrupted. 66 * 67 * @param target the object to proxy 68 * @param interfaceType the interface you wish the returned proxy to 69 * implement 70 * @param timeoutDuration with timeoutUnit, the maximum length of time that 71 * callers are willing to wait on each method call to the proxy 72 * @param timeoutUnit with timeoutDuration, the maximum length of time that 73 * callers are willing to wait on each method call to the proxy 74 * @return a time-limiting proxy 75 * @throws IllegalArgumentException if {@code interfaceType} is a regular 76 * class, enum, or annotation type, rather than an interface 77 */ 78 <T> T newProxy(T target, Class<T> interfaceType, 79 long timeoutDuration, TimeUnit timeoutUnit); 80 81 /** 82 * Invokes a specified Callable, timing out after the specified time limit. 83 * If the target method call finished before the limit is reached, the return 84 * value or exception is propagated to the caller exactly as-is. If, on the 85 * other hand, the time limit is reached, we attempt to abort the call to the 86 * target, and throw an {@link UncheckedTimeoutException} to the caller. 87 * <p> 88 * <b>Warning:</b> The future of this method is in doubt. It may be nuked, or 89 * changed significantly. 90 * 91 * @param callable the Callable to execute 92 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 93 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 94 * @param interruptible whether to respond to thread interruption by aborting 95 * the operation and throwing InterruptedException; if false, the 96 * operation is allowed to complete or time out, and the current thread's 97 * interrupt status is re-asserted. 98 * @return the result returned by the Callable 99 * @throws InterruptedException if {@code interruptible} is true and our 100 * thread is interrupted during execution 101 * @throws UncheckedTimeoutException if the time limit is reached 102 * @throws Exception 103 */ 104 <T> T callWithTimeout(Callable<T> callable, long timeoutDuration, 105 TimeUnit timeoutUnit, boolean interruptible) throws Exception; 106 } 107
