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