COMMAND git -C /tmp/java-baseline-guava-3350 rev-parse HEAD
8868c096cfdabbe38170b6e395369c315cfb72a1

READ /tmp/java-baseline-guava-3350/guava/src/com/google/common/util/concurrent/AbstractTransformFuture.java
/*
 * Copyright (C) 2006 The Guava Authors
 *
 * 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 com.google.common.util.concurrent;

import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.util.concurrent.Futures.getDone;
import static com.google.common.util.concurrent.MoreExecutors.rejectionPropagatingExecutor;
import static com.google.common.util.concurrent.Platform.restoreInterruptIfIsInterruptedException;

import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Function;
import com.google.errorprone.annotations.ForOverride;
import com.google.errorprone.annotations.concurrent.LazyInit;
import com.google.j2objc.annotations.RetainedLocalRef;
import java.util.concurrent.CancellationException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executor;
import org.jspecify.annotations.Nullable;

/** Implementations of {@code Futures.transform*}. */
@GwtCompatible
// Whenever both tests are cheap and functional, it's faster to use &, | instead of &&, ||
@SuppressWarnings("ShortCircuitBoolean")
abstract class AbstractTransformFuture<
        I extends @Nullable Object, O extends @Nullable Object, F, T extends @Nullable Object>
    extends FluentFuture.TrustedFuture<O> implements Runnable {
  static <I extends @Nullable Object, O extends @Nullable Object> ListenableFuture<O> createAsync(
      ListenableFuture<I> input,
      AsyncFunction<? super I, ? extends O> function,
      Executor executor) {
    AsyncTransformFuture<I, O> output = new AsyncTransformFuture<>(input, function);
    input.addListener(output, rejectionPropagatingExecutor(executor, output));
    return output;
  }

  static <I extends @Nullable Object, O extends @Nullable Object> ListenableFuture<O> create(
      ListenableFuture<I> input, Function<? super I, ? extends O> function, Executor executor) {
    TransformFuture<I, O> output = new TransformFuture<>(input, function);
    input.addListener(output, rejectionPropagatingExecutor(executor, output));
    return output;
  }

  /*
   * In certain circumstances, this field might theoretically not be visible to an afterDone() call
   * triggered by cancel(). For details, see the comments on the fields of TimeoutFuture.
   */
  @LazyInit @Nullable ListenableFuture<? extends I> inputFuture;
  @LazyInit @Nullable F function;

  AbstractTransformFuture(ListenableFuture<? extends I> inputFuture, F function) {
    this.inputFuture = checkNotNull(inputFuture);
    this.function = checkNotNull(function);
  }

  @Override
  @SuppressWarnings({
    "CatchingUnchecked", // sneaky checked exception
    "nullness", // TODO(b/147136275): Remove once our checker understands & and |.
  })
  public final void run() {
    @RetainedLocalRef ListenableFuture<? extends I> localInputFuture = inputFuture;
    @RetainedLocalRef F localFunction = function;
    if (isCancelled() | localInputFuture == null | localFunction == null) {
      return;
    }
    inputFuture = null;

    if (localInputFuture.isCancelled()) {
      @SuppressWarnings("unchecked")
      boolean unused =
          setFuture((ListenableFuture<O>) localInputFuture); // Respects cancellation cause setting
      return;
    }

    /*
     * Any of the setException() calls below can fail if the output Future is cancelled between now
     * and then. This means that we're silently swallowing an exception -- maybe even an Error. But
     * this is no worse than what FutureTask does in that situation. Additionally, because the
     * Future was cancelled, its listeners have been run, so its consumers will not hang.
     *
     * Contrast this to the situation we have if setResult() throws, a situation described below.
     */
    I sourceResult;
    try {
      sourceResult = getDone(localInputFuture);
    } catch (CancellationException e) {
      // TODO(user): verify future behavior - unify logic with getFutureValue in AbstractFuture. This
      // code should be unreachable with correctly implemented Futures.
      // Cancel this future and return.
      // At this point, inputFuture is cancelled and outputFuture doesn't exist, so the value of
      // mayInterruptIfRunning is irrelevant.
      cancel(false);
      return;
    } catch (ExecutionException e) {
      // Set the cause of the exception as this future's exception.
      setException(e.getCause());
      return;
    } catch (Exception e) { // sneaky checked exception
      // Bug in inputFuture.get(). Propagate to the output Future so that its consumers don't hang.
      setException(e);
      return;
    } catch (Error e) {
      /*
       * StackOverflowError, OutOfMemoryError (e.g., from allocating ExecutionException), or
       * something. Try to treat it like a RuntimeException. If we overflow the stack again, the
       * resulting Error will propagate upward up to the root call to set().
       */
      setException(e);
      return;
    }

    T transformResult;
    try {
      transformResult = doTransform(localFunction, sourceResult);
    } catch (Throwable t) {
      restoreInterruptIfIsInterruptedException(t);
      // This exception is irrelevant in this thread, but useful for the client.
      setException(t);
      return;
    } finally {
      function = null;
    }

    /*
     * If set()/setValue() throws an Error, we let it propagate. Why? The most likely Error is a
     * StackOverflowError (from deep transform(..., directExecutor()) nesting), and calling
     * setException(stackOverflowError) would fail:
     *
     * - If the stack overflowed before set()/setValue() could even store the result in the output
     * Future, then a call setException() would likely also overflow.
     *
     * - If the stack overflowed after set()/setValue() stored its result, then a call to
     * setException() will be a no-op because the Future is already done.
     *
     * Both scenarios are bad: The output Future might never complete, or, if it does complete, it
     * might not run some of its listeners. The likely result is that the app will hang. (And of
     * course stack overflows are bad news in general. For example, we may have overflowed in the
     * middle of defining a class. If so, that class will never be loadable in this process.) The
     * best we can do (since logging may overflow the stack) is to let the error propagate. Because
     * it is an Error, it won't be caught and logged by AbstractFuture.executeListener. Instead, it
     * can propagate through many layers of AbstractTransformFuture up to the root call to set().
     *
     * https://github.com/google/guava/issues/2254
     *
     * Other kinds of Errors are possible:
     *
     * - OutOfMemoryError from allocations in setFuture(): The calculus here is similar to
     * StackOverflowError: We can't reliably call setException(error).
     *
     * - Any kind of Error from a listener. Even if we could distinguish that case (by exposing some
     * extra state from AbstractFuture), our options are limited: A call to setException() would be
     * a no-op. We could log, but if that's what we really want, we should modify
     * AbstractFuture.executeListener to do so, since that method would have the ability to continue
     * to execute other listeners.
     *
     * What about RuntimeException? If there is a bug in set()/setValue() that produces one, it will
     * propagate, too, but only as far as AbstractFuture.executeListener, which will catch and log
     * it.
     */
    setResult(transformResult);
  }

  /** Template method for subtypes to actually run the transform. */
  @ForOverride
  @ParametricNullness
  abstract T doTransform(F function, @ParametricNullness I result) throws Exception;

  /** Template method for subtypes to actually set the result. */
  @ForOverride
  abstract void setResult(@ParametricNullness T result);

  @Override
  protected final void afterDone() {
    @RetainedLocalRef ListenableFuture<? extends I> localInputFuture = inputFuture;
    maybePropagateCancellationTo(localInputFuture);
    this.inputFuture = null;
    this.function = null;
  }

  @Override
  protected @Nullable String pendingToString() {
    @RetainedLocalRef ListenableFuture<? extends I> localInputFuture = inputFuture;
    @RetainedLocalRef F localFunction = function;
    String superString = super.pendingToString();
    String resultString = "";
    if (localInputFuture != null) {
      resultString = "inputFuture=[" + localInputFuture + "], ";
    }
    if (localFunction != null) {
      return resultString + "function=[" + localFunction + "]";
    } else if (superString != null) {
      return resultString + superString;
    }
    return null;
  }

  /**
   * An {@link AbstractTransformFuture} that delegates to an {@link AsyncFunction} and {@link
   * #setFuture(ListenableFuture)}.
   */
  private static final class AsyncTransformFuture<
          I extends @Nullable Object, O extends @Nullable Object>
      extends AbstractTransformFuture<
          I, O, AsyncFunction<? super I, ? extends O>, ListenableFuture<? extends O>> {
    AsyncTransformFuture(
        ListenableFuture<? extends I> inputFuture, AsyncFunction<? super I, ? extends O> function) {
      super(inputFuture, function);
    }

    @Override
    ListenableFuture<? extends O> doTransform(
        AsyncFunction<? super I, ? extends O> function, @ParametricNullness I input)
        throws Exception {
      ListenableFuture<? extends O> output = function.apply(input);
      checkNotNull(
          output,
          "AsyncFunction.apply returned null instead of a Future. "
              + "Did you mean to return immediateFuture(null)? %s",
          function);
      return output;
    }

    @Override
    void setResult(ListenableFuture<? extends O> result) {
      setFuture(result);
    }
  }

  /**
   * An {@link AbstractTransformFuture} that delegates to a {@link Function} and {@link
   * #set(Object)}.
   */
  private static final class TransformFuture<I extends @Nullable Object, O extends @Nullable Object>
      extends AbstractTransformFuture<I, O, Function<? super I, ? extends O>, O> {
    TransformFuture(
        ListenableFuture<? extends I> inputFuture, Function<? super I, ? extends O> function) {
      super(inputFuture, function);
    }

    @Override
    @ParametricNullness
    O doTransform(Function<? super I, ? extends O> function, @ParametricNullness I input) {
      return function.apply(input);
    }

    @Override
    void setResult(@ParametricNullness O result) {
      set(result);
    }
  }
}

