com.jcabi.aspects

Annotation Type Timeable

@Documented
@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface Timeable

Makes a method time constrained.

For example, this load() method should not take more than a second, and should be interrupted if it takes more:

 @Timeable(limit = 1, unit = TimeUnit.SECONDS)
 String load(String resource) {
   // something that runs potentially long
 }

Important to note that in Java 1.5+ it is impossible to force thread termination, for many reasons. Thus, we can't just call Thread.stop(), when a thread is over a specified time limit. The best thing we can do is to call Thread.interrupt() and hope that the thread itself is checking its Thread.isInterrupted() status. If you want to design your long running methods in a way that Timeable can terminate them, embed a checker into your most intessively used place, for example:

 @Timeable(limit = 1, unit = TimeUnit.SECONDS)
 String load(String resource) {
   while (true) {
     if (Thread.currentThread.isInterrupted()) {
       throw new IllegalStateException("time out");
     }
     // execution as usual
   }
 }

Since:

0.7.16

Version:

$Id$

Author:

Yegor Bugayenko (yegor@tpc2.com)

See Also:

http://www.jcabi.com/jcabi-aspects/, Why Are Thread.stop, Thread.suspend, Thread.resume and Runtime.runFinalizersOnExit Deprecated?a>

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
int	limit Maximum amount allowed for this method.
TimeUnit	unit Time unit for the limit.

Element Detail

limit

public abstract int limit

Maximum amount allowed for this method.

Suppressed Checkstyle violations:

MagicNumber (2 lines)

Default:

15

unit

public abstract TimeUnit unit

Time unit for the limit.

The minimum unit you can use is a second. We simply can't monitor with a frequency higher than a second.

Default:

java.util.concurrent.TimeUnit.SECONDS