View Javadoc
1   /*
2    * Copyright (C) 2010 The Guava Authors
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5    * in compliance with the License. You may obtain a copy of the License at
6    *
7    * http://www.apache.org/licenses/LICENSE-2.0
8    *
9    * Unless required by applicable law or agreed to in writing, software distributed under the License
10   * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11   * or implied. See the License for the specific language governing permissions and limitations under
12   * the License.
13   */
14  
15  package com.google.common.util.concurrent;
16  
17  import com.google.common.annotations.GwtIncompatible;
18  import java.util.Collection;
19  import java.util.List;
20  import java.util.concurrent.Callable;
21  import java.util.concurrent.ExecutorService;
22  import java.util.concurrent.Future;
23  import java.util.concurrent.RejectedExecutionException;
24  import java.util.concurrent.TimeUnit;
25  
26  /**
27   * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance
28   * from an existing {@link ExecutorService}, call {@link
29   * MoreExecutors#listeningDecorator(ExecutorService)}.
30   *
31   * @author Chris Povirk
32   * @since 10.0
33   */
34  @GwtIncompatible
35  public interface ListeningExecutorService extends ExecutorService {
36    /**
37     * @return a {@code ListenableFuture} representing pending completion of the task
38     * @throws RejectedExecutionException {@inheritDoc}
39     */
40    @Override
41    <T> ListenableFuture<T> submit(Callable<T> task);
42  
43    /**
44     * @return a {@code ListenableFuture} representing pending completion of the task
45     * @throws RejectedExecutionException {@inheritDoc}
46     */
47    @Override
48    ListenableFuture<?> submit(Runnable task);
49  
50    /**
51     * @return a {@code ListenableFuture} representing pending completion of the task
52     * @throws RejectedExecutionException {@inheritDoc}
53     */
54    @Override
55    <T> ListenableFuture<T> submit(Runnable task, T result);
56  
57    /**
58     * {@inheritDoc}
59     *
60     * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest
61     * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe)
62     * cast:<pre>
63     *   {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract}
64     *   {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks);}
65     * </pre>
66     *
67     * @return A list of {@code ListenableFuture} instances representing the tasks, in the same
68     *     sequential order as produced by the iterator for the given task list, each of which has
69     *     completed.
70     * @throws RejectedExecutionException {@inheritDoc}
71     * @throws NullPointerException if any task is null
72     */
73    @Override
74    <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
75        throws InterruptedException;
76  
77    /**
78     * {@inheritDoc}
79     *
80     * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest
81     * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe)
82     * cast:<pre>
83     *   {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract}
84     *   {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks, timeout, unit);}
85     * </pre>
86     *
87     * @return a list of {@code ListenableFuture} instances representing the tasks, in the same
88     *     sequential order as produced by the iterator for the given task list. If the operation did
89     *     not time out, each task will have completed. If it did time out, some of these tasks will
90     *     not have completed.
91     * @throws RejectedExecutionException {@inheritDoc}
92     * @throws NullPointerException if any task is null
93     */
94    @Override
95    <T> List<Future<T>> invokeAll(
96        Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
97        throws InterruptedException;
98  }