public interface

ListenableFuture<V>

implements java.util.concurrent.Future<java.lang.Object>

 androidx.concurrent.ListenableFuture<V>

Subclasses:

ResolvableFuture<V>, AbstractResolvableFuture<V>

Gradle dependencies

compile group: 'androidx.concurrent', name: 'concurrent-listenablefuture', version: '1.0.0-beta01'

  • groupId: androidx.concurrent
  • artifactId: concurrent-listenablefuture
  • version: 1.0.0-beta01

Artifact androidx.concurrent:concurrent-listenablefuture:1.0.0-beta01 it located at Google repository (https://maven.google.com/)

Overview

A java.util.concurrent.Future that accepts completion listeners. Each listener has an associated executor, and it is invoked using this executor once the future's computation is complete. If the computation has already completed when the listener is added, the listener will execute immediately.

See the Guava User Guide article on ListenableFuture.

This class is GWT-compatible.

Purpose

The main purpose of ListenableFuture is to help you chain together a graph of asynchronous operations. You can chain them together manually with calls to methods like Futures.transform, but you will often find it easier to use a framework. Frameworks automate the process, often adding features like monitoring, debugging, and cancellation. Examples of frameworks include:

The main purpose of addListener is to support this chaining. You will rarely use it directly, in part because it does not provide direct access to the Future result. (If you want such access, you may prefer Futures.addCallback.) Still, direct addListener calls are occasionally useful:

 final String name = ...;
 inFlight.add(name);
 ListenableFuture future = service.query(name);
 future.addListener(new Runnable() {
   public void run() {
     processedCount.incrementAndGet();
     inFlight.remove(name);
     lastProcessed.set(name);
     logger.info("Done with {0}", name);
   }
 }, executor);
 

How to get an instance

We encourage you to return ListenableFuture from your methods so that your users can take advantage of the utilities built atop the class. The way that you will create ListenableFuture instances depends on how you currently create Future instances:

  • If you receive them from an java.util.concurrent.ExecutorService, convert that service to a ListeningExecutorService, usually by calling MoreExecutors.listeningDecorator.
  • If you manually call FutureTask.set or a similar method, create a SettableFuture instead. (If your needs are more complex, you may prefer AbstractFuture.)

Test doubles: If you need a ListenableFuture for your test, try a SettableFuture or one of the methods in the Futures.immediate* family. Avoid creating a mock or stub Future. Mock and stub implementations are fragile because they assume that only certain methods will be called and because they often implement subtleties of the API improperly.

Custom implementation: Avoid implementing ListenableFuture from scratch. If you can't get by with the standard implementations, prefer to derive a new Future instance with the methods in Futures or, if necessary, to extend AbstractFuture.

Occasionally, an API will return a plain Future and it will be impossible to change the return type. For this case, we provide a more expensive workaround in JdkFutureAdapters. However, when possible, it is more efficient and reliable to create a ListenableFuture directly.

Summary

Methods
public voidaddListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)

Registers a listener to be run on the given executor.

Methods

public void addListener(java.lang.Runnable listener, java.util.concurrent.Executor executor)

Registers a listener to be run on the given executor. The listener will run when the Future's computation is complete or, if the computation is already complete, immediately.

There is no guaranteed ordering of execution of listeners, but any listener added through this method is guaranteed to be called once the computation is complete.

Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown during Executor.execute (e.g., a RejectedExecutionException or an exception thrown by direct execution) will be caught and logged.

Note: For fast, lightweight listeners that would be safe to execute in any thread, consider MoreExecutors.directExecutor. Otherwise, avoid it. Heavyweight directExecutor listeners can cause problems, and these problems can be difficult to reproduce because they depend on timing. For example:

  • The listener may be executed by the caller of addListener. That caller may be a UI thread or other latency-sensitive thread. This can harm UI responsiveness.
  • The listener may be executed by the thread that completes this Future. That thread may be an internal system thread such as an RPC network thread. Blocking that thread may stall progress of the whole system. It may even cause a deadlock.
  • The listener may delay other listeners, even listeners that are not themselves directExecutor listeners.

This is the most general listener interface. For common operations performed using listeners, see Futures. For a simplified but general listener interface, see addCallback().

Memory consistency effects: Actions in a thread prior to adding a listener happen-before its execution begins, perhaps in another thread.

Guava implementations of ListenableFuture promptly release references to listeners after executing them.

Parameters:

listener: the listener to run when the computation is complete
executor: the executor to run the listener in

Source

