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}