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> CompletableFuture<T>	eval(org.apache.hadoop.util.functional.CallableRaisingIOE<T> callable) Evaluate a CallableRaisingIOE in the current thread, converting IOEs to RTEs and propagating.
static void	propagateOptions(FSBuilder<?,?> builder, Configuration conf, String prefix, boolean mandatory) Propagate options to any builder, converting everything with the prefix to an option where, if there were 2+ dot-separated elements, it is converted to a schema.
static <T,U extends FSBuilder<T,U>> FSBuilder<T,U>	propagateOptions(FSBuilder<T,U> builder, Configuration conf, String optionalPrefix, String mandatoryPrefix) Propagate options to any builder, converting everything with the prefix to an option where, if there were 2+ dot-separated elements, it is converted to a schema.
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

timeout - timeout to wait

unit - time unit.

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.

propagateOptions

public static <T,U extends FSBuilder<T,U>> FSBuilder<T,U> propagateOptions(FSBuilder<T,U> builder,
                                                                           Configuration conf,
                                                                           String optionalPrefix,
                                                                           String mandatoryPrefix)

Propagate options to any builder, converting everything with the prefix to an option where, if there were 2+ dot-separated elements, it is converted to a schema. See propagateOptions(FSBuilder, Configuration, String, boolean).

Type Parameters:

T - type of result

U - type of builder

Parameters:

builder - builder to modify

conf - configuration to read

optionalPrefix - prefix for optional settings

mandatoryPrefix - prefix for mandatory settings

Returns:

the builder passed in.

propagateOptions

public static void propagateOptions(FSBuilder<?,?> builder,
                                    Configuration conf,
                                    String prefix,
                                    boolean mandatory)

Propagate options to any builder, converting everything with the prefix to an option where, if there were 2+ dot-separated elements, it is converted to a schema.

   fs.example.s3a.option becomes "s3a.option"
   fs.example.fs.io.policy becomes "fs.io.policy"
   fs.example.something becomes "something"
 

Parameters:

builder - builder to modify

conf - configuration to read

prefix - prefix to scan/strip

mandatory - are the options to be mandatory or optional?

eval

public static <T> CompletableFuture<T> eval(org.apache.hadoop.util.functional.CallableRaisingIOE<T> callable)

Evaluate a CallableRaisingIOE in the current thread, converting IOEs to RTEs and propagating.

Type Parameters:

T - Return type.

Parameters:

callable - callable to invoke

Returns:

the evaluated result.

Throws:

UnsupportedOperationException - fail fast if unsupported

IllegalArgumentException - invalid argument