READ /tmp/java-baseline-guava-3350/guava/src/com/google/common/util/concurrent/AbstractFuture.java
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * 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 com.google.common.util.concurrent;

import static com.google.common.base.Preconditions.checkNotNull;
import static com.google.common.util.concurrent.NullnessCasts.uncheckedNull;
import static com.google.common.util.concurrent.Platform.interruptCurrentThread;
import static com.google.common.util.concurrent.Platform.rethrowIfErrorOtherThanStackOverflow;
import static java.lang.Integer.toHexString;
import static java.lang.System.identityHashCode;
import static java.util.Objects.requireNonNull;
import static java.util.concurrent.TimeUnit.MILLISECONDS;
import static java.util.logging.Level.SEVERE;

import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Strings;
import com.google.common.util.concurrent.internal.InternalFutureFailureAccess;
import com.google.common.util.concurrent.internal.InternalFutures;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import com.google.errorprone.annotations.ForOverride;
import com.google.j2objc.annotations.ReflectionSupport;
import com.google.j2objc.annotations.RetainedLocalRef;
import java.util.concurrent.CancellationException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.Executor;
import java.util.concurrent.Future;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
import org.jspecify.annotations.Nullable;

/**
 * An abstract implementation of {@link ListenableFuture}, intended for advanced users only. More
 * common ways to create a {@code ListenableFuture} include instantiating a {@link SettableFuture},
 * submitting a task to a {@link ListeningExecutorService}, and deriving a {@code Future} from an
 * existing one, typically using methods like {@link Futures#transform(ListenableFuture,
 * com.google.common.base.Function, java.util.concurrent.Executor) Futures.transform} and {@link
 * Futures#catching(ListenableFuture, Class, com.google.common.base.Function,
 * java.util.concurrent.Executor) Futures.catching}.
 *
 * <p>This class implements all methods in {@code ListenableFuture}. Subclasses should provide a way
 * to set the result of the computation through the protected methods {@link #set(Object)}, {@link
 * #setFuture(ListenableFuture)} and {@link #setException(Throwable)}. Subclasses may also override
 * {@link #afterDone()}, which will be invoked automatically when the future completes. Subclasses
 * should rarely override other methods.
 *
 * @author Sven Mawson
 * @author Luke Sandberg
 * @since 1.0
 */
// Whenever both tests are cheap and functional, it's faster to use &, | instead of &&, ||
@SuppressWarnings("ShortCircuitBoolean")
@GwtCompatible
/*
 * TODO(cpovirk): Do we still need @ReflectionSupport on *this* class now that the fields live in
 * the superclass? Note that Listener (which we also reflect on) still lives here.
 */
@ReflectionSupport(value = ReflectionSupport.Level.FULL)
public abstract class AbstractFuture<V extends @Nullable Object> extends AbstractFutureState<V> {
  /*
   * All static initialization should be performed in AbstractFutureState: AbstractFutureState's
   * initialization may trigger logging, which may assume that AbstractFuture is initialized.
   *
   * TODO(cpovirk): Write a test that asserts that AbstractFuture has no clinit?
   */

