001    /*
002     * Copyright (C) 2010 The Guava Authors
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package com.google.common.util.concurrent;
018    
019    import java.util.Collection;
020    import java.util.List;
021    import java.util.concurrent.Callable;
022    import java.util.concurrent.ExecutorService;
023    import java.util.concurrent.Future;
024    import java.util.concurrent.RejectedExecutionException;
025    import java.util.concurrent.TimeUnit;
026    
027    /**
028     * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance
029     * from an existing {@link ExecutorService}, call
030     * {@link MoreExecutors#listeningDecorator(ExecutorService)}.
031     *
032     * @author Chris Povirk
033     * @since 10.0
034     */
035    public interface ListeningExecutorService extends ExecutorService {
036      /**
037       * @return a {@code ListenableFuture} representing pending completion of the task
038       * @throws RejectedExecutionException {@inheritDoc}
039       */
040      <T> ListenableFuture<T> submit(Callable<T> task);
041    
042      /**
043       * @return a {@code ListenableFuture} representing pending completion of the task
044       * @throws RejectedExecutionException {@inheritDoc}
045       */
046      ListenableFuture<?> submit(Runnable task);
047    
048      /**
049       * @return a {@code ListenableFuture} representing pending completion of the task
050       * @throws RejectedExecutionException {@inheritDoc}
051       */
052      <T> ListenableFuture<T> submit(Runnable task, T result);
053    
054      /**
055       * {@inheritDoc}
056       *
057       * <p>All elements in the returned list must be {@link ListenableFuture} instances.
058       *
059       * @return A list of {@code ListenableFuture} instances representing the tasks, in the same
060       *         sequential order as produced by the iterator for the given task list, each of which has
061       *         completed.
062       * @throws RejectedExecutionException {@inheritDoc}
063       * @throws NullPointerException if any task is null
064       */
065      <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks)
066          throws InterruptedException;
067    
068      /**
069       * {@inheritDoc}
070       *
071       * <p>All elements in the returned list must be {@link ListenableFuture} instances.
072       *
073       * @return a list of {@code ListenableFuture} instances representing the tasks, in the same
074       *         sequential order as produced by the iterator for the given task list. If the operation
075       *         did not time out, each task will have completed. If it did time out, some of these
076       *         tasks will not have completed.
077       * @throws RejectedExecutionException {@inheritDoc}
078       * @throws NullPointerException if any task is null
079       */
080      <T> List<Future<T>> invokeAll(
081          Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)
082          throws InterruptedException;
083    }