1 /* 2 * Copyright (C) 2006 Google Inc. 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 java.util.concurrent.Callable; 20 import java.util.concurrent.TimeUnit; 21 22 /** 23 * Produces proxies that impose a time limit on method 24 * calls to the proxied object. For example, to return the value of 25 * {@code target.someMethod()}, but substitute {@code DEFAULT_VALUE} if this 26 * method call takes over 50 ms, you can use this code: 27 * <pre> 28 * TimeLimiter limiter = . . .; 29 * TargetType proxy = limiter.newProxy( 30 * target, TargetType.class, 50, TimeUnit.MILLISECONDS); 31 * try { 32 * return proxy.someMethod(); 33 * } catch (UncheckedTimeoutException e) { 34 * return DEFAULT_VALUE; 35 * } 36 * </pre> 37 * Please see {@code SimpleTimeLimiterTest} for more usage examples. 38 * 39 * @author Kevin Bourrillion 40 * @since 2009.09.15 <b>tentative</b> 41 */ 42 public interface TimeLimiter { 43 44 /** 45 * Returns an instance of {@code interfaceType} that delegates all method 46 * calls to the {@code target} object, enforcing the specified time limit on 47 * each call. This time-limited delegation is also performed for calls to 48 * {@link Object#equals}, {@link Object#hashCode}, and 49 * {@link Object#toString}. 50 * <p> 51 * If the target method call finishes before the limit is reached, the return 52 * value or exception is propagated to the caller exactly as-is. If, on the 53 * other hand, the time limit is reached, the proxy will attempt to abort the 54 * call to the target, and will throw an {@link UncheckedTimeoutException} to 55 * the caller. 56 * <p> 57 * It is important to note that the primary purpose of the proxy object is to 58 * return control to the caller when the timeout elapses; aborting the target 59 * method call is of secondary concern. The particular nature and strength 60 * of the guarantees made by the proxy is implementation-dependent. However, 61 * it is important that each of the methods on the target object behaves 62 * appropriately when its thread is interrupted. 63 * 64 * @param target the object to proxy 65 * @param interfaceType the interface you wish the returned proxy to 66 * implement 67 * @param timeoutDuration with timeoutUnit, the maximum length of time that 68 * callers are willing to wait on each method call to the proxy 69 * @param timeoutUnit with timeoutDuration, the maximum length of time that 70 * callers are willing to wait on each method call to the proxy 71 * @return a time-limiting proxy 72 * @throws IllegalArgumentException if {@code interfaceType} is a regular 73 * class, enum, or annotation type, rather than an interface 74 */ newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit)75 <T> T newProxy(T target, Class<T> interfaceType, 76 long timeoutDuration, TimeUnit timeoutUnit); 77 78 /** 79 * Invokes a specified Callable, timing out after the specified time limit. 80 * If the target method call finished before the limit is reached, the return 81 * value or exception is propagated to the caller exactly as-is. If, on the 82 * other hand, the time limit is reached, we attempt to abort the call to the 83 * target, and throw an {@link UncheckedTimeoutException} to the caller. 84 * <p> 85 * <b>Warning:</b> The future of this method is in doubt. It may be nuked, or 86 * changed significantly. 87 * 88 * @param callable the Callable to execute 89 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 90 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 91 * @param interruptible whether to respond to thread interruption by aborting 92 * the operation and throwing InterruptedException; if false, the 93 * operation is allowed to complete or time out, and the current thread's 94 * interrupt status is re-asserted. 95 * @return the result returned by the Callable 96 * @throws InterruptedException if {@code interruptible} is true and our 97 * thread is interrupted during execution 98 * @throws UncheckedTimeoutException if the time limit is reached 99 * @throws Exception 100 */ callWithTimeout(Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit, boolean interruptible)101 <T> T callWithTimeout(Callable<T> callable, long timeoutDuration, 102 TimeUnit timeoutUnit, boolean interruptible) throws Exception; 103 } 104