org.apache.hadoop.util.functional

Class FutureIO

java.lang.Object

org.apache.hadoop.util.functional.FutureIO

@InterfaceAudience.Public
 @InterfaceStability.Unstable
public final class FutureIO
extends Object

Future IO Helper methods.

Contains methods promoted from FutureIOSupport because they are a key part of integrating async IO in application code.

One key feature is that the awaitFuture(Future) and awaitFuture(Future, long, TimeUnit) calls will extract and rethrow exceptions raised in the future's execution, including extracting the inner IOException of any UncheckedIOException raised in the future. This makes it somewhat easier to execute IOException-raising code inside futures.

Method Summary

Modifier and Type	Method and Description
static <T> T	awaitFuture(Future<T> future) Given a future, evaluate it.
static <T> T	awaitFuture(Future<T> future, long timeout, TimeUnit unit) Given a future, evaluate it.
static <T> T	raiseInnerCause(CompletionException e) Extract the cause of a completion failure and rethrow it if an IOE or RTE.
static <T> T	raiseInnerCause(ExecutionException e) From the inner cause of an execution exception, extract the inner cause if it is an IOE or RTE.
static IOException	unwrapInnerException(Throwable e) From the inner cause of an execution exception, extract the inner cause to an IOException, raising RuntimeExceptions and Errors immediately.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

awaitFuture

public static <T> T awaitFuture(Future<T> future)
                         throws InterruptedIOException,
                                IOException,
                                RuntimeException

Given a future, evaluate it.

Any exception generated in the future is extracted and rethrown.

Type Parameters:

T - type of the result.

Parameters:

future - future to evaluate

Returns:

the result, if all went well.

Throws:

InterruptedIOException - future was interrupted

IOException - if something went wrong

RuntimeException - any nested RTE thrown

awaitFuture

public static <T> T awaitFuture(Future<T> future,
                                long timeout,
                                TimeUnit unit)
                         throws InterruptedIOException,
                                IOException,
                                RuntimeException,
                                TimeoutException

Given a future, evaluate it.

Any exception generated in the future is extracted and rethrown.

Type Parameters:

T - type of the result.

Parameters:

future - future to evaluate

Returns:

the result, if all went well.

Throws:

InterruptedIOException - future was interrupted

IOException - if something went wrong

RuntimeException - any nested RTE thrown

TimeoutException - the future timed out.

raiseInnerCause

public static <T> T raiseInnerCause(ExecutionException e)
                             throws IOException

From the inner cause of an execution exception, extract the inner cause if it is an IOE or RTE. This will always raise an exception, either the inner IOException, an inner RuntimeException, or a new IOException wrapping the raised exception.

Type Parameters:

T - type of return value.

Parameters:

e - exception.

Returns:

nothing, ever.

Throws:

IOException - either the inner IOException, or a wrapper around any non-Runtime-Exception

RuntimeException - if that is the inner cause.

raiseInnerCause

public static <T> T raiseInnerCause(CompletionException e)
                             throws IOException

Extract the cause of a completion failure and rethrow it if an IOE or RTE.

Type Parameters:

T - type of return value.

Parameters:

e - exception.

Returns:

nothing, ever.

Throws:

IOException - either the inner IOException, or a wrapper around any non-Runtime-Exception

RuntimeException - if that is the inner cause.

unwrapInnerException

public static IOException unwrapInnerException(Throwable e)

From the inner cause of an execution exception, extract the inner cause to an IOException, raising RuntimeExceptions and Errors immediately.

1. If it is an IOE: Return.
2. If it is a UncheckedIOException: return the cause
3. Completion/Execution Exceptions: extract and repeat
4. If it is an RTE or Error: throw.
5. Any other type: wrap in an IOE

Recursively handles wrapped Execution and Completion Exceptions in case something very complicated has happened.

Parameters:

e - exception.

Returns:

an IOException extracted or built from the cause.

Throws:

RuntimeException - if that is the inner cause.

Error - if that is the inner cause.