  /**
   * Tag interface marking trusted subclasses. This enables some optimizations. The implementation
   * of this interface must also be an AbstractFuture and must not override or expose for overriding
   * any of the public methods of ListenableFuture.
   */
  interface Trusted<V extends @Nullable Object> extends ListenableFuture<V> {}

  /**
   * A less abstract subclass of AbstractFuture. This can be used to optimize setFuture by ensuring
   * that {@link #get} calls exactly the implementation of {@link AbstractFuture#get}.
   */
  abstract static class TrustedFuture<V extends @Nullable Object> extends AbstractFuture<V>
      implements Trusted<V> {
    @CanIgnoreReturnValue
    @Override
    @ParametricNullness
    public final V get() throws InterruptedException, ExecutionException {
      return super.get();
    }

    @CanIgnoreReturnValue
    @Override
    @ParametricNullness
    public final V get(long timeout, TimeUnit unit)
        throws InterruptedException, ExecutionException, TimeoutException {
      return super.get(timeout, unit);
    }

    @Override
    public final boolean isDone() {
      return super.isDone();
    }

    @Override
    public final boolean isCancelled() {
      return super.isCancelled();
    }

    @Override
    public final void addListener(Runnable listener, Executor executor) {
      super.addListener(listener, executor);
    }

    @CanIgnoreReturnValue
    @Override
    public final boolean cancel(boolean mayInterruptIfRunning) {
      return super.cancel(mayInterruptIfRunning);
    }
  }

  /** Listeners form a Treiber stack through the {@link #listeners} field. */
  static final class Listener {
    static final Listener TOMBSTONE = new Listener();
    // null only for TOMBSTONE
    final @Nullable Runnable task;
    // null only for TOMBSTONE
    final @Nullable Executor executor;

    // writes to next are made visible by subsequent CAS's on the listeners field
    @Nullable Listener next;

    Listener(Runnable task, Executor executor) {
      this.task = task;
      this.executor = executor;
    }

    Listener() {
      this.task = null;
      this.executor = null;
    }
  }

  /** A special value to represent failure, when {@link #setException} is called successfully. */
  private static final class Failure {
    static final Failure FALLBACK_INSTANCE =
        new Failure(
            new Throwable("Failure occurred while trying to finish a future.") {
              @Override
              public Throwable fillInStackTrace() {
                return this; // no stack trace
              }
            });
    final Throwable exception;

    Failure(Throwable exception) {
      this.exception = checkNotNull(exception);
    }
  }

  /** A special value to represent cancellation and the 'wasInterrupted' bit. */
  private static final class Cancellation {
    // constants to use when GENERATE_CANCELLATION_CAUSES = false
    static final @Nullable Cancellation CAUSELESS_INTERRUPTED;
    static final @Nullable Cancellation CAUSELESS_CANCELLED;

    static {
      if (GENERATE_CANCELLATION_CAUSES) {
        CAUSELESS_CANCELLED = null;
        CAUSELESS_INTERRUPTED = null;
      } else {
        CAUSELESS_CANCELLED = new Cancellation(false, null);
        CAUSELESS_INTERRUPTED = new Cancellation(true, null);
      }
    }

    final boolean wasInterrupted;
    final @Nullable Throwable cause;

    Cancellation(boolean wasInterrupted, @Nullable Throwable cause) {
      this.wasInterrupted = wasInterrupted;
      this.cause = cause;
    }
  }

  /** A special value that encodes the 'setFuture' state. */
  private static final class DelegatingToFuture<V extends @Nullable Object> implements Runnable {
    final AbstractFuture<V> owner;
    final ListenableFuture<? extends V> future;

    DelegatingToFuture(AbstractFuture<V> owner, ListenableFuture<? extends V> future) {
      this.owner = owner;
      this.future = future;
    }

    @Override
    public void run() {
      if (owner.value() != this) {
        // nothing to do, we must have been cancelled, don't bother inspecting the future.
        return;
      }
      Object valueToSet = getFutureValue(future);
      if (casValue(owner, this, valueToSet)) {
        complete(
            owner,
            /*
             * Interruption doesn't propagate through a DelegatingToFuture chain (see
             * getFutureValue), so don't invoke interruptTask.
             */
            false);
      }
    }
  }

  /** Constructor for use by subclasses. */
  protected AbstractFuture() {}

  /**
   * {@inheritDoc}
   *
   * <p>The default {@link AbstractFuture} implementation throws {@code InterruptedException} if the
   * current thread is interrupted during the call, even if the value is already available.
   *
   * @throws CancellationException {@inheritDoc}
   */
  @CanIgnoreReturnValue
  @Override
  @ParametricNullness
  public V get(long timeout, TimeUnit unit)
      throws InterruptedException, TimeoutException, ExecutionException {
    return Platform.get(this, timeout, unit);
  }

  /**
   * {@inheritDoc}
   *
   * <p>The default {@link AbstractFuture} implementation throws {@code InterruptedException} if the
   * current thread is interrupted during the call, even if the value is already available.
   *
   * @throws CancellationException {@inheritDoc}
   */
  @CanIgnoreReturnValue
  @Override
  @ParametricNullness
  public V get() throws InterruptedException, ExecutionException {
    return Platform.get(this);
  }

  /**
   * Returns the result of this future or throws in case of failure, just like {@link #get()} except
   * that this method <i>also</i> throws if this future is not done.
   *
   * <p>This method computes its result based on the internal state of {@link AbstractFuture}, so it
   * does not necessarily return the same result as {@link #get()} if {@link #get()} has been
   * overridden. Thus, it should be called only on instances of {@link Trusted} or from within
   * {@link #get()} itself.
   */
  @ParametricNullness
  @SuppressWarnings("nullness") // TODO(b/147136275): Remove once our checker understands & and |.
  /*
   * TODO: b/112550045 - Use this from Futures.getDone when applicable? Note the small difference in
   * failure message between the two at present.
   */
  final V getFromAlreadyDoneTrustedFuture() throws ExecutionException {
    @RetainedLocalRef Object localValue = value();
    if (localValue == null | localValue instanceof DelegatingToFuture) {
      throw new IllegalStateException("Cannot get() on a pending future.");
    }
    return getDoneValue(localValue);
  }

