Futures

class Futures
kotlin.Any
   ↳ androidx.camera.core.impl.utils.futures.Futures

Utility class for generating specific implementations of ListenableFuture.

Summary

Public methods

static Unit
addCallback(@NonNull future: ListenableFuture<V>, @NonNull callback: FutureCallback<in V>, @NonNull executor: Executor)

Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

static ListenableFuture<MutableList<V>!>
allAsList(@NonNull futures: MutableCollection<out ListenableFuture<out V>!>)

Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed.

static V?
getDone(@NonNull future: Future<V>)

Returns the result of the input Future, which must have already completed.

static V?
getUninterruptibly(@NonNull future: Future<V>)

Invokes Future.get() uninterruptibly.

static ListenableFuture<V>

Returns an implementation of ListenableFuture which immediately contains an exception that will be thrown by Future#get().

static ScheduledFuture<V>

Returns an implementation of ScheduledFuture which immediately contains an exception that will be thrown by Future#get().

static ListenableFuture<V>
immediateFuture(@Nullable value: V?)

Returns an implementation of ListenableFuture which immediately contains a result.

static ListenableFuture<MutableList<V>!>
successfulAsList(@NonNull futures: MutableCollection<out ListenableFuture<out V>!>)

Creates a new ListenableFuture whose value is a list containing the values of all its successful input futures.

static ListenableFuture<O>
transform(@NonNull input: ListenableFuture<I>, @NonNull function: Function<in I, out O>, @NonNull executor: Executor)

Returns a new Future whose result is derived from the result of the given Future.

static ListenableFuture<O>
transformAsync(@NonNull input: ListenableFuture<I>, @NonNull function: AsyncFunction<in I, out O>, @NonNull executor: Executor)

Returns a new Future whose result is asynchronously derived from the result of the given Future.

Public methods

addCallback

static fun <V : Any!> addCallback(@NonNull future: ListenableFuture<V>, @NonNull callback: FutureCallback<in V>, @NonNull executor: Executor): Unit

Registers separate success and failure callbacks to be run when the Future's computation is complete or, if the computation is already complete, immediately.

Parameters
future ListenableFuture<V>: The future attach the callback to.
callback ListenableFuture<V>: The callback to invoke when future is completed.
executor ListenableFuture<V>: The executor to run callback when the future completes.

allAsList

@NonNull static fun <V : Any!> allAsList(@NonNull futures: MutableCollection<out ListenableFuture<out V>!>): ListenableFuture<MutableList<V>!>

Creates a new ListenableFuture whose value is a list containing the values of all its input futures, if all succeed.

The list of results is in the same order as the input list.

Canceling this future will attempt to cancel all the component futures, and if any of the provided futures fails or is canceled, this one is, too.

Parameters
futures MutableCollection<out ListenableFuture<out V>!>: futures to combine
Return
ListenableFuture<MutableList<V>!>: a future that provides a list of the results of the component futures

getDone

@Nullable static fun <V : Any!> getDone(@NonNull future: Future<V>): V?

Returns the result of the input Future, which must have already completed.

The benefits of this method are twofold. First, the name "getDone" suggests to readers that the Future is already done. Second, if buggy code calls getDone on a Future that is still pending, the program will throw instead of block.

Exceptions
ExecutionException if the Future failed with an exception
CancellationException if the Future was cancelled
IllegalStateException if the Future is not done

getUninterruptibly

@Nullable static fun <V : Any!> getUninterruptibly(@NonNull future: Future<V>): V?

Invokes Future.get() uninterruptibly.

Exceptions
ExecutionException if the computation threw an exception
CancellationException if the computation was cancelled

immediateFailedFuture

@NonNull static fun <V : Any!> immediateFailedFuture(@NonNull cause: Throwable): ListenableFuture<V>

Returns an implementation of ListenableFuture which immediately contains an exception that will be thrown by Future#get().

Parameters
cause Throwable: The cause of the ExecutionException that will be thrown by Future#get().
<V> Throwable: The type of the result.
Return
ListenableFuture<V>: A future which immediately contains an exception.

immediateFailedScheduledFuture

@NonNull static fun <V : Any!> immediateFailedScheduledFuture(@NonNull cause: Throwable): ScheduledFuture<V>

Returns an implementation of ScheduledFuture which immediately contains an exception that will be thrown by Future#get().

Parameters
cause Throwable: The cause of the ExecutionException that will be thrown by Future#get().
<V> Throwable: The type of the result.
Return
ScheduledFuture<V>: A future which immediately contains an exception.

immediateFuture

@NonNull static fun <V : Any!> immediateFuture(@Nullable value: V?): ListenableFuture<V>

Returns an implementation of ListenableFuture which immediately contains a result.

Parameters
value V?: The result that is immediately set on the future.
<V> V?: The type of the result.
Return
ListenableFuture<V>: A future which immediately contains the result.

successfulAsList

@NonNull static fun <V : Any!> successfulAsList(@NonNull futures: MutableCollection<out ListenableFuture<out V>!>): ListenableFuture<MutableList<V>!>

Creates a new ListenableFuture whose value is a list containing the values of all its successful input futures. The list of results is in the same order as the input list, and if any of the provided futures fails or is canceled, its corresponding position will contain null (which is indistinguishable from the future having a successful value of null).

Canceling this future will attempt to cancel all the component futures.

Parameters
futures MutableCollection<out ListenableFuture<out V>!>: futures to combine
Return
ListenableFuture<MutableList<V>!>: a future that provides a list of the results of the component futures

transform

@NonNull static fun <I : Any!, O : Any!> transform(@NonNull input: ListenableFuture<I>, @NonNull function: Function<in I, out O>, @NonNull executor: Executor): ListenableFuture<O>

Returns a new Future whose result is derived from the result of the given Future. If input fails, the returned Future fails with the same exception (and the function is not invoked)

Parameters
input ListenableFuture<I>: The future to transform
function ListenableFuture<I>: A Function to transform the results of the provided future to the results of the returned future.
executor ListenableFuture<I>: Executor to run the function in.
Return
ListenableFuture<O>: A future that holds result of the transformation.

transformAsync

@NonNull static fun <I : Any!, O : Any!> transformAsync(@NonNull input: ListenableFuture<I>, @NonNull function: AsyncFunction<in I, out O>, @NonNull executor: Executor): ListenableFuture<O>

Returns a new Future whose result is asynchronously derived from the result of the given Future. If the given Future fails, the returned Future fails with the same exception (and the function is not invoked).

Parameters
input ListenableFuture<I>: The future to transform
function ListenableFuture<I>: A function to transform the result of the input future to the result of the output future
executor ListenableFuture<I>: Executor to run the function in.
Return
ListenableFuture<O>: A future that holds result of the function (if the input succeeded) or the original input's failure (if not)