/*
 * Copyright 2019 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.concurrent;

import androidx.annotation.NonNull;

import java.util.concurrent.Executor;
import java.util.concurrent.Future;
import java.util.concurrent.RejectedExecutionException;

/**
 * A {@link Future} that accepts completion listeners. Each listener has an associated executor, and
 * it is invoked using this executor once the future's computation is {@linkplain Future#isDone()
 * complete}. If the computation has already completed when the listener is added, the listener will
 * execute immediately.
 *
 * <p>See the Guava User Guide article on <a
 * href="https://github.com/google/guava/wiki/ListenableFutureExplained">{@code
 * ListenableFuture}</a>.
 *
 * <p>This class is GWT-compatible.
 *
 * <h3>Purpose</h3>
 *
 * <p>The main purpose of {@code ListenableFuture} is to help you chain together a graph of
 * asynchronous operations. You can chain them together manually with calls to methods like
 * {@code Futures.transform}, but you will often find it easier to use a framework. Frameworks
 * automate the process, often adding features like monitoring, debugging, and cancellation.
 * Examples of frameworks include:
 *
 * <ul>
 *   <!-- MOE:begin_intracomment_strip -->
 *   <li><a href="http://go/javaproducers">Apps Framework Producers</a> (for server apps)
 *   <!-- MOE:end_intracomment_strip -->
 *   <li><a href="http://google.github.io/dagger/producers.html">Dagger Producers</a>
 *       <!-- MOE:begin_intracomment_strip -->
 *       (for Android apps)
 *   <li><a href="http://go/async-java">...and more</a>
 *       <!-- MOE:end_intracomment_strip -->
 * </ul>
 *
 * <p>The main purpose of {@link #addListener addListener} is to support this chaining. You will
 * rarely use it directly, in part because it does not provide direct access to the {@code Future}
 * result. (If you want such access, you may prefer {@code Futures.addCallback}.)
 * Still, direct {@code addListener} calls are occasionally useful:
 *
 * <pre>{@code
 * final String name = ...;
 * inFlight.add(name);
 * ListenableFuture<Result> future = service.query(name);
 * future.addListener(new Runnable() {
 *   public void run() {
 *     processedCount.incrementAndGet();
 *     inFlight.remove(name);
 *     lastProcessed.set(name);
 *     logger.info("Done with {0}", name);
 *   }
 * }, executor);
 * }</pre>
 *
 * <h3>How to get an instance</h3>
 *
 * <p>We encourage you to return {@code ListenableFuture} from your methods so that your users can
 * take advantage of the utilities built atop the class. The way that you will
 * create {@code ListenableFuture} instances depends on how you currently create {@code Future}
 * instances:
 *
 * <ul>
 *   <li>If you receive them from an {@code java.util.concurrent.ExecutorService}, convert that
 *       service to a {@code ListeningExecutorService}, usually by calling
 *       {@code MoreExecutors.listeningDecorator}.
 *   <li>If you manually call {@code FutureTask.set} or a similar method,
 *       create a {@code SettableFuture} instead. (If your needs are more complex, you may prefer
 *       {@code AbstractFuture}.)
 * </ul>
 *
 * <p><b>Test doubles</b>: If you need a {@code ListenableFuture} for your test, try a
 * {@code SettableFuture} or one of the methods in the {@code Futures.immediate*}
 * family. <b>Avoid</b> creating a mock or stub {@code Future}. Mock and stub implementations are
 * fragile because they assume that only certain methods will be called and because they often
 * implement subtleties of the API improperly.
 *
 * <p><b>Custom implementation</b>: Avoid implementing {@code ListenableFuture} from scratch. If you
 * can't get by with the standard implementations, prefer to derive a new {@code Future} instance
 * with the methods in {@code Futures} or, if necessary, to extend {@code AbstractFuture}.
 *
 * <p>Occasionally, an API will return a plain {@code Future} and it will be impossible to change
 * the return type. For this case, we provide a more expensive workaround in {@code
 * JdkFutureAdapters}. However, when possible, it is more efficient and reliable to create a {@code
 * ListenableFuture} directly.
 *
 * @author Sven Mawson
 * @author Nishant Thakkar
 * @since 1.0
 */
public interface ListenableFuture<V> extends Future<V> {
    /**
     * Registers a listener to be {@linkplain Executor#execute(Runnable) run} on the given executor.
     * The listener will run when the {@code Future}'s computation is {@linkplain Future#isDone()
     * complete} or, if the computation is already complete, immediately.
     *
     * <p>There is no guaranteed ordering of execution of listeners, but any listener added through
     * this method is guaranteed to be called once the computation is complete.
     *
     * <p>Exceptions thrown by a listener will be propagated up to the executor. Any exception thrown
     * during {@code Executor.execute} (e.g., a {@code RejectedExecutionException} or an exception
     * thrown by direct execution) will be caught and
     * logged.
     *
     * <p>Note: For fast, lightweight listeners that would be safe to execute in any thread, consider
     * {@code MoreExecutors.directExecutor}. Otherwise, avoid it. Heavyweight {@code directExecutor}
     * listeners can cause problems, and these problems can be difficult to reproduce because they
     * depend on timing. For example:
     *
     * <ul>
     *   <li>The listener may be executed by the caller of {@code addListener}. That caller may be a
     *       UI thread or other latency-sensitive thread. This can harm UI responsiveness.
     *   <li>The listener may be executed by the thread that completes this {@code Future}. That
     *       thread may be an internal system thread such as an RPC network thread. Blocking that
     *       thread may stall progress of the whole system. It may even cause a deadlock.
     *   <li>The listener may delay other listeners, even listeners that are not themselves {@code
     *       directExecutor} listeners.
     * </ul>
     *
     * <p>This is the most general listener interface. For common operations performed using
     * listeners, see {@code Futures}. For a simplified but general listener interface, see {@code
     * addCallback()}.
     *
     * <p>Memory consistency effects: Actions in a thread prior to adding a listener <a
     * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-17.html#jls-17.4.5">
     * <i>happen-before</i></a> its execution begins, perhaps in another thread.
     *
     * <p>Guava implementations of {@code ListenableFuture} promptly release references to listeners
     * after executing them.
     *
     * @param listener the listener to run when the computation is complete
     * @param executor the executor to run the listener in
     * @throws java.util.concurrent.RejectedExecutionException if we tried to execute the listener
     *     immediately but the executor rejected it.
     */
    void addListener(@NonNull Runnable listener, @NonNull Executor executor);
}