com.facebook.bolts

Class Task<TResult>

java.lang.Object

com.facebook.bolts.Task<TResult>

Type Parameters:

TResult - The type of the result of the task.

public class Task<TResult>
extends java.lang.Object

Represents the result of an asynchronous operation.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Task.TaskCompletionSource Deprecated. Please use TaskCompletionSource instead.
static interface	Task.UnobservedExceptionHandler Interface for handlers invoked when a failed Task is about to be finalized, but the exception has not been consumed.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.concurrent.ExecutorService	BACKGROUND_EXECUTOR An Executor that executes tasks in parallel.
static java.util.concurrent.Executor	UI_THREAD_EXECUTOR An Executor that executes tasks on the UI thread.

Method Summary

Modifier and Type	Method and Description
static <TResult> Task<TResult>	call(java.util.concurrent.Callable<TResult> callable) Invokes the callable on the current thread, producing a Task.
static <TResult> Task<TResult>	call(java.util.concurrent.Callable<TResult> callable, CancellationToken ct) Invokes the callable on the current thread, producing a Task.
static <TResult> Task<TResult>	call(java.util.concurrent.Callable<TResult> callable, java.util.concurrent.Executor executor) Invokes the callable using the given executor, returning a Task to represent the operation.
static <TResult> Task<TResult>	call(java.util.concurrent.Callable<TResult> callable, java.util.concurrent.Executor executor, CancellationToken ct) Invokes the callable using the given executor, returning a Task to represent the operation.
static <TResult> Task<TResult>	callInBackground(java.util.concurrent.Callable<TResult> callable) Invokes the callable on a background thread, returning a Task to represent the operation.
static <TResult> Task<TResult>	callInBackground(java.util.concurrent.Callable<TResult> callable, CancellationToken ct) Invokes the callable on a background thread, returning a Task to represent the operation.
static <TResult> Task<TResult>	cancelled() Creates a cancelled task.
<TOut> Task<TOut>	cast() Makes a fluent cast of a Task's result possible, avoiding an extra continuation just to cast the type of the result.
Task<java.lang.Void>	continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate, Continuation<java.lang.Void,Task<java.lang.Void>> continuation) Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.
Task<java.lang.Void>	continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate, Continuation<java.lang.Void,Task<java.lang.Void>> continuation, CancellationToken ct) Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.
Task<java.lang.Void>	continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate, Continuation<java.lang.Void,Task<java.lang.Void>> continuation, java.util.concurrent.Executor executor) Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.
Task<java.lang.Void>	continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate, Continuation<java.lang.Void,Task<java.lang.Void>> continuation, java.util.concurrent.Executor executor, CancellationToken ct) Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.
<TContinuationResult> Task<TContinuationResult>	continueWith(Continuation<TResult,TContinuationResult> continuation) Adds a synchronous continuation to this task, returning a new task that completes after the continuation has finished running.
<TContinuationResult> Task<TContinuationResult>	continueWith(Continuation<TResult,TContinuationResult> continuation, CancellationToken ct) Adds a synchronous continuation to this task, returning a new task that completes after the continuation has finished running.
<TContinuationResult> Task<TContinuationResult>	continueWith(Continuation<TResult,TContinuationResult> continuation, java.util.concurrent.Executor executor) Adds a continuation that will be scheduled using the executor, returning a new task that completes after the continuation has finished running.
<TContinuationResult> Task<TContinuationResult>	continueWith(Continuation<TResult,TContinuationResult> continuation, java.util.concurrent.Executor executor, CancellationToken ct) Adds a continuation that will be scheduled using the executor, returning a new task that completes after the continuation has finished running.
<TContinuationResult> Task<TContinuationResult>	continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation) Adds an asynchronous continuation to this task, returning a new task that completes after the task returned by the continuation has completed.
<TContinuationResult> Task<TContinuationResult>	continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation, CancellationToken ct) Adds an asynchronous continuation to this task, returning a new task that completes after the task returned by the continuation has completed.
<TContinuationResult> Task<TContinuationResult>	continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation, java.util.concurrent.Executor executor) Adds an Task-based continuation to this task that will be scheduled using the executor, returning a new task that completes after the task returned by the continuation has completed.
<TContinuationResult> Task<TContinuationResult>	continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation, java.util.concurrent.Executor executor, CancellationToken ct) Adds an Task-based continuation to this task that will be scheduled using the executor, returning a new task that completes after the task returned by the continuation has completed.
static Task<java.lang.Void>	delay(long delay) Creates a task that completes after a time delay.
static Task<java.lang.Void>	delay(long delay, CancellationToken cancellationToken) Creates a task that completes after a time delay.
static <TResult> Task<TResult>	forError(java.lang.Exception error) Creates a faulted task with the given error.
static <TResult> Task<TResult>	forResult(TResult value) Creates a completed task with the given value.
java.lang.Exception	getError()
TResult	getResult()
static Task.UnobservedExceptionHandler	getUnobservedExceptionHandler() Returns the handler invoked when a task has an unobserved exception or null.
boolean	isCancelled()
boolean	isCompleted()
boolean	isFaulted()
Task<java.lang.Void>	makeVoid() Turns a Task into a Task, dropping any result.
<TContinuationResult> Task<TContinuationResult>	onSuccess(Continuation<TResult,TContinuationResult> continuation) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccess(Continuation<TResult,TContinuationResult> continuation, CancellationToken ct) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccess(Continuation<TResult,TContinuationResult> continuation, java.util.concurrent.Executor executor) Runs a continuation when a task completes successfully, forwarding along Exception or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccess(Continuation<TResult,TContinuationResult> continuation, java.util.concurrent.Executor executor, CancellationToken ct) Runs a continuation when a task completes successfully, forwarding along Exception or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation, CancellationToken ct) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation, java.util.concurrent.Executor executor) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
<TContinuationResult> Task<TContinuationResult>	onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation, java.util.concurrent.Executor executor, CancellationToken ct) Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.
static void	setUnobservedExceptionHandler(Task.UnobservedExceptionHandler eh) Set the handler invoked when a task has an unobserved exception.
void	waitForCompletion() Blocks until the task is complete.
boolean	waitForCompletion(long duration, java.util.concurrent.TimeUnit timeUnit) Blocks until the task is complete or times out.
static Task<java.lang.Void>	whenAll(java.util.Collection<? extends Task<?>> tasks) Creates a task that completes when all of the provided tasks are complete.
static <TResult> Task<java.util.List<TResult>>	whenAllResult(java.util.Collection<? extends Task<TResult>> tasks) Creates a task that completes when all of the provided tasks are complete.
static Task<Task<?>>	whenAny(java.util.Collection<? extends Task<?>> tasks) Creates a task that will complete when any of the supplied tasks have completed.
static <TResult> Task<Task<TResult>>	whenAnyResult(java.util.Collection<? extends Task<TResult>> tasks) Creates a task that will complete when any of the supplied tasks have completed.

