1 /* 2 * Copyright (C) 2010 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.util.concurrent; 18 19 import java.util.Collection; 20 import java.util.List; 21 import java.util.concurrent.Callable; 22 import java.util.concurrent.ExecutorService; 23 import java.util.concurrent.Future; 24 import java.util.concurrent.RejectedExecutionException; 25 import java.util.concurrent.TimeUnit; 26 27 /** 28 * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance 29 * from an existing {@link ExecutorService}, call 30 * {@link MoreExecutors#listeningDecorator(ExecutorService)}. 31 * 32 * @author Chris Povirk 33 * @since 10.0 34 */ 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 submit(Callable<T> task)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 submit(Runnable task)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 submit(Runnable task, T result)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 invokeAll(Collection<? extends Callable<T>> tasks)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 89 * did not time out, each task will have completed. If it did time out, some of these 90 * tasks will not have completed. 91 * @throws RejectedExecutionException {@inheritDoc} 92 * @throws NullPointerException if any task is null 93 */ 94 @Override invokeAll( Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit)95 <T> List<Future<T>> invokeAll( 96 Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 97 throws InterruptedException; 98 } 99