  /** Unboxes {@code obj}. Assumes that obj is not {@code null} or a {@link DelegatingToFuture}. */
  @ParametricNullness
  @SuppressWarnings("TypeParameterUnusedInFormals") // sorry not sorry
  static <V extends @Nullable Object> V getDoneValue(Object obj) throws ExecutionException {
    // While this seems like it might be too branch-y, simple benchmarking proves it to be
    // unmeasurable (comparing done AbstractFutures with immediateFuture)
    if (obj instanceof Cancellation) {
      Cancellation cancellation = (Cancellation) obj;
      Throwable cause = cancellation.cause;
      throw cancellationExceptionWithCause("Task was cancelled.", cause);
    } else if (obj instanceof Failure) {
      Failure failure = (Failure) obj;
      Throwable exception = failure.exception;
      throw new ExecutionException(exception);
    } else if (obj == NULL) {
      /*
       * It's safe to return null because we would only have stored it in the first place if it were
       * a valid value for V.
       */
      return uncheckedNull();
    } else {
      @SuppressWarnings("unchecked") // this is the only other option
      V asV = (V) obj;
      return asV;
    }
  }

  /** Returns whether {@code obj} is <b>not</b> an instance of {@code DelegatingToFuture}. */
  // This method lets us:
  // - avoid exposing DelegatingToFuture to the whole package
  // - avoid fighting with the relative operator precedence of `instanceof` and `!`
  static boolean notInstanceOfDelegatingToFuture(@Nullable Object obj) {
    return !(obj instanceof DelegatingToFuture);
  }

  @Override
  public boolean isDone() {
    @RetainedLocalRef Object localValue = value();
    return localValue != null & notInstanceOfDelegatingToFuture(localValue);
  }

  @Override
  public boolean isCancelled() {
    @RetainedLocalRef Object localValue = value();
    return localValue instanceof Cancellation;
  }

  /**
   * {@inheritDoc}
   *
   * <p>If a cancellation attempt succeeds on a {@code Future} that had previously been {@linkplain
   * #setFuture set asynchronously}, then the cancellation will also be propagated to the delegate
   * {@code Future} that was supplied in the {@code setFuture} call.
   *
   * <p>Rather than override this method to perform additional cancellation work or cleanup,
   * subclasses should override {@link #afterDone}, consulting {@link #isCancelled} and {@link
   * #wasInterrupted} as necessary. This ensures that the work is done even if the future is
   * cancelled without a call to {@code cancel}, such as by calling {@code
   * setFuture(cancelledFuture)}.
   *
   * <p>Beware of completing a future while holding a lock. Its listeners may do slow work or
   * acquire other locks, risking deadlocks.
   */
  @CanIgnoreReturnValue
  @Override
  public boolean cancel(boolean mayInterruptIfRunning) {
    @RetainedLocalRef Object localValue = value();
    boolean rValue = false;
    if (localValue == null | localValue instanceof DelegatingToFuture) {
      // Try to delay allocating the exception. At this point we may still lose the CAS, but it is
      // certainly less likely.
      Object valueToSet =
          GENERATE_CANCELLATION_CAUSES
              ? new Cancellation(
                  mayInterruptIfRunning, new CancellationException("Future.cancel() was called."))
              /*
               * requireNonNull is safe because we've initialized these if
               * !GENERATE_CANCELLATION_CAUSES.
               *
               * TODO(cpovirk): Maybe it would be cleaner to define a CancellationSupplier interface
               * with two implementations, one that contains causeless Cancellation instances and
               * the other of which creates new Cancellation instances each time it's called? Yet
               * another alternative is to fill in a non-null value for each of the fields no matter
               * what and to just not use it if !GENERATE_CANCELLATION_CAUSES.
               */
              : requireNonNull(
                  mayInterruptIfRunning
                      ? Cancellation.CAUSELESS_INTERRUPTED
                      : Cancellation.CAUSELESS_CANCELLED);
      AbstractFuture<?> abstractFuture = this;
      while (true) {
        if (casValue(abstractFuture, localValue, valueToSet)) {
          rValue = true;
          complete(abstractFuture, mayInterruptIfRunning);
          if (localValue instanceof DelegatingToFuture) {
            // propagate cancellation to the future set in setfuture, this is racy, and we don't
            // care if we are successful or not.
            ListenableFuture<?> futureToPropagateTo = ((DelegatingToFuture) localValue).future;
            if (futureToPropagateTo instanceof Trusted) {
              // If the future is a Trusted instance then we specifically avoid calling cancel()
              // this has 2 benefits
              // 1. for long chains of futures strung together with setFuture we consume less stack
              // 2. we avoid allocating Cancellation objects at every level of the cancellation
              //    chain
              // We can only do this for Trusted, because Trusted implementations of cancel do
              // nothing but delegate to this method and do not permit user overrides.
              AbstractFuture<?> trusted = (AbstractFuture<?>) futureToPropagateTo;
              localValue = trusted.value();
              if (localValue == null | localValue instanceof DelegatingToFuture) {
                abstractFuture = trusted;
                continue; // loop back up and try to complete the new future
              }
            } else {
              // not a Trusted instance, call cancel directly.
              futureToPropagateTo.cancel(mayInterruptIfRunning);
            }
          }
          break;
        }
        // obj changed, reread
        localValue = abstractFuture.value();
        if (notInstanceOfDelegatingToFuture(localValue)) {
          // obj cannot be null at this point, because value can only change from null to non-null.
          // So if value changed (and it did since we lost the CAS), then it cannot be null and
          // since it isn't a DelegatingToFuture, then the future must be done and we should exit
          // the loop
          break;
        }
      }
    }
    return rValue;
  }

  /**
   * Subclasses can override this method to implement interruption of the future's computation. The
   * method is invoked automatically by a successful call to {@link #cancel(boolean) cancel(true)}.
   *
   * <p>The default implementation does nothing.
   *
   * <p>This method is likely to be deprecated. Prefer to override {@link #afterDone}, checking
   * {@link #wasInterrupted} to decide whether to interrupt your task.
   *
   * @since 10.0
   */
  protected void interruptTask() {}

  /**
   * Returns true if this future was cancelled with {@code mayInterruptIfRunning} set to {@code
   * true}.
   *
   * @since 14.0
   */
  protected final boolean wasInterrupted() {
    @RetainedLocalRef Object localValue = value();
    return (localValue instanceof Cancellation) && ((Cancellation) localValue).wasInterrupted;
  }

  /**
   * {@inheritDoc}
   *
   * @since 10.0
   */
  @Override
  public void addListener(Runnable listener, Executor executor) {
    checkNotNull(listener, "Runnable was null.");
    checkNotNull(executor, "Executor was null.");
    // Checking isDone and listeners != TOMBSTONE may seem redundant, but our contract for
    // addListener says that listeners execute 'immediate' if the future isDone(). However, our
    // protocol for completing a future is to assign the value field (which sets isDone to true) and
    // then to release waiters, followed by executing afterDone(), followed by releasing listeners.
    // That means that it is possible to observe that the future isDone and that your listeners
    // don't execute 'immediately'.  By checking isDone here we avoid that.
    // A corollary to all that is that we don't need to check isDone inside the loop because if we
    // get into the loop we know that we weren't done when we entered and therefore we aren't under
    // an obligation to execute 'immediately'.
    if (!isDone()) {
      Listener oldHead = listeners();
      if (oldHead != Listener.TOMBSTONE) {
        Listener newNode = new Listener(listener, executor);
        do {
          newNode.next = oldHead;
          if (casListeners(oldHead, newNode)) {
            return;
          }
          oldHead = listeners(); // re-read
        } while (oldHead != Listener.TOMBSTONE);
      }
    }
    // If we get here then the Listener TOMBSTONE was set, which means the future is done, call
    // the listener.
    executeListener(listener, executor);
  }

  /**
   * Sets the result of this {@code Future} unless this {@code Future} has already been cancelled or
   * set (including {@linkplain #setFuture set asynchronously}). When a call to this method returns,
   * the {@code Future} is guaranteed to be {@linkplain #isDone done} <b>only if</b> the call was
   * accepted (in which case it returns {@code true}). If it returns {@code false}, the {@code
   * Future} may have previously been set asynchronously, in which case its result may not be known
   * yet. That result, though not yet known, cannot be overridden by a call to a {@code set*}
   * method, only by a call to {@link #cancel}.
   *
   * <p>Beware of completing a future while holding a lock. Its listeners may do slow work or
   * acquire other locks, risking deadlocks.
   *
   * @param value the value to be used as the result
   * @return true if the attempt was accepted, completing the {@code Future}
   */
  @CanIgnoreReturnValue
  protected boolean set(@ParametricNullness V value) {
    Object valueToSet = value == null ? NULL : value;
    if (casValue(this, null, valueToSet)) {
      complete(this, /* callInterruptTask= */ false);
      return true;
    }
    return false;
  }

  /**
   * Sets the failed result of this {@code Future} unless this {@code Future} has already been
   * cancelled or set (including {@linkplain #setFuture set asynchronously}). When a call to this
   * method returns, the {@code Future} is guaranteed to be {@linkplain #isDone done} <b>only if</b>
   * the call was accepted (in which case it returns {@code true}). If it returns {@code false}, the
   * {@code Future} may have previously been set asynchronously, in which case its result may not be
   * known yet. That result, though not yet known, cannot be overridden by a call to a {@code set*}
   * method, only by a call to {@link #cancel}.
   *
   * <p>Beware of completing a future while holding a lock. Its listeners may do slow work or
   * acquire other locks, risking deadlocks.
   *
   * @param throwable the exception to be used as the failed result
   * @return true if the attempt was accepted, completing the {@code Future}
   */
  @CanIgnoreReturnValue
  protected boolean setException(Throwable throwable) {
    Object valueToSet = new Failure(checkNotNull(throwable));
    if (casValue(this, null, valueToSet)) {
      complete(this, /* callInterruptTask= */ false);
      return true;
    }
    return false;
  }

  /**
   * Sets the result of this {@code Future} to match the supplied input {@code Future} once the
   * supplied {@code Future} is done, unless this {@code Future} has already been cancelled or set
   * (including "set asynchronously," defined below).
   *
   * <p>If the supplied future is {@linkplain #isDone done} when this method is called and the call
   * is accepted, then this future is guaranteed to have been completed with the supplied future by
   * the time this method returns. If the supplied future is not done and the call is accepted, then
   * the future will be <i>set asynchronously</i>. Note that such a result, though not yet known,
   * cannot be overridden by a call to a {@code set*} method, only by a call to {@link #cancel}.
   *
   * <p>If the call {@code setFuture(delegate)} is accepted and this {@code Future} is later
   * cancelled, cancellation will be propagated to {@code delegate}. Additionally, any call to
   * {@code setFuture} after any cancellation will propagate cancellation to the supplied {@code
   * Future}.
   *
   * <p>Note that, even if the supplied future is cancelled and it causes this future to complete,
   * it will never trigger interruption behavior. In particular, it will not cause this future to
   * invoke the {@link #interruptTask} method, and the {@link #wasInterrupted} method will not
   * return {@code true}.
   *
   * <p>Beware of completing a future while holding a lock. Its listeners may do slow work or
   * acquire other locks, risking deadlocks.
   *
   * @param future the future to delegate to
   * @return true if the attempt was accepted, indicating that the {@code Future} was not previously
   *     cancelled or set.
   * @since 19.0
   */
  @CanIgnoreReturnValue
  @SuppressWarnings("Interruption") // We are propagating an interrupt from a caller.
  protected boolean setFuture(ListenableFuture<? extends V> future) {
    checkNotNull(future);
    @RetainedLocalRef Object localValue = value();
    if (localValue == null) {
      if (future.isDone()) {
        Object value = getFutureValue(future);
        if (casValue(this, null, value)) {
          complete(
              this,
              /*
               * Interruption doesn't propagate through a DelegatingToFuture chain (see
               * getFutureValue), so don't invoke interruptTask.
               */
              false);
          return true;
        }
        return false;
      }
      DelegatingToFuture<V> valueToSet = new DelegatingToFuture<>(this, future);
      if (casValue(this, null, valueToSet)) {
        // the listener is responsible for calling completeWithFuture, directExecutor is appropriate
        // since all we are doing is unpacking a completed future which should be fast.
        try {
          future.addListener(valueToSet, DirectExecutor.INSTANCE);
        } catch (Throwable t) {
          // Any Exception is either a RuntimeException or sneaky checked exception.
          //
          // addListener has thrown an exception! DelegatingToFuture.run can't throw any exceptions
          // so this must have been caused by addListener itself. The most likely explanation is a
          // misconfigured mock. Try to switch to Failure.
          Failure failure;
          try {
            failure = new Failure(t);
          } catch (Exception | Error oomMostLikely) { // sneaky checked exception
            failure = Failure.FALLBACK_INSTANCE;
          }
          // Note: The only way this CAS could fail is if cancel() has raced with us. That is ok.
          boolean unused = casValue(this, valueToSet, failure);
        }
        return true;
      }
      localValue = value(); // we lost the cas, fall through and maybe cancel
    }
    // The future has already been set to something. If it is cancellation we should cancel the
    // incoming future.
    if (localValue instanceof Cancellation) {
      // we don't care if it fails, this is best-effort.
      future.cancel(((Cancellation) localValue).wasInterrupted);
    }
    return false;
  }

  /**
   * Returns a value that satisfies the contract of the {@link #value} field based on the state of
   * given future.
   *
   * <p>This is approximately the inverse of {@link #getDoneValue(Object)}
   */
  private static Object getFutureValue(ListenableFuture<?> future) {
    if (future instanceof Trusted) {
      // Break encapsulation for Trusted instances since we know that subclasses cannot override
      // .get() and therefore this is equivalent to calling .get() and unpacking the exceptions like
      // we do below (just much faster because it is a single field read instead of a read, several
      // branches and possibly creating exceptions).
      Object v = ((AbstractFuture<?>) future).value();
      if (v instanceof Cancellation) {
        // If the other future was interrupted, clear the interrupted bit while preserving the cause
        // this will make it consistent with how non-trustedfutures work which cannot propagate the
        // wasInterrupted bit
        Cancellation c = (Cancellation) v;
        if (c.wasInterrupted) {
          v =
              c.cause != null
                  ? new Cancellation(/* wasInterrupted= */ false, c.cause)
                  : Cancellation.CAUSELESS_CANCELLED;
        }
      }
      // requireNonNull is safe as long as we call this method only on completed futures.
      return requireNonNull(v);
    }
    if (future instanceof InternalFutureFailureAccess) {
      Throwable throwable =
          InternalFutures.tryInternalFastPathGetFailure((InternalFutureFailureAccess) future);
      if (throwable != null) {
        return new Failure(throwable);
      }
    }
    boolean wasCancelled = future.isCancelled();
    // Don't allocate a CancellationException if it's not necessary
    if (!GENERATE_CANCELLATION_CAUSES & wasCancelled) {
      /*
       * requireNonNull is safe because we've initialized CAUSELESS_CANCELLED if
       * !GENERATE_CANCELLATION_CAUSES.
       */
      return requireNonNull(Cancellation.CAUSELESS_CANCELLED);
    }
    // Otherwise calculate the value by calling .get()
    try {
      Object v = getUninterruptibly(future);
      if (wasCancelled) {
        return new Cancellation(
            false,
            new IllegalArgumentException(
                "get() did not throw CancellationException, despite reporting "
                    + "isCancelled() == true: "
                    + future));
      }
      return v == null ? NULL : v;
    } catch (ExecutionException exception) {
      if (wasCancelled) {
        return new Cancellation(
            false,
            new IllegalArgumentException(
                "get() did not throw CancellationException, despite reporting "
                    + "isCancelled() == true: "
                    + future,
                exception));
      }
      return new Failure(exception.getCause());
    } catch (CancellationException cancellation) {
      if (!wasCancelled) {
        return new Failure(
            new IllegalArgumentException(
                "get() threw CancellationException, despite reporting isCancelled() == false: "
                    + future,
                cancellation));
      }
      return new Cancellation(false, cancellation);
    } catch (Exception | Error t) { // sneaky checked exception
      return new Failure(t);
    }
  }

  /**
   * An inlined private copy of {@link Uninterruptibles#getUninterruptibly} used to break an
   * internal dependency on other /util/concurrent classes.
   */
  @ParametricNullness
  private static <V extends @Nullable Object> V getUninterruptibly(Future<V> future)
      throws ExecutionException {
    boolean interrupted = false;
    try {
      while (true) {
        try {
          return future.get();
        } catch (InterruptedException e) {
          interrupted = true;
        }
      }
    } finally {
      if (interrupted) {
        interruptCurrentThread();
      }
    }
  }

  /** Unblocks all threads and runs all listeners. */
  private static void complete(AbstractFuture<?> param, boolean callInterruptTask) {
    // Declare a "true" local variable so that the Checker Framework will infer nullness.
    @RetainedLocalRef AbstractFuture<?> future = param;

    @RetainedLocalRef Listener next = null;
    outer:
    while (true) {
      future.releaseWaiters();
      /*
       * We call interruptTask() immediately before afterDone() so that migrating between the two
       * can be a no-op.
       */
      if (callInterruptTask) {
        future.interruptTask();
        /*
         * Interruption doesn't propagate through a DelegatingToFuture chain (see getFutureValue),
         * so don't invoke interruptTask on any subsequent futures.
         */
        callInterruptTask = false;
      }
      // We call this before the listeners in order to avoid needing to manage a separate stack data
      // structure for them.  Also, some implementations rely on this running prior to listeners
      // so that the cleanup work is visible to listeners.
      // afterDone() should be generally fast and only used for cleanup work... but in theory can
      // also be recursive and create StackOverflowErrors
      future.afterDone();
      // push the current set of listeners onto next
      next = future.clearListeners(next);
      future = null;
      while (next != null) {
        @RetainedLocalRef Listener curr = next;
        next = next.next;
        /*
         * requireNonNull is safe because the listener stack never contains TOMBSTONE until after
         * clearListeners.
         */
        Runnable task = requireNonNull(curr.task);
        if (task instanceof DelegatingToFuture) {
          DelegatingToFuture<?> setFuture = (DelegatingToFuture<?>) task;
          // We unwind setFuture specifically to avoid StackOverflowErrors in the case of long
          // chains of DelegatingToFutures
          // Handling this special case is important because there is no way to pass an executor to
          // setFuture, so a user couldn't break the chain by doing this themselves.  It is also
          // potentially common if someone writes a recursive Futures.transformAsync transformer.
          future = setFuture.owner;
          if (future.value() == setFuture) {
            Object valueToSet = getFutureValue(setFuture.future);
            if (casValue(future, setFuture, valueToSet)) {
              continue outer;
            }
          }
          // otherwise the future we were trying to set is already done.
        } else {
          /*
           * requireNonNull is safe because the listener stack never contains TOMBSTONE until after
           * clearListeners.
           */
          executeListener(task, requireNonNull(curr.executor));
        }
      }
      break;
    }
  }

  /**
   * Callback method that is called exactly once after the future is completed.
   *
   * <p>If {@link #interruptTask} is also run during completion, {@link #afterDone} runs after it.
   *
   * <p>The default implementation of this method in {@code AbstractFuture} does nothing. This is
   * intended for very lightweight cleanup work, for example, timing statistics or clearing fields.
   * If your task does anything heavier consider, just using a listener with an executor.
   *
   * @since 20.0
   */
  @ForOverride
  protected void afterDone() {}

  // TODO(b/114236866): Inherit doc from InternalFutureFailureAccess. Also, -link to its URL.
  /**
   * Usually returns {@code null} but, if this {@code Future} has failed, may <i>optionally</i>
   * return the cause of the failure. "Failure" means specifically "completed with an exception"; it
   * does not include "was cancelled." To be explicit: If this method returns a non-null value,
   * then:
   *
   * <ul>
   *   <li>{@code isDone()} must return {@code true}
   *   <li>{@code isCancelled()} must return {@code false}
   *   <li>{@code get()} must not block, and it must throw an {@code ExecutionException} with the
   *       return value of this method as its cause
   * </ul>
   *
   * <p>This method is {@code protected} so that classes like {@code
   * com.google.common.util.concurrent.SettableFuture} do not expose it to their users as an
   * instance method. In the unlikely event that you need to call this method, call {@link
   * InternalFutures#tryInternalFastPathGetFailure(InternalFutureFailureAccess)}.
   *
   * @since 27.0
   */
  @Override
  /*
   * We should annotate the superclass, InternalFutureFailureAccess, to say that its copy of this
   * method returns @Nullable, too. However, we're not sure if we want to make any changes to that
   * class, since it's in a separate artifact that we planned to release only a single version of.
   */
  protected final @Nullable Throwable tryInternalFastPathGetFailure() {
    if (this instanceof Trusted) {
      @RetainedLocalRef Object localValue = value();
      if (localValue instanceof Failure) {
        return ((Failure) localValue).exception;
      }
    }
    return null;
  }

  /**
   * If this future has been cancelled (and possibly interrupted), cancels (and possibly interrupts)
   * the given future (if available).
   */
  @SuppressWarnings("nullness") // TODO(b/147136275): Remove once our checker understands & and |.
  final void maybePropagateCancellationTo(@Nullable Future<?> related) {
    if (related != null & isCancelled()) {
      related.cancel(wasInterrupted());
    }
  }

  /**
   * Clears the {@link #listeners} list and prepends its contents to {@code onto}, least recently
   * added first.
   */
  private @Nullable Listener clearListeners(@Nullable Listener onto) {
    // We need to
    // 1. atomically swap the listeners with TOMBSTONE, this is because addListener uses that
    //    to synchronize with us
    // 2. reverse the linked list, because despite our rather clear contract, people depend on us
    //    executing listeners in the order they were added
    // 3. push all the items onto 'onto' and return the new head of the stack
    Listener head = gasListeners(Listener.TOMBSTONE);
    Listener reversedList = onto;
    while (head != null) {
      Listener tmp = head;
      head = head.next;
      tmp.next = reversedList;
      reversedList = tmp;
    }
    return reversedList;
  }

  // TODO(user): move parts into a default method on ListenableFuture?
  @Override
  public String toString() {
    // TODO(cpovirk): Presize to something plausible?
    StringBuilder builder = new StringBuilder();
    if (getClass().getName().startsWith("com.google.common.util.concurrent.")) {
      builder.append(getClass().getSimpleName());
    } else {
      builder.append(getClass().getName());
    }
    builder.append('@').append(toHexString(identityHashCode(this))).append("[status=");
    if (isCancelled()) {
      builder.append("CANCELLED");
    } else if (isDone()) {
      addDoneString(builder);
    } else {
      addPendingString(builder); // delegates to addDoneString if future completes midway
    }
    return builder.append("]").toString();
  }

  /**
   * Provide a human-readable explanation of why this future has not yet completed.
   *
   * @return null if an explanation cannot be provided (e.g. because the future is done).
   * @since 23.0
   */
  protected @Nullable String pendingToString() {
    // TODO(diamondm) consider moving this into addPendingString so it's always in the output
    if (this instanceof ScheduledFuture) {
      return "remaining delay=[" + ((ScheduledFuture) this).getDelay(MILLISECONDS) + " ms]";
    }
    return null;
  }

  @SuppressWarnings("CatchingUnchecked") // sneaky checked exception
  private void addPendingString(StringBuilder builder) {
    // Capture current builder length so it can be truncated if this future ends up completing while
    // the toString is being calculated
    int truncateLength = builder.length();

    builder.append("PENDING");

    @RetainedLocalRef Object localValue = value();
    if (localValue instanceof DelegatingToFuture) {
      builder.append(", setFuture=[");
      appendUserObject(builder, ((DelegatingToFuture) localValue).future);
      builder.append("]");
    } else {
      String pendingDescription;
      try {
        pendingDescription = Strings.emptyToNull(pendingToString());
      } catch (Throwable e) {
        /*
         * We want to catch (Exception | StackOverflowError), but we can't under environments where
         * StackOverflowError doesn't exist.
         */
        rethrowIfErrorOtherThanStackOverflow(e);
        // The Throwable is either a RuntimeException, an Error, or sneaky checked exception.
        //
        // Don't call getMessage or toString() on the exception, in case the exception thrown by the
        // subclass is implemented with bugs similar to the subclass.
        pendingDescription = "Exception thrown from implementation: " + e.getClass();
      }
      if (pendingDescription != null) {
        builder.append(", info=[").append(pendingDescription).append("]");
      }
    }

    // The future may complete while calculating the toString, so we check once more to see if the
    // future is done
    if (isDone()) {
      // Truncate anything that was appended before realizing this future is done
      builder.delete(truncateLength, builder.length());
      addDoneString(builder);
    }
  }

  @SuppressWarnings("CatchingUnchecked") // sneaky checked exception
  private void addDoneString(StringBuilder builder) {
    try {
      V value = getUninterruptibly(this);
      builder.append("SUCCESS, result=[");
      appendResultObject(builder, value);
      builder.append("]");
    } catch (ExecutionException e) {
      builder.append("FAILURE, cause=[").append(e.getCause()).append("]");
    } catch (CancellationException e) {
      builder.append("CANCELLED"); // shouldn't be reachable
    } catch (Exception e) { // sneaky checked exception
      builder.append("UNKNOWN, cause=[").append(e.getClass()).append(" thrown from get()]");
    }
  }

  /**
   * Any object can be the result of a Future, and not every object has a reasonable toString()
   * implementation. Using a reconstruction of the default Object.toString() prevents OOMs and stack
   * overflows, and helps avoid sensitive data inadvertently ending up in exception messages.
   */
  private void appendResultObject(StringBuilder builder, @Nullable Object o) {
    if (o == null) {
      builder.append("null");
    } else if (o == this) {
      builder.append("this future");
    } else {
      builder
          .append(o.getClass().getName())
          .append("@")
          .append(Integer.toHexString(System.identityHashCode(o)));
    }
  }

  /** Helper for printing user supplied objects into our toString method. */
  @SuppressWarnings("CatchingUnchecked") // sneaky checked exception
  private void appendUserObject(StringBuilder builder, @Nullable Object o) {
    // This is some basic recursion detection for when people create cycles via set/setFuture or
    // when deep chains of futures exist resulting in a StackOverflowError. We could detect
    // arbitrary cycles using a thread local but this should be a good enough solution (it is also
    // what jdk collections do in these cases)
    try {
      if (o == this) {
        builder.append("this future");
      } else {
        builder.append(o);
      }
    } catch (Throwable e) {
      /*
       * We want to catch (Exception | StackOverflowError), but we can't under environments where
       * StackOverflowError doesn't exist.
       */
      rethrowIfErrorOtherThanStackOverflow(e);
      // The Throwable is either a RuntimeException, an Error, or sneaky checked exception.
      //
      // Don't call getMessage or toString() on the exception, in case the exception thrown by the
      // user object is implemented with bugs similar to the user object.
      builder.append("Exception thrown from implementation: ").append(e.getClass());
    }
  }

  /**
   * Submits the given runnable to the given {@link Executor} catching and logging all {@linkplain
   * RuntimeException runtime exceptions} thrown by the executor.
   */
  @SuppressWarnings("CatchingUnchecked") // sneaky checked exception
  private static void executeListener(Runnable runnable, Executor executor) {
    try {
      executor.execute(runnable);
    } catch (Exception e) { // sneaky checked exception
      // Log it and keep going -- bad runnable and/or executor. Don't punish the other runnables if
      // we're given a bad one. We only catch Exception because we want Errors to propagate up.
      log.get()
          .log(
              SEVERE,
              "RuntimeException while executing runnable "
                  + runnable
                  + " with executor "
                  + executor,
              e);
    }
  }

  private static CancellationException cancellationExceptionWithCause(
      String message, @Nullable Throwable cause) {
    CancellationException exception = new CancellationException(message);
    exception.initCause(cause);
    return exception;
  }
}

READ /tmp/java-baseline-guava-3350/guava/src/com/google/common/util/concurrent/ListenableFuture.java
/*
 * Copyright (C) 2007 The Guava Authors
 *
 * 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 com.google.common.util.concurrent;

import com.google.errorprone.annotations.DoNotMock;
import java.util.concurrent.Executor;
import java.util.concurrent.Future;
import java.util.concurrent.RejectedExecutionException;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

/**
 * 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 {@link
 * Futures#transform(ListenableFuture, com.google.common.base.Function, Executor) Futures.transform}
 * (or {@link FluentFuture#transform(com.google.common.base.Function, Executor)
 * FluentFuture.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>
 *   <li><a href="https://dagger.dev/producers.html">Dagger Producers</a>
 * </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 {@link Futures#addCallback
 * Futures.addCallback}.) Still, direct {@code addListener} calls are occasionally useful:
 *
 * {@snippet :
 * 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);
 * }
 *
 * <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 {@linkplain Futures 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 {@link ListeningExecutorService}, usually by calling {@link
 *       MoreExecutors#listeningDecorator(java.util.concurrent.ExecutorService)
 *       MoreExecutors.listeningDecorator}.
 *   <li>If you manually call {@link java.util.concurrent.FutureTask#set} or a similar method,
 *       create a {@link SettableFuture} instead. (If your needs are more complex, you may prefer
 *       {@link AbstractFuture}.)
 * </ul>
 *
 * <p><b>Test doubles</b>: If you need a {@code ListenableFuture} for your test, try a {@link
 * SettableFuture} or one of the methods in the {@link Futures#immediateFuture 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 {@link Futures} or, if necessary, to extend {@link 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
 */
/*
 * Some of the annotations below were added after we released our separate
 * com.google.guava:listenablefuture:1.0 artifact. (For more on that artifact, see
 * https://github.com/google/guava/releases/tag/v27.0) This means that the copy of ListenableFuture
 * in com.google.guava:guava differs from the "frozen" copy in the listenablefuture artifact. This
 * could in principle cause problems for some users. Still, we expect that the benefits of the
 * nullness annotations in particular will outweigh the costs. (And it's worth noting that we have
 * released multiple ListenableFuture.class files that are not byte-for-byte compatible even from
 * the beginning, thanks to using different `-source -target` values for compiling our `-jre` and
 * `-android` "flavors.")
 *
 * (We could consider releasing a listenablefuture:1.0.1 someday. But we would want to look into how
 * that affects users, especially users of the Android Gradle Plugin, since the plugin developers
 * put in a special hack for us: https://issuetracker.google.com/issues/131431257)
 */
@DoNotMock("Use the methods in Futures (like immediateFuture) or SettableFuture")
@NullMarked
public interface ListenableFuture<V extends @Nullable Object> 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 {@linkplain MoreExecutors#directExecutor direct execution}) will be caught and
   * logged.
   *
   * <p>Note: If your listener is lightweight -- and will not cause stack overflow by completing
   * more futures or adding more {@code directExecutor()} listeners inline -- consider {@link
   * MoreExecutors#directExecutor}. Otherwise, avoid it: See the warnings on the docs for {@code
   * directExecutor}.
   *
   * <p>This is the most general listener interface. For common operations performed using
   * listeners, see {@link Futures}. For a simplified but general listener interface, see {@link
   * Futures#addCallback 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 RejectedExecutionException if we tried to execute the listener immediately but the
   *     executor rejected it.
   */
  void addListener(Runnable listener, Executor executor);
}