Methods inherited from class java.lang.Object

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

Field Detail

BACKGROUND_EXECUTOR

public static final java.util.concurrent.ExecutorService BACKGROUND_EXECUTOR

An Executor that executes tasks in parallel.

UI_THREAD_EXECUTOR

public static final java.util.concurrent.Executor UI_THREAD_EXECUTOR

An Executor that executes tasks on the UI thread.

Method Detail

getUnobservedExceptionHandler

public static Task.UnobservedExceptionHandler getUnobservedExceptionHandler()

Returns the handler invoked when a task has an unobserved exception or null.

setUnobservedExceptionHandler

public static void setUnobservedExceptionHandler(Task.UnobservedExceptionHandler eh)

Set the handler invoked when a task has an unobserved exception.

Parameters:

eh - the object to use as an unobserved exception handler. If null then unobserved exceptions will be ignored.

isCompleted

public boolean isCompleted()

Returns:

true if the task completed (has a result, an error, or was cancelled. false otherwise.

isCancelled

public boolean isCancelled()

Returns:

true if the task was cancelled, false otherwise.

isFaulted

public boolean isFaulted()

Returns:

true if the task has an error, false otherwise.

getResult

public TResult getResult()

Returns:

The result of the task, if set. null otherwise.

getError

public java.lang.Exception getError()

Returns:

The error for the task, if set. null otherwise.

waitForCompletion

public void waitForCompletion()
                       throws java.lang.InterruptedException

Blocks until the task is complete.

Throws:

java.lang.InterruptedException

waitForCompletion

public boolean waitForCompletion(long duration,
                                 java.util.concurrent.TimeUnit timeUnit)
                          throws java.lang.InterruptedException

Blocks until the task is complete or times out.

Returns:

true if the task completed (has a result, an error, or was cancelled). false otherwise.

Throws:

java.lang.InterruptedException

forResult

public static <TResult> Task<TResult> forResult(TResult value)

Creates a completed task with the given value.

forError

public static <TResult> Task<TResult> forError(java.lang.Exception error)

Creates a faulted task with the given error.

cancelled

public static <TResult> Task<TResult> cancelled()

Creates a cancelled task.

delay

public static Task<java.lang.Void> delay(long delay)

Creates a task that completes after a time delay.

Parameters:

delay - The number of milliseconds to wait before completing the returned task. Zero and negative values are treated as requests for immediate execution.

delay

public static Task<java.lang.Void> delay(long delay,
                                         CancellationToken cancellationToken)

Creates a task that completes after a time delay.

Parameters:

delay - The number of milliseconds to wait before completing the returned task. Zero and negative values are treated as requests for immediate execution.

cancellationToken - The optional cancellation token that will be checked prior to completing the returned task.

cast

public <TOut> Task<TOut> cast()

Makes a fluent cast of a Task's result possible, avoiding an extra continuation just to cast the type of the result.

makeVoid

public Task<java.lang.Void> makeVoid()

Turns a Task into a Task, dropping any result.

callInBackground

public static <TResult> Task<TResult> callInBackground(java.util.concurrent.Callable<TResult> callable)

Invokes the callable on a background thread, returning a Task to represent the operation.

If you want to cancel the resulting Task throw a CancellationException from the callable.

callInBackground

public static <TResult> Task<TResult> callInBackground(java.util.concurrent.Callable<TResult> callable,
                                                       CancellationToken ct)

Invokes the callable on a background thread, returning a Task to represent the operation.

call

public static <TResult> Task<TResult> call(java.util.concurrent.Callable<TResult> callable,
                                           java.util.concurrent.Executor executor)

Invokes the callable using the given executor, returning a Task to represent the operation.

If you want to cancel the resulting Task throw a CancellationException from the callable.

call

public static <TResult> Task<TResult> call(java.util.concurrent.Callable<TResult> callable,
                                           java.util.concurrent.Executor executor,
                                           CancellationToken ct)

Invokes the callable using the given executor, returning a Task to represent the operation.

call

public static <TResult> Task<TResult> call(java.util.concurrent.Callable<TResult> callable)

Invokes the callable on the current thread, producing a Task.

If you want to cancel the resulting Task throw a CancellationException from the callable.

call

public static <TResult> Task<TResult> call(java.util.concurrent.Callable<TResult> callable,
                                           CancellationToken ct)

Invokes the callable on the current thread, producing a Task.

whenAnyResult

public static <TResult> Task<Task<TResult>> whenAnyResult(java.util.Collection<? extends Task<TResult>> tasks)

Creates a task that will complete when any of the supplied tasks have completed.

The returned task will complete when any of the supplied tasks has completed. The returned task will always end in the completed state with its result set to the first task to complete. This is true even if the first task to complete ended in the canceled or faulted state.

Parameters:

tasks - The tasks to wait on for completion.

Returns:

A task that represents the completion of one of the supplied tasks. The return task's result is the task that completed.

whenAny

public static Task<Task<?>> whenAny(java.util.Collection<? extends Task<?>> tasks)

Creates a task that will complete when any of the supplied tasks have completed.

The returned task will complete when any of the supplied tasks has completed. The returned task will always end in the completed state with its result set to the first task to complete. This is true even if the first task to complete ended in the canceled or faulted state.

Parameters:

tasks - The tasks to wait on for completion.

Returns:

A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed.

whenAllResult

public static <TResult> Task<java.util.List<TResult>> whenAllResult(java.util.Collection<? extends Task<TResult>> tasks)

Creates a task that completes when all of the provided tasks are complete.

If any of the supplied tasks completes in a faulted state, the returned task will also complete in a faulted state, where its exception will resolve to that Exception if a single task fails or an AggregateException of all the Exceptions if multiple tasks fail.

If none of the supplied tasks faulted but at least one of them was cancelled, the returned task will end as cancelled.

If none of the tasks faulted and none of the tasks were cancelled, the resulting task will end completed. The result of the returned task will be set to a list containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks collection contained t1, t2, t3, the output task's result will return an List<TResult> where list.get(0) == t1.getResult(), list.get(1) == t2.getResult(), and list.get(2) == t3.getResult()).

If the supplied collection contains no tasks, the returned task will immediately transition to a completed state before it's returned to the caller. The returned List<TResult> will contain 0 elements.

Parameters:

tasks - The tasks that the return value will wait for before completing.

Returns:

A Task that will resolve to List<TResult> when all the tasks are resolved.

whenAll

public static Task<java.lang.Void> whenAll(java.util.Collection<? extends Task<?>> tasks)

Creates a task that completes when all of the provided tasks are complete.

If any of the supplied tasks completes in a faulted state, the returned task will also complete in a faulted state, where its exception will resolve to that Exception if a single task fails or an AggregateException of all the Exceptions if multiple tasks fail.

If none of the supplied tasks faulted but at least one of them was cancelled, the returned task will end as cancelled.

If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the completed state.

If the supplied collection contains no tasks, the returned task will immediately transition to a completed state before it's returned to the caller.

Parameters:

tasks - The tasks that the return value will wait for before completing.

Returns:

A Task that will resolve to Void when all the tasks are resolved.

continueWhile

public Task<java.lang.Void> continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate,
                                          Continuation<java.lang.Void,Task<java.lang.Void>> continuation)

Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.

