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 017package com.google.common.util.concurrent; 018 019import java.util.Collection; 020import java.util.List; 021import java.util.concurrent.Callable; 022import java.util.concurrent.ExecutorService; 023import java.util.concurrent.Future; 024import java.util.concurrent.RejectedExecutionException; 025import 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 */ 035public interface ListeningExecutorService extends ExecutorService { 036 /** 037 * @return a {@code ListenableFuture} representing pending completion of the task 038 * @throws RejectedExecutionException {@inheritDoc} 039 */ 040 @Override 041 <T> ListenableFuture<T> submit(Callable<T> task); 042 043 /** 044 * @return a {@code ListenableFuture} representing pending completion of the task 045 * @throws RejectedExecutionException {@inheritDoc} 046 */ 047 @Override 048 ListenableFuture<?> submit(Runnable task); 049 050 /** 051 * @return a {@code ListenableFuture} representing pending completion of the task 052 * @throws RejectedExecutionException {@inheritDoc} 053 */ 054 @Override 055 <T> ListenableFuture<T> submit(Runnable task, T result); 056 057 /** 058 * {@inheritDoc} 059 * 060 * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest 061 * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe) 062 * cast:<pre> 063 * {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract} 064 * {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks);} 065 * </pre> 066 * 067 * @return A list of {@code ListenableFuture} instances representing the tasks, in the same 068 * sequential order as produced by the iterator for the given task list, each of which has 069 * completed. 070 * @throws RejectedExecutionException {@inheritDoc} 071 * @throws NullPointerException if any task is null 072 */ 073 @Override 074 <T> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 075 throws InterruptedException; 076 077 /** 078 * {@inheritDoc} 079 * 080 * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest 081 * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe) 082 * cast:<pre> 083 * {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract} 084 * {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks, timeout, unit);} 085 * </pre> 086 * 087 * @return a list of {@code ListenableFuture} instances representing the tasks, in the same 088 * sequential order as produced by the iterator for the given task list. If the operation 089 * did not time out, each task will have completed. If it did time out, some of these 090 * tasks will not have completed. 091 * @throws RejectedExecutionException {@inheritDoc} 092 * @throws NullPointerException if any task is null 093 */ 094 @Override 095 <T> List<Future<T>> invokeAll( 096 Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 097 throws InterruptedException; 098}