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