[Groovy] Annotation Type TimedInterrupt

All Implemented Interfaces and Traits:

Annotation

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

See Also:

ThreadInterrupt

ConditionalInterrupt

Since:

1.8.0