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 com.google.errorprone.annotations.DoNotMock; 021import java.util.concurrent.Callable; 022import java.util.concurrent.ExecutionException; 023import java.util.concurrent.TimeUnit; 024import java.util.concurrent.TimeoutException; 025import org.checkerframework.checker.nullness.qual.Nullable; 026 027/** 028 * Imposes a time limit on method calls. 029 * 030 * @author Kevin Bourrillion 031 * @author Jens Nyman 032 * @since 1.0 033 */ 034@Beta 035@DoNotMock("Use FakeTimeLimiter") 036@GwtIncompatible 037@SuppressWarnings("GoodTime") // should have java.time.Duration overloads 038@ElementTypesAreNonnullByDefault 039public interface TimeLimiter { 040 041 /** 042 * Returns an instance of {@code interfaceType} that delegates all method calls to the {@code 043 * target} object, enforcing the specified time limit on each call. This time-limited delegation 044 * is also performed for calls to {@link Object#equals}, {@link Object#hashCode}, and {@link 045 * Object#toString}. 046 * 047 * <p>If the target method call finishes before the limit is reached, the return value or 048 * exception is propagated to the caller exactly as-is. If, on the other hand, the time limit is 049 * reached, the proxy will attempt to abort the call to the target, and will throw an {@link 050 * UncheckedTimeoutException} to the caller. 051 * 052 * <p>It is important to note that the primary purpose of the proxy object is to return control to 053 * the caller when the timeout elapses; aborting the target method call is of secondary concern. 054 * The particular nature and strength of the guarantees made by the proxy is 055 * implementation-dependent. However, it is important that each of the methods on the target 056 * object behaves appropriately when its thread is interrupted. 057 * 058 * <p>For example, to return the value of {@code target.someMethod()}, but substitute {@code 059 * DEFAULT_VALUE} if this method call takes over 50 ms, you can use this code: 060 * 061 * <pre> 062 * TimeLimiter limiter = . . .; 063 * TargetType proxy = limiter.newProxy( 064 * target, TargetType.class, 50, TimeUnit.MILLISECONDS); 065 * try { 066 * return proxy.someMethod(); 067 * } catch (UncheckedTimeoutException e) { 068 * return DEFAULT_VALUE; 069 * } 070 * </pre> 071 * 072 * @param target the object to proxy 073 * @param interfaceType the interface you wish the returned proxy to implement 074 * @param timeoutDuration with timeoutUnit, the maximum length of time that callers are willing to 075 * wait on each method call to the proxy 076 * @param timeoutUnit with timeoutDuration, the maximum length of time that callers are willing to 077 * wait on each method call to the proxy 078 * @return a time-limiting proxy 079 * @throws IllegalArgumentException if {@code interfaceType} is a regular class, enum, or 080 * annotation type, rather than an interface 081 */ 082 <T> T newProxy(T target, Class<T> interfaceType, long timeoutDuration, TimeUnit timeoutUnit); 083 084 /** 085 * Invokes a specified Callable, timing out after the specified time limit. If the target method 086 * call finishes before the limit is reached, the return value or a wrapped exception is 087 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 088 * the target, and throw a {@link TimeoutException} to the caller. 089 * 090 * @param callable the Callable to execute 091 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 092 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 093 * @return the result returned by the Callable 094 * @throws TimeoutException if the time limit is reached 095 * @throws InterruptedException if the current thread was interrupted during execution 096 * @throws ExecutionException if {@code callable} throws a checked exception 097 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 098 * @throws ExecutionError if {@code callable} throws an {@code Error} 099 * @since 22.0 100 */ 101 @CanIgnoreReturnValue 102 <T extends @Nullable Object> T callWithTimeout( 103 Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit) 104 throws TimeoutException, InterruptedException, ExecutionException; 105 106 /** 107 * Invokes a specified Callable, timing out after the specified time limit. If the target method 108 * call finishes before the limit is reached, the return value or a wrapped exception is 109 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the call to 110 * the target, and throw a {@link TimeoutException} to the caller. 111 * 112 * <p>The difference with {@link #callWithTimeout(Callable, long, TimeUnit)} is that this method 113 * will ignore interrupts on the current thread. 114 * 115 * @param callable the Callable to execute 116 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 117 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 118 * @return the result returned by the Callable 119 * @throws TimeoutException if the time limit is reached 120 * @throws ExecutionException if {@code callable} throws a checked exception 121 * @throws UncheckedExecutionException if {@code callable} throws a {@code RuntimeException} 122 * @throws ExecutionError if {@code callable} throws an {@code Error} 123 * @since 22.0 124 */ 125 @CanIgnoreReturnValue 126 <T extends @Nullable Object> T callUninterruptiblyWithTimeout( 127 Callable<T> callable, long timeoutDuration, TimeUnit timeoutUnit) 128 throws TimeoutException, ExecutionException; 129 130 /** 131 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 132 * run finishes before the limit is reached, this method returns or a wrapped exception is 133 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 134 * throw a {@link TimeoutException} to the caller. 135 * 136 * @param runnable the Runnable 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 * @throws TimeoutException if the time limit is reached 140 * @throws InterruptedException if the current thread was interrupted during execution 141 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 142 * @throws ExecutionError if {@code runnable} throws an {@code Error} 143 * @since 22.0 144 */ 145 void runWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit) 146 throws TimeoutException, InterruptedException; 147 148 /** 149 * Invokes a specified Runnable, timing out after the specified time limit. If the target method 150 * run finishes before the limit is reached, this method returns or a wrapped exception is 151 * propagated. If, on the other hand, the time limit is reached, we attempt to abort the run, and 152 * throw a {@link TimeoutException} to the caller. 153 * 154 * <p>The difference with {@link #runWithTimeout(Runnable, long, TimeUnit)} is that this method 155 * will ignore interrupts on the current thread. 156 * 157 * @param runnable the Runnable to execute 158 * @param timeoutDuration with timeoutUnit, the maximum length of time to wait 159 * @param timeoutUnit with timeoutDuration, the maximum length of time to wait 160 * @throws TimeoutException if the time limit is reached 161 * @throws UncheckedExecutionException if {@code runnable} throws a {@code RuntimeException} 162 * @throws ExecutionError if {@code runnable} throws an {@code Error} 163 * @since 22.0 164 */ 165 void runUninterruptiblyWithTimeout(Runnable runnable, long timeoutDuration, TimeUnit timeoutUnit) 166 throws TimeoutException; 167}