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 static com.google.common.util.concurrent.Internal.toNanosSaturated; 018import static java.util.concurrent.TimeUnit.NANOSECONDS; 019 020import com.google.common.annotations.GwtIncompatible; 021import com.google.common.annotations.J2ktIncompatible; 022import com.google.errorprone.annotations.CanIgnoreReturnValue; 023import com.google.errorprone.annotations.DoNotMock; 024import java.time.Duration; 025import java.util.concurrent.Callable; 026import java.util.concurrent.ExecutionException; 027import java.util.concurrent.TimeUnit; 028import java.util.concurrent.TimeoutException; 029import org.jspecify.annotations.Nullable; 030 031/** 032 * Imposes a time limit on method calls. 033 * 034 * @author Kevin Bourrillion 035 * @author Jens Nyman 036 * @since 1.0 037 */ 038@DoNotMock("Use FakeTimeLimiter") 039@J2ktIncompatible 040@GwtIncompatible 041public interface TimeLimiter { 042 043 /** 044 * Returns an instance of {@code interfaceType} that delegates all method calls to the {@code 045 * target} object, enforcing the specified time limit on each call. This time-limited delegation 046 * is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link 047 * Object#toString}. 048 * 049 * <p>If the target method call finishes before the limit is reached, the return value or 050 * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is 051 * reached, the proxy will attempt to abort the call to the target, and will throw an {@link 052 * UncheckedTimeoutException} to the caller. 053 * 054 * <p>It is important to note that the primary purpose of the proxy object is to return control to 055 * the caller when the timeout elapses; aborting the target method call is of secondary concern. 056 * The particular nature and strength of the guarantees made by the proxy is 057 * implementation-dependent. However, it is important that each of the methods on the target 058 * object behaves appropriately when its thread is interrupted. 059 * 060 * <p>For example, to return the value of {@code target.someMethod()}, but substitute {@code 061 * DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code: 062 * 063 * <pre> 064 * TimeLimiter limiter = . . .; 065 * TargetType proxy = limiter.newProxy( 066 * target, TargetType.class, 50, TimeUnit.MILLISECONDS); 067 * try { 068 * return proxy.someMethod(); 069 * } catch (UncheckedTimeoutException e) { 070 * return DEFAULT_VALUE; 071 * } 072 * </pre> 073 * 074 * @param target the object to proxy 075 * @param interfaceType the interface you wish the returned proxy to implement 076 * @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to 077 * wait on each method call to the proxy 078 * @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to 079 * wait on each method call to the proxy 080 * @return a time-limiting proxy 081 * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or 082 * annotation type, rather than an interface 083 */ 084 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 085 <T> T newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit); 086 087 /** 088 * Returns an instance of {@code interfaceType} that delegates all method calls to the {@code 089 * target} object, enforcing the specified time limit on each call. This time-limited delegation 090 * is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link 091 * Object#toString}. 092 * 093 * <p>If the target method call finishes before the limit is reached, the return value or 094 * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is 095 * reached, the proxy will attempt to abort the call to the target, and will throw an {@link 096 * UncheckedTimeoutException} to the caller. 097 * 098 * <p>It is important to note that the primary purpose of the proxy object is to return control to 099 * the caller when the timeout elapses; aborting the target method call is of secondary concern. 100 * The particular nature and strength of the guarantees made by the proxy is 101 * implementation-dependent. However, it is important that each of the methods on the target 102 * object behaves appropriately when its thread is interrupted. 103 * 104 * <p>For example, to return the value of {@code target.someMethod()}, but substitute {@code 105 * DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code: 106 * 107 * <pre> 108 * TimeLimiter limiter = . . .; 109 * TargetType proxy = limiter.newProxy(target, TargetType.class, Duration.ofMillis(50)); 110 * try { 111 * return proxy.someMethod(); 112 * } catch (UncheckedTimeoutException e) { 113 * return DEFAULT_VALUE; 114 * } 115 * </pre> 116 * 117 * @param target the object to proxy 118 * @param interfaceType the interface you wish the returned proxy to implement 119 * @param timeout the maximum length of time that callers are willing to wait on each method call 120 * to the proxy 121 * @return a time-limiting proxy 122 * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or 123 * annotation type, rather than an interface 124 * @since 28.0 125 */ 126 default <T> T newProxy(T target, Class<T> interfaceType, Duration timeout) { 127 return newProxy(target, interfaceType, toNanosSaturated(timeout), NANOSECONDS); 128 } 129 130 /** 131 * Invokes a specified Callable, timing out after the specified time limit. If the target method 132 * call finishes before the limit is reached, the return value or a wrapped exception is 133 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 134 * the target, and throw a {@link TimeoutException} to the caller. 135 * 136 * @param callable the Callable to execute 137 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 138 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 139 * @return the result returned by the Callable 140 * @throws TimeoutException if the time limit is reached 141 * @throws InterruptedException if the current thread was interrupted during execution 142 * @throws ExecutionException if {@code callable} throws a checked exception 143 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 144 * @throws ExecutionError if {@code callable} throws an {@code Error} 145 * @since 22.0 146 */ 147 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 148 @CanIgnoreReturnValue 149 @ParametricNullness 150 <T extends @Nullable Object> T callWithTimeout( 151 Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit) 152 throws TimeoutException, InterruptedException, ExecutionException; 153 154 /** 155 * Invokes a specified Callable, timing out after the specified time limit. If the target method 156 * call finishes before the limit is reached, the return value or a wrapped exception is 157 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 158 * the target, and throw a {@link TimeoutException} to the caller. 159 * 160 * @param callable the Callable to execute 161 * @param timeout the maximum length of time to wait 162 * @return the result returned by the Callable 163 * @throws TimeoutException if the time limit is reached 164 * @throws InterruptedException if the current thread was interrupted during execution 165 * @throws ExecutionException if {@code callable} throws a checked exception 166 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 167 * @throws ExecutionError if {@code callable} throws an {@code Error} 168 * @since 28.0 169 */ 170 @CanIgnoreReturnValue 171 @ParametricNullness 172 default <T extends @Nullable Object> T callWithTimeout(Callable<T> callable, Duration timeout) 173 throws TimeoutException, InterruptedException, ExecutionException { 174 return callWithTimeout(callable, toNanosSaturated(timeout), NANOSECONDS); 175 } 176 177 /** 178 * Invokes a specified Callable, timing out after the specified time limit. If the target method 179 * call finishes before the limit is reached, the return value or a wrapped exception is 180 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 181 * the target, and throw a {@link TimeoutException} to the caller. 182 * 183 * <p>The difference with {@link #callWithTimeout(Callable, long, TimeUnit)} is that this method 184 * will ignore interrupts on the current thread. 185 * 186 * @param callable the Callable to execute 187 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 188 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 189 * @return the result returned by the Callable 190 * @throws TimeoutException if the time limit is reached 191 * @throws ExecutionException if {@code callable} throws a checked exception 192 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 193 * @throws ExecutionError if {@code callable} throws an {@code Error} 194 * @since 22.0 195 */ 196 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 197 @CanIgnoreReturnValue 198 @ParametricNullness 199 <T extends @Nullable Object> T callUninterruptiblyWithTimeout( 200 Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit) 201 throws TimeoutException, ExecutionException; 202 203 /** 204 * Invokes a specified Callable, timing out after the specified time limit. If the target method 205 * call finishes before the limit is reached, the return value or a wrapped exception is 206 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 207 * the target, and throw a {@link TimeoutException} to the caller. 208 * 209 * <p>The difference with {@link #callWithTimeout(Callable, Duration)} is that this method will 210 * ignore interrupts on the current thread. 211 * 212 * @param callable the Callable to execute 213 * @param timeout the maximum length of time to wait 214 * @return the result returned by the Callable 215 * @throws TimeoutException if the time limit is reached 216 * @throws ExecutionException if {@code callable} throws a checked exception 217 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 218 * @throws ExecutionError if {@code callable} throws an {@code Error} 219 * @since 28.0 220 */ 221 @CanIgnoreReturnValue 222 @ParametricNullness 223 default <T extends @Nullable Object> T callUninterruptiblyWithTimeout( 224 Callable<T> callable, Duration timeout) throws TimeoutException, ExecutionException { 225 return callUninterruptiblyWithTimeout(callable, toNanosSaturated(timeout), NANOSECONDS); 226 } 227 228 /** 229 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 230 * run finishes before the limit is reached, this method returns or a wrapped exception is 231 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 232 * throw a {@link TimeoutException} to the caller. 233 * 234 * @param runnable the Runnable to execute 235 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 236 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 237 * @throws TimeoutException if the time limit is reached 238 * @throws InterruptedException if the current thread was interrupted during execution 239 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 240 * @throws ExecutionError if {@code runnable} throws an {@code Error} 241 * @since 22.0 242 */ 243 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 244 void runWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit) 245 throws TimeoutException, InterruptedException; 246 247 /** 248 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 249 * run finishes before the limit is reached, this method returns or a wrapped exception is 250 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 251 * throw a {@link TimeoutException} to the caller. 252 * 253 * @param runnable the Runnable to execute 254 * @param timeout the maximum length of time to wait 255 * @throws TimeoutException if the time limit is reached 256 * @throws InterruptedException if the current thread was interrupted during execution 257 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 258 * @throws ExecutionError if {@code runnable} throws an {@code Error} 259 * @since 28.0 260 */ 261 default void runWithTimeout(Runnable runnable, Duration timeout) 262 throws TimeoutException, InterruptedException { 263 runWithTimeout(runnable, toNanosSaturated(timeout), NANOSECONDS); 264 } 265 266 /** 267 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 268 * run finishes before the limit is reached, this method returns or a wrapped exception is 269 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 270 * throw a {@link TimeoutException} to the caller. 271 * 272 * <p>The difference with {@link #runWithTimeout(Runnable, long, TimeUnit)} is that this method 273 * will ignore interrupts on the current thread. 274 * 275 * @param runnable the Runnable to execute 276 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 277 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 278 * @throws TimeoutException if the time limit is reached 279 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 280 * @throws ExecutionError if {@code runnable} throws an {@code Error} 281 * @since 22.0 282 */ 283 @SuppressWarnings("GoodTime") // should accept a java.time.Duration 284 void runUninterruptiblyWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit) 285 throws TimeoutException; 286 287 /** 288 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 289 * run finishes before the limit is reached, this method returns or a wrapped exception is 290 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 291 * throw a {@link TimeoutException} to the caller. 292 * 293 * <p>The difference with {@link #runWithTimeout(Runnable, Duration)} is that this method will 294 * ignore interrupts on the current thread. 295 * 296 * @param runnable the Runnable to execute 297 * @param timeout the maximum length of time to wait 298 * @throws TimeoutException if the time limit is reached 299 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 300 * @throws ExecutionError if {@code runnable} throws an {@code Error} 301 * @since 28.0 302 */ 303 default void runUninterruptiblyWithTimeout(Runnable runnable, Duration timeout) 304 throws TimeoutException { 305 runUninterruptiblyWithTimeout(runnable, toNanosSaturated(timeout), NANOSECONDS); 306 } 307}