import java.util.concurrent.TimeoutException;
import org.jspecify.annotations.Nullable;

/**
 * A {@link ListenableFuture} that supports fluent chains of operations. For example:
 *
 * {@snippet :
 * ListenableFuture<Boolean> adminIsLoggedIn =
 *     FluentFuture.from(usersDatabase.getAdminUser())
 *         .transform(User::getId, directExecutor())
 *         .transform(ActivityService::isLoggedIn, threadPool)

   * respective source streams. For example:
   *
   * {@snippet :
   * Streams.forEachPair(
   *   Stream.of("foo1", "foo2", "foo3"),
   *   Stream.of("bar1", "bar2"),
   *   (arg1, arg2) -> System.out.println(arg1 + ":" + arg2)
   * }
   *
   * <p>will print:
   *
   * {@snippet :
   * foo1:bar1
   * foo2:bar2
   * }
   *

   * java.util.stream} Javadoc), that order is preserved, but entries are <a
   * href="ImmutableMultimap.html#iteration">grouped by key</a>.
   *
   * <p>Example:
   *
   * {@snippet :
   * static final Multimap<Character, String> FIRST_LETTER_MULTIMAP =
   *     Stream.of("banana", "apple", "carrot", "asparagus", "cherry")

   * and not contents.
   *
   * <p>This is useful for implementing {@link Object#hashCode()}. For example, in an object that
   * has three properties, {@code x}, {@code y}, and {@code z}, one could write:
   *
   * {@snippet :
   * public int hashCode() {
   *   return Objects.hashCode(getX(), getY(), getZ());
   * }
   * }
   *
   * <p><b>Warning:</b> When a single object is supplied, the returned hash code does not equal the

   * the beginning and from the end of the string. For example:
   *
   * {@snippet :
   * CharMatcher.anyOf("ab").trimFrom("abacatbab")
   * }
   *
   * ... returns {@code "cat"}.
   *
   * <p>Note that:
   *
   * {@snippet :
   * CharMatcher.inRange('\0', ' ').trimFrom(str)
   * }
   *
   * ... is equivalent to {@link String#trim()}.
   */

 *
 * <p>Most implementations will only need to implement {@link #load}. Other methods may be
 * overridden as desired.
 *
 * <p>Usage example:
 *
 * {@snippet :
 * CacheLoader<Key, Graph> loader = new CacheLoader<Key, Graph>() {
 *   public Graph load(Key key) throws AnyException {
 *     return createExpensiveGraph(key);
 *   }
 * };

 * as a {@code List}:
 *
 * {@snippet :
 * ImmutableList<String> results =
 *     FluentIterable.from(database.getClientList())
 *         .filter(Client::isActiveInLastMonth)
 *         .transform(Object::toString)
 *         .limit(10)
 *         .toList();
 * }
 *
 * The approximate stream equivalent is:
 *
 * {@snippet :
 * List<String> results =
 *     database.getClientList()

 * as a {@code List}:
 *
 * {@snippet :
 * ImmutableList<String> results =
 *     FluentIterable.from(database.getClientList())
 *         .filter(Client::isActiveInLastMonth)
 *         .transform(Object::toString)
 *         .limit(10)
 *         .toList();
 * }
 *
 * The approximate stream equivalent is:
 *
 * {@snippet :
 * List<String> results =
 *     database.getClientList()

   * that tests equivalence using their lengths:
   *
   * {@snippet :
   * equiv.wrap("a").equals(equiv.wrap("b")) // true
   * equiv.wrap("a").equals(equiv.wrap("hello")) // false
   * }
   *
   * <p>Note in particular that an equivalence wrapper is never equal to the object it wraps.
   *
   * {@snippet :
   * equiv.wrap(obj).equals(obj) // always false
   * }
   *
   * @since 10.0

   * fallback}, an exception is thrown, this exception is used as the result of the output {@code
   * Future}.
   *
   * <p>Usage example:
   *
   * {@snippet :
   * ListenableFuture<Integer> fetchCounterFuture = ...;
   *
   * // Falling back to a zero counter in case an exception happens when
   * // processing the RPC to fetch counters.