io.trane.future

Interface InterruptHandler

All Known Subinterfaces:

Future<T>

All Known Implementing Classes:

Promise

@FunctionalInterface
public interface InterruptHandler

Interrupts provide a way to send signals to the current pending Promise given a Future composition. It is a mechanism that enables cancellations. For instance, given this composition that involves an async boundary (userService.get) and a continuation (.map):

Future<String> username = 
  userService.get(userId).map(user -> user.username);

It is possible to raise an interrupt that is received by the userService.get Promise:

username.raise(new TimeoutException);

The Promise created by userService.get can define a custom handler that performs an action in case an interrupt is received.

Promise.apply has overloaded methods that allow the user to set the interrupt handler. This mechanism can be used to cancel requests to remote systems, as Finagle does.

The method interruptible is a shortcut to fail the Promise if it receives any interrupt signal:

Future<String> username = 
  userService.get(userId).interruptible().map(user -> user.username);
  
username.raise(new TimeoutException);

In this case, even if userService.get does not handle interrupts, the Promise is satisfied with the interrupt exception.

The interrupt propagation happens through pointers from each continuation to its parent that are created automatically by the library. In the previous example, the map continuation has a pointer to the Promise that is pending.

Method Summary

Modifier and Type	Method and Description
static InterruptHandler	apply(Collection<? extends InterruptHandler> handlers) Creates an interrupt handle that calls multiple handlers.
static InterruptHandler	apply(InterruptHandler h1, InterruptHandler h2) Creates an interrupt handler that calls to other handlers.
void	raise(Throwable ex) Raises an interrupt.

Method Detail

apply

static InterruptHandler apply(Collection<? extends InterruptHandler> handlers)

Creates an interrupt handle that calls multiple handlers.

Parameters:

handlers - list of handlers to be called.

Returns:

the aggregate interrupt handler.

apply

static InterruptHandler apply(InterruptHandler h1,
                              InterruptHandler h2)

Creates an interrupt handler that calls to other handlers.

Parameters:

h1 - first handler to be called.

h2 - second handler to be called.

Returns:

the aggregate interrupt handler.

raise

void raise(Throwable ex)

Raises an interrupt.

Parameters:

ex - the interrupt exception.