ThreadInterrupt (groovy 2.4.11 API)
Date: 2017-04-27

Package: groovy.transform

## [Groovy] Annotation Type ThreadInterrupt

- groovy.transform.ThreadInterrupt

- Allows "interrupt-safe" executions of scripts by adding Thread.currentThread().isInterrupted() checks into loops (for, while) and at the start of closures and methods.

  This is especially useful when executing foreign scripts that you do not have control over. Inject this transformation into a script that you need to interrupt.

  Annotating anything in a script will cause for loops, while loops, methods, and closures to make an isInterruptedCheck and throw a InterruptedException if the check yields true. The annotation by default will apply to any classes defined in the script as well. Annotated 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.

  The following is sample usage of the annotation:

       @groovy.transform.ThreadInterrupt
       def scriptMethod() {
         4.times {
           println 'executing script method...'
         }
       }

       class MyClass {
         def myMethod() {
           for (i in (1..10)) {
             println 'executing method...'
           }
         }
       }

       scriptMethod()
       new MyClass().myMethod()

  Which results in the following code being generated. Notice the checks and exceptions:

       public class script1290627909406 extends groovy.lang.Script {

           public java.lang.Object scriptMethod() {
               if (java.lang.Thread.currentThread().isInterrupted()) {
                   throw new java.lang.InterruptedException('Execution Interrupted')
               }
               4.times({
                   if (java.lang.Thread.currentThread().isInterrupted()) {
                       throw new java.lang.InterruptedException('Execution Interrupted')
                   }
                   this.println('executing script method...')
               })
           }
       }
       public class MyClass extends java.lang.Object {

         public java.lang.Object myMethod() {
           if (java.lang.Thread.currentThread().isInterrupted()) {
             throw new java.lang.InterruptedException('Execution Interrupted')
           }
           for (java.lang.Object i : (1..10)) {
             if (java.lang.Thread.currentThread().isInterrupted()) {
               throw new java.lang.InterruptedException('Execution Interrupted')
             }
             this.println('executing method...')
           }
         }
       }

       this.scriptMethod()
       new MyClass().myMethod()

  Additional usage examples can be found in the unit test for this class.
  See Also:
    TimedInterrupt
    ConditionalInterrupt
  Authors:
    Cedric Champeau
    Hamlet D'Arcy
    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 isInterrupted checks on some of the classes.
    `null` | `boolean` | `applyToAllMembers()` Set this to false if you have multiple methods/closures within a class or script and only want isInterrupted checks on some of them.
    `null` | `boolean` | `checkOnMethodStart()` By default an isInterrupted check is added to the start of all user-defined methods.
    `null` | `Class` | `thrown()` Sets the type of exception which is thrown.

  - ### 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 isInterrupted checks on some of the classes. Place annotations on the classes you want enhanced. Set to true (the default) for blanket coverage of isInterrupted 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 isInterrupted checks on some of them. Place annotations 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 isInterrupted checks on all methods, loops and closures within the class/script.

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

    - #### boolean checkOnMethodStart()

      By default an isInterrupted 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()

      Sets the type of exception which is thrown.

      Default:
        InterruptedException