TimedInterrupt (groovy 2.4.10 API)
Date: 2017-03-14

Package: groovy.transform

## [Groovy] Annotation Type TimedInterrupt

- groovy.transform.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
  Authors:
    Hamlet D'Arcy
    Cedric Champeau
    Paul King
  Since:
    1.8.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `null` | `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).
    `null` | `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).
    `null` | `boolean` | `checkOnMethodStart()` By default a time check is added to the start of all user-defined methods.
    `null` | `Class` | `thrown()` The type of exception thrown when timeout is reached.
    `null` | `TimeUnit` | `unit()` The TimeUnit of the value parameter.
    `null` | `long` | `value()` The maximum elapsed time the script will be allowed to run for.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Method Detail

    - #### 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`.

      See Also:
        applyToAllMembers()
      Default:
        true

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

      See Also:
        applyToAllClasses()
      Since:
        2.2.0
      Default:
        true

    - #### 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

    - #### Class thrown()

      The type of exception thrown when timeout is reached.

      Default:
        TimeoutException

    - #### TimeUnit unit()

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

      Default:
        TimeUnit.SECONDS

    - #### long value()

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