Package com.foundationdb.async

Provides a basic asynchronous programming library for Java.

Concepts

In this library, the concepts from computer science of Future/Promise are present and named Future/Settable. As a way to deal in a reasonable manner with the presence of checked Exceptions in Java (which essentially add information to the return signature of code) this library adds the idea of Partial. Named after the mathematical concept of partial functions -- which do not have an output defined for the full range of inputs -- PartialFunction are declared to throw Exceptions as some inputs will not have a valid output. Using the same names, PartialFutures are the outputs of PartialFunctions and can have checked exceptions set as an unsuccessful output -- and those checked exceptions can be thrown from PartialFuture.get().

Practical Use

Most client use of this library should either use a blocking structure with threads calling Future.get() or use the asynchronous "mapping" functions. Use Future.map(Function) when the output of a Future needs only simple, fast transformation (e.g. for decoding small pieces of data from one format to another). Use Future.flatMap(Function) when the output will serve as the input to another longer running asynchronous process.

Cancellation

Future extends the interface Cancellable and therefore can represent an operation that can be cancelled in some fashion. Cancelling a Future will cancel the process behind it, even if the Future being cancelled is a derived result of another process (see Future.flatMap(Function)). Therefore, Futures should only be cancelled when it is known that no other piece of code depends on the output of this source process. Calling com.foundationdb.async.Future#cancel() is the same as calling PartialFuture.dispose().