1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * This file is available under and governed by the GNU General Public 27 * License version 2 only, as published by the Free Software Foundation. 28 * However, the following notice accompanied the original version of this 29 * file: 30 * 31 * Written by Doug Lea with assistance from members of JCP JSR-166 32 * Expert Group and released to the public domain, as explained at 33 * http://creativecommons.org/publicdomain/zero/1.0/ 34 */ 35 36 package java.util.concurrent; 37 38 /** 39 * A service that decouples the production of new asynchronous tasks 40 * from the consumption of the results of completed tasks. Producers 41 * {@code submit} tasks for execution. Consumers {@code take} 42 * completed tasks and process their results in the order they 43 * complete. A {@code CompletionService} can for example be used to 44 * manage asynchronous I/O, in which tasks that perform reads are 45 * submitted in one part of a program or system, and then acted upon 46 * in a different part of the program when the reads complete, 47 * possibly in a different order than they were requested. 48 * 49 * <p>Typically, a {@code CompletionService} relies on a separate 50 * {@link Executor} to actually execute the tasks, in which case the 51 * {@code CompletionService} only manages an internal completion 52 * queue. The {@link ExecutorCompletionService} class provides an 53 * implementation of this approach. 54 * 55 * <p>Memory consistency effects: Actions in a thread prior to 56 * submitting a task to a {@code CompletionService} 57 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 58 * actions taken by that task, which in turn <i>happen-before</i> 59 * actions following a successful return from the corresponding {@code take()}. 60 * 61 * @param <V> the type of values the tasks of this service produce and consume 62 * 63 * @since 1.5 64 */ 65 public interface CompletionService<V> { 66 /** 67 * Submits a value-returning task for execution and returns a Future 68 * representing the pending results of the task. Upon completion, 69 * this task may be taken or polled. 70 * 71 * @param task the task to submit 72 * @return a Future representing pending completion of the task 73 * @throws RejectedExecutionException if the task cannot be 74 * scheduled for execution 75 * @throws NullPointerException if the task is null 76 */ submit(Callable<V> task)77 Future<V> submit(Callable<V> task); 78 79 /** 80 * Submits a Runnable task for execution and returns a Future 81 * representing that task. Upon completion, this task may be 82 * taken or polled. 83 * 84 * @param task the task to submit 85 * @param result the result to return upon successful completion 86 * @return a Future representing pending completion of the task, 87 * and whose {@code get()} method will return the given 88 * result value upon completion 89 * @throws RejectedExecutionException if the task cannot be 90 * scheduled for execution 91 * @throws NullPointerException if the task is null 92 */ submit(Runnable task, V result)93 Future<V> submit(Runnable task, V result); 94 95 /** 96 * Retrieves and removes the Future representing the next 97 * completed task, waiting if none are yet present. 98 * 99 * @return the Future representing the next completed task 100 * @throws InterruptedException if interrupted while waiting 101 */ take()102 Future<V> take() throws InterruptedException; 103 104 /** 105 * Retrieves and removes the Future representing the next 106 * completed task, or {@code null} if none are present. 107 * 108 * @return the Future representing the next completed task, or 109 * {@code null} if none are present 110 */ poll()111 Future<V> poll(); 112 113 /** 114 * Retrieves and removes the Future representing the next 115 * completed task, waiting if necessary up to the specified wait 116 * time if none are yet present. 117 * 118 * @param timeout how long to wait before giving up, in units of 119 * {@code unit} 120 * @param unit a {@code TimeUnit} determining how to interpret the 121 * {@code timeout} parameter 122 * @return the Future representing the next completed task or 123 * {@code null} if the specified waiting time elapses 124 * before one is present 125 * @throws InterruptedException if interrupted while waiting 126 */ poll(long timeout, TimeUnit unit)127 Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException; 128 } 129