de.skuzzle.inject.async.annotation

Annotation Type Async

@Target(value=METHOD)
 @Retention(value=RUNTIME)
public @interface Async

Tags a method to be run asynchronously. Annotated methods must return either a Future or no value (void or Void). To enable asynchronous method support, use GuiceAsync.enableFor(com.google.inject.Binder) in any of your modules.

Method calls are intercepted and the call is then executed in a different thread using an ExecutorService. The ExecutorService instance that will be used is looked up using the Injector.

Specifying the Executor

It is possible to customize the look-up Key that is used to retrieve the actual ExecutorService.

• You can put any BindingAnnotation including Named on the method to specify the annotation part of the Key.
• If you need to reference a certain ExecutorService sub type, you can use Executor to specify the class part of the Key.

For example, your method may look like:

 @Async
 @Named("computationExecutor")
 @Executor(AdvancedExecutorService.class)
 public void compute() {...}
 

In this case, the Executor to use will be looked up like injector.getInstance(Key.get(AdvancedExecutorService.class, Names.named("computationExecutor"))

If you leave out the Executor part, the class defaults to ExecutorService.class. If you leave out the binding annotation, the created key will not have an annotation part. If you put neither a binding annotation nor an Executor class on the method, a default ExecutorService is used that is created internally. You should make no assumptions about the actual behavior of that service and it is highly recommended to bind and specify an ExecutorService yourself.

 public class MyModule extends AbstractModule {
     @Provides
     public ThreadFactory provideMyThreadFactory() {
         return new ThreadFactoryBuilder()....build(); // class from Google guava
     }

     @Provides
     @Named("mainThreadPool")
     public ExecutorService provideMyExecutor(ThreadFactory threadFactory) {
         return Executors.newFixedThreadPool(4, threadFactory);
     }
 }
 

Returning values

You can return a value from an asynchronous method by returning a Future object. To implement such a method, you can obtain a Future for an arbitrary value using Futures.delegate(Object) like in:

 @Async
 public Future<Double> compute() {
     final double result = realComputation();
     return Futures.delegate(result);
 }
 

The dummy Future object created here will be replaced with a real Future object that is obtained from the ExecutorService.

It's also possible to return a CompletableFuture:

 @Async
 public CompletableFuture<Double> compute() {
     final double result = realComputation();
     return Futures.delegateCompletable(result);
 }
 

Thread safety

As your method is executed asynchronously, special care has to be taken to ensure thread safety of that operation. Beware of the following:

• Do not access attributes of the surrounding class. If you do, use synchronization to ensure visibility of the data that you write and read.
• Parameters that are passed to the asynchronous method are also transferred to the executing thread. Thus, all actual parameters must be thread safe. That is, they must use synchronization and/or volatile declarations to ensure integrity and visibility of the data that is written and read.

Exception handling

Asynchronous methods can throw checked exceptions. If they do, the exception will be wrapped in an ExecutionException which will be thrown by Future.get().

This annotation is subject to all limitations that apply to MethodInterceptors. Please see the guice wiki for more information.

Author:

Simon Taddiken