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 static com.google.common.util.concurrent.Internal.toNanosSaturated; 018 019import com.google.common.annotations.GwtIncompatible; 020import com.google.common.annotations.J2ktIncompatible; 021import com.google.errorprone.annotations.DoNotMock; 022import java.time.Duration; 023import java.util.Collection; 024import java.util.List; 025import java.util.concurrent.Callable; 026import java.util.concurrent.ExecutionException; 027import java.util.concurrent.ExecutorService; 028import java.util.concurrent.Future; 029import java.util.concurrent.RejectedExecutionException; 030import java.util.concurrent.TimeUnit; 031import java.util.concurrent.TimeoutException; 032import org.checkerframework.checker.nullness.qual.Nullable; 033 034/** 035 * An {@link ExecutorService} that returns {@link ListenableFuture} instances. To create an instance 036 * from an existing {@link ExecutorService}, call {@link 037 * MoreExecutors#listeningDecorator(ExecutorService)}. 038 * 039 * @author Chris Povirk 040 * @since 10.0 041 */ 042@DoNotMock( 043 "Use TestingExecutors.sameThreadScheduledExecutor, or wrap a real Executor from " 044 + "java.util.concurrent.Executors with MoreExecutors.listeningDecorator") 045@GwtIncompatible 046@ElementTypesAreNonnullByDefault 047public interface ListeningExecutorService extends ExecutorService { 048 /** 049 * @return a {@code ListenableFuture} representing pending completion of the task 050 * @throws RejectedExecutionException {@inheritDoc} 051 */ 052 @Override 053 <T extends @Nullable Object> ListenableFuture<T> submit(Callable<T> task); 054 055 /** 056 * @return a {@code ListenableFuture} representing pending completion of the task 057 * @throws RejectedExecutionException {@inheritDoc} 058 */ 059 @Override 060 ListenableFuture<?> submit(Runnable task); 061 062 /** 063 * @return a {@code ListenableFuture} representing pending completion of the task 064 * @throws RejectedExecutionException {@inheritDoc} 065 */ 066 @Override 067 <T extends @Nullable Object> ListenableFuture<T> submit( 068 Runnable task, @ParametricNullness T result); 069 070 /** 071 * {@inheritDoc} 072 * 073 * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest 074 * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe) 075 * cast: 076 * 077 * <pre> 078 * {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract} 079 * {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks);} 080 * </pre> 081 * 082 * @return A list of {@code ListenableFuture} instances representing the tasks, in the same 083 * sequential order as produced by the iterator for the given task list, each of which has 084 * completed. 085 * @throws RejectedExecutionException {@inheritDoc} 086 * @throws NullPointerException if any task is null 087 */ 088 @Override 089 <T extends @Nullable Object> List<Future<T>> invokeAll(Collection<? extends Callable<T>> tasks) 090 throws InterruptedException; 091 092 /** 093 * {@inheritDoc} 094 * 095 * <p>All elements in the returned list must be {@link ListenableFuture} instances. The easiest 096 * way to obtain a {@code List<ListenableFuture<T>>} from this method is an unchecked (but safe) 097 * cast: 098 * 099 * <pre> 100 * {@code @SuppressWarnings("unchecked") // guaranteed by invokeAll contract} 101 * {@code List<ListenableFuture<T>> futures = (List) executor.invokeAll(tasks, timeout, unit);} 102 * </pre> 103 * 104 * @return a list of {@code ListenableFuture} instances representing the tasks, in the same 105 * sequential order as produced by the iterator for the given task list. If the operation did 106 * not time out, each task will have completed. If it did time out, some of these tasks will 107 * not have completed. 108 * @throws RejectedExecutionException {@inheritDoc} 109 * @throws NullPointerException if any task is null 110 */ 111 @Override 112 <T extends @Nullable Object> List<Future<T>> invokeAll( 113 Collection<? extends Callable<T>> tasks, long timeout, TimeUnit unit) 114 throws InterruptedException; 115 116 /** 117 * Duration-based overload of {@link #invokeAll(Collection, long, TimeUnit)}. 118 * 119 * @since 32.1.0 120 */ 121 @J2ktIncompatible 122 default <T extends @Nullable Object> List<Future<T>> invokeAll( 123 Collection<? extends Callable<T>> tasks, Duration timeout) throws InterruptedException { 124 return invokeAll(tasks, toNanosSaturated(timeout), TimeUnit.NANOSECONDS); 125 } 126 127 /** 128 * Duration-based overload of {@link #invokeAny(Collection, long, TimeUnit)}. 129 * 130 * @since 32.1.0 131 */ 132 @J2ktIncompatible 133 default <T extends @Nullable Object> T invokeAny( 134 Collection<? extends Callable<T>> tasks, Duration timeout) 135 throws InterruptedException, ExecutionException, TimeoutException { 136 return invokeAny(tasks, toNanosSaturated(timeout), TimeUnit.NANOSECONDS); 137 } 138 139 /** 140 * Duration-based overload of {@link #awaitTermination(long, TimeUnit)}. 141 * 142 * @since 32.1.0 143 */ 144 @J2ktIncompatible 145 default boolean awaitTermination(Duration timeout) throws InterruptedException { 146 return awaitTermination(toNanosSaturated(timeout), TimeUnit.NANOSECONDS); 147 } 148}