@Documented @Retention(value: RetentionPolicy.SOURCE) @Target(value: [ElementType.PACKAGE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.LOCAL_VARIABLE]) @GroovyASTTransformationClass(value: [org.codehaus.groovy.transform.TimedInterruptibleASTTransformation]) @interface TimedInterrupt
Allows safe timed executions of scripts by adding elapsed time checks into loops (for, while) and at the start of closures and methods and throwing an exception if a timeout occurs.
This is especially useful when executing foreign scripts that you do not have control over. Inject this transformation into a script that you want to timeout after a specified amount of time.
Annotating anything in a script will cause for loops, while loops, methods, and closures to make an elapsed time check and throw a TimeoutException if the check yields true. The annotation by default will apply to any classes defined in the script as well. Annotating a class will cause (by default) all classes in the entire file ('Compilation Unit') to be enhanced. You can fine tune what is enhanced using the annotation parameters. Static methods and static fields are ignored.
The following is sample usage of the annotation forcing the script to timeout after 5 minutes (300 seconds):
import groovy.transform.TimedInterrupt
import java.util.concurrent.TimeUnit
@TimedInterrupt(value = 300L, unit = TimeUnit.SECONDS)
class MyClass {
def method() {
println '...'
}
}
This sample script will be transformed at compile time to something that resembles this:
import java.util.concurrent.TimeUnit
import java.util.concurrent.TimeoutException
public class MyClass {
// XXXXXX below is a placeholder for a hashCode value at runtime
final private long timedInterruptXXXXXX$expireTime
final private java.util.Date timedInterruptXXXXXX$startTime
public MyClass() {
timedInterruptXXXXXX$expireTime = System.nanoTime() + TimeUnit.NANOSECONDS.convert(300, TimeUnit.SECONDS)
timedInterruptXXXXXX$startTime = new java.util.Date()
}
public java.lang.Object method() {
if (timedInterruptXXXXXX$expireTime < System.nanoTime()) {
throw new TimeoutException('Execution timed out after 300 units. Start time: ' + timedInterruptXXXXXX$startTime)
}
return this.println('...')
}
}
See the unit test for this class for additional examples. | Type Params | Return Type | Name and description |
|---|---|---|
|
abstract boolean |
applyToAllClasses()Set this to false if you have multiple classes within one source file and only want timeout checks on some of the classes (or you want different time constraints on different classes). |
|
abstract boolean |
applyToAllMembers()Set this to false if you have multiple methods/closures within a class or script and only want timeout checks on some of them (or you want different time constraints on different methods/closures). |
|
abstract boolean |
checkOnMethodStart()By default a time check is added to the start of all user-defined methods. |
|
abstract Class |
thrown()The type of exception thrown when timeout is reached. |
|
abstract TimeUnit |
unit()The TimeUnit of the value parameter. |
|
abstract long |
value()The maximum elapsed time the script will be allowed to run for. |
Set this to false if you have multiple classes within one source file and only want
timeout checks on some of the classes (or you want different time constraints on different classes).
Place an annotation with appropriate parameters on each class you want enhanced.
Set to true (the default) for blanket coverage of timeout checks on all methods, loops
and closures within all classes/script code.
For even finer-grained control see applyToAllMembers.
Set this to false if you have multiple methods/closures within a class or script and only
want timeout checks on some of them (or you want different time constraints on different methods/closures).
Place annotations with appropriate parameters on the methods/closures that you want enhanced.
When false, applyToAllClasses is automatically set to false.
Set to true (the default) for blanket coverage of timeout checks on all methods, loops
and closures within the class/script.
By default a time check is added to the start of all user-defined methods. To turn this off simply set this parameter to false.
The type of exception thrown when timeout is reached.
The TimeUnit of the value parameter. By default it is TimeUnit.SECONDS.
The maximum elapsed time the script will be allowed to run for. By default it is measure in seconds