continueWhile

public Task<java.lang.Void> continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate,
                                          Continuation<java.lang.Void,Task<java.lang.Void>> continuation,
                                          CancellationToken ct)

Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.

continueWhile

public Task<java.lang.Void> continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate,
                                          Continuation<java.lang.Void,Task<java.lang.Void>> continuation,
                                          java.util.concurrent.Executor executor)

Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.

continueWhile

public Task<java.lang.Void> continueWhile(java.util.concurrent.Callable<java.lang.Boolean> predicate,
                                          Continuation<java.lang.Void,Task<java.lang.Void>> continuation,
                                          java.util.concurrent.Executor executor,
                                          CancellationToken ct)

Continues a task with the equivalent of a Task-based while loop, where the body of the loop is a task continuation.

continueWith

public <TContinuationResult> Task<TContinuationResult> continueWith(Continuation<TResult,TContinuationResult> continuation,
                                                                    java.util.concurrent.Executor executor)

Adds a continuation that will be scheduled using the executor, returning a new task that completes after the continuation has finished running. This allows the continuation to be scheduled on different thread.

continueWith

public <TContinuationResult> Task<TContinuationResult> continueWith(Continuation<TResult,TContinuationResult> continuation,
                                                                    java.util.concurrent.Executor executor,
                                                                    CancellationToken ct)

Adds a continuation that will be scheduled using the executor, returning a new task that completes after the continuation has finished running. This allows the continuation to be scheduled on different thread.

continueWith

public <TContinuationResult> Task<TContinuationResult> continueWith(Continuation<TResult,TContinuationResult> continuation)

Adds a synchronous continuation to this task, returning a new task that completes after the continuation has finished running.

continueWith

public <TContinuationResult> Task<TContinuationResult> continueWith(Continuation<TResult,TContinuationResult> continuation,
                                                                    CancellationToken ct)

Adds a synchronous continuation to this task, returning a new task that completes after the continuation has finished running.

continueWithTask

public <TContinuationResult> Task<TContinuationResult> continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                        java.util.concurrent.Executor executor)

Adds an Task-based continuation to this task that will be scheduled using the executor, returning a new task that completes after the task returned by the continuation has completed.

continueWithTask

public <TContinuationResult> Task<TContinuationResult> continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                        java.util.concurrent.Executor executor,
                                                                        CancellationToken ct)

Adds an Task-based continuation to this task that will be scheduled using the executor, returning a new task that completes after the task returned by the continuation has completed.

continueWithTask

public <TContinuationResult> Task<TContinuationResult> continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation)

Adds an asynchronous continuation to this task, returning a new task that completes after the task returned by the continuation has completed.

continueWithTask

public <TContinuationResult> Task<TContinuationResult> continueWithTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                        CancellationToken ct)

Adds an asynchronous continuation to this task, returning a new task that completes after the task returned by the continuation has completed.

onSuccess

public <TContinuationResult> Task<TContinuationResult> onSuccess(Continuation<TResult,TContinuationResult> continuation,
                                                                 java.util.concurrent.Executor executor)

Runs a continuation when a task completes successfully, forwarding along Exception or cancellation.

onSuccess

public <TContinuationResult> Task<TContinuationResult> onSuccess(Continuation<TResult,TContinuationResult> continuation,
                                                                 java.util.concurrent.Executor executor,
                                                                 CancellationToken ct)

Runs a continuation when a task completes successfully, forwarding along Exception or cancellation.

onSuccess

public <TContinuationResult> Task<TContinuationResult> onSuccess(Continuation<TResult,TContinuationResult> continuation)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.

onSuccess

public <TContinuationResult> Task<TContinuationResult> onSuccess(Continuation<TResult,TContinuationResult> continuation,
                                                                 CancellationToken ct)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.

onSuccessTask

public <TContinuationResult> Task<TContinuationResult> onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                     java.util.concurrent.Executor executor)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.

onSuccessTask

public <TContinuationResult> Task<TContinuationResult> onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                     java.util.concurrent.Executor executor,
                                                                     CancellationToken ct)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.

onSuccessTask

public <TContinuationResult> Task<TContinuationResult> onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.

onSuccessTask

public <TContinuationResult> Task<TContinuationResult> onSuccessTask(Continuation<TResult,Task<TContinuationResult>> continuation,
                                                                     CancellationToken ct)

Runs a continuation when a task completes successfully, forwarding along Exceptions or cancellation.