001/*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.util.concurrent;
016
017import static com.google.common.util.concurrent.Internal.toNanosSaturated;
018
019import com.google.common.annotations.GwtIncompatible;
020import com.google.common.annotations.J2ktIncompatible;
021import com.google.errorprone.annotations.DoNotMock;
022import java.time.Duration;
023import java.util.Collection;
024import java.util.List;
025import java.util.concurrent.Callable;
026import java.util.concurrent.ExecutionException;
027import java.util.concurrent.ExecutorService;
028import java.util.concurrent.Future;
029import java.util.concurrent.RejectedExecutionException;
030import java.util.concurrent.TimeUnit;
031import java.util.concurrent.TimeoutException;
032import org.checkerframework.checker.nullness.qual.Nullable;
033
034/**
035 * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance
036 * from an existing {@link ExecutorService}, call {@link
037 * MoreExecutors#listeningDecorator(ExecutorService)}.
038 *
039 * @author Chris Povirk
040 * @since 10.0
041 */
042@DoNotMock(
043    "Use TestingExecutors.sameThreadScheduledExecutor, or wrap a real Executor from "
044        + "java.util.concurrent.Executors with MoreExecutors.listeningDecorator")
045@GwtIncompatible
046@ElementTypesAreNonnullByDefault
047public interface ListeningExecutorService extends ExecutorService {
048  /**
049   * @return a {@code ListenableFuture} representing pending completion of the task
050   * @throws RejectedExecutionException {@inheritDoc}
051   */
052  @Override
053  <T extends @Nullable Object> ListenableFuture<T> submit(Callable<T> task);
054
055  /**
056   * @return a {@code ListenableFuture} representing pending completion of the task
057   * @throws RejectedExecutionException {@inheritDoc}
058   */
059  @Override
060  ListenableFuture<?> submit(Runnable task);
061
062  /**
063   * @return a {@code ListenableFuture} representing pending completion of the task
064   * @throws RejectedExecutionException {@inheritDoc}
065   */
066  @Override
067  <T extends @Nullable Object> ListenableFuture<T> submit(
068      Runnable task, @ParametricNullness T result);
069
070  /**
071   * {@inheritDoc}
072   *
073   * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest
074   * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe)
075   * cast:
076   *
077   * <pre>
078   *   {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract}
079   *   {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks);}
080   * </pre>
081   *
082   * @return A list of {@code ListenableFuture} instances representing the tasks, in the same
083   *     sequential order as produced by the iterator for the given task list, each of which has
084   *     completed.
085   * @throws RejectedExecutionException {@inheritDoc}
086   * @throws NullPointerException if any task is null
087   */
088  @Override
089  <T extends @Nullable Object> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
090      throws InterruptedException;
091
092  /**
093   * {@inheritDoc}
094   *
095   * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest
096   * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe)
097   * cast:
098   *
099   * <pre>
100   *   {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract}
101   *   {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks, timeout, unit);}
102   * </pre>
103   *
104   * @return a list of {@code ListenableFuture} instances representing the tasks, in the same
105   *     sequential order as produced by the iterator for the given task list. If the operation did
106   *     not time out, each task will have completed. If it did time out, some of these tasks will
107   *     not have completed.
108   * @throws RejectedExecutionException {@inheritDoc}
109   * @throws NullPointerException if any task is null
110   */
111  @Override
112  <T extends @Nullable Object> List<Future<T>> invokeAll(
113      Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
114      throws InterruptedException;
115
116  /**
117   * Duration-based overload of {@link #invokeAll(Collection, long, TimeUnit)}.
118   *
119   * @since 32.1.0
120   */
121  @J2ktIncompatible
122  default <T extends @Nullable Object> List<Future<T>> invokeAll(
123      Collection<? extends Callable<T>> tasks, Duration timeout) throws InterruptedException {
124    return invokeAll(tasks, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
125  }
126
127  /**
128   * Duration-based overload of {@link #invokeAny(Collection, long, TimeUnit)}.
129   *
130   * @since 32.1.0
131   */
132  @J2ktIncompatible
133  default <T extends @Nullable Object> T invokeAny(
134      Collection<? extends Callable<T>> tasks, Duration timeout)
135      throws InterruptedException, ExecutionException, TimeoutException {
136    return invokeAny(tasks, toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
137  }
138
139  /**
140   * Duration-based overload of {@link #awaitTermination(long, TimeUnit)}.
141   *
142   * @since 32.1.0
143   */
144  @J2ktIncompatible
145  default boolean awaitTermination(Duration timeout) throws InterruptedException {
146    return awaitTermination(toNanosSaturated(timeout), TimeUnit.NANOSECONDS);
147  }
148}