groovy.transform
[Groovy] Annotation Type TimedInterrupt

java.lang.Object
  groovy.transform.TimedInterrupt

@Documented
@Retention(RetentionPolicy.SOURCE)
@Target([ ElementType.PACKAGE, ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.LOCAL_VARIABLE])
@GroovyASTTransformationClass(["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 '...'
      }
 }
 

 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('...')
     }
 }
 

Authors:

Hamlet D'Arcy

Cedric Champeau

Paul King

See Also:

ThreadInterrupt

ConditionalInterrupt

Since:

1.8.0

applyToAllClasses

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). 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.

Default:

true

See Also:

applyToAllMembers()

applyToAllMembers

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). 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.

Default:

true

See Also:

applyToAllClasses()

Since:

2.2.0

checkOnMethodStart

boolean checkOnMethodStart()

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.

Default:

true

thrown

Class thrown()

The type of exception thrown when timeout is reached.

Default:

TimeoutException

unit

TimeUnit unit()

The TimeUnit of the value parameter. By default it is TimeUnit.SECONDS.

Default:

TimeUnit.SECONDS

value

long value()

The maximum elapsed time the script will be allowed to run for. By default it is measure in seconds

Copyright © 2003-2013 The Codehaus. All rights reserved.