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 public interface CompletionService<V> { 62 /** 63 * Submits a value-returning task for execution and returns a Future 64 * representing the pending results of the task. Upon completion, 65 * this task may be taken or polled. 66 * 67 * @param task the task to submit 68 * @return a Future representing pending completion of the task 69 * @throws RejectedExecutionException if the task cannot be 70 * scheduled for execution 71 * @throws NullPointerException if the task is null 72 */ submit(Callable<V> task)73 Future<V> submit(Callable<V> task); 74 75 /** 76 * Submits a Runnable task for execution and returns a Future 77 * representing that task. Upon completion, this task may be 78 * taken or polled. 79 * 80 * @param task the task to submit 81 * @param result the result to return upon successful completion 82 * @return a Future representing pending completion of the task, 83 * and whose {@code get()} method will return the given 84 * result value upon completion 85 * @throws RejectedExecutionException if the task cannot be 86 * scheduled for execution 87 * @throws NullPointerException if the task is null 88 */ submit(Runnable task, V result)89 Future<V> submit(Runnable task, V result); 90 91 /** 92 * Retrieves and removes the Future representing the next 93 * completed task, waiting if none are yet present. 94 * 95 * @return the Future representing the next completed task 96 * @throws InterruptedException if interrupted while waiting 97 */ take()98 Future<V> take() throws InterruptedException; 99 100 /** 101 * Retrieves and removes the Future representing the next 102 * completed task, or {@code null} if none are present. 103 * 104 * @return the Future representing the next completed task, or 105 * {@code null} if none are present 106 */ poll()107 Future<V> poll(); 108 109 /** 110 * Retrieves and removes the Future representing the next 111 * completed task, waiting if necessary up to the specified wait 112 * time if none are yet present. 113 * 114 * @param timeout how long to wait before giving up, in units of 115 * {@code unit} 116 * @param unit a {@code TimeUnit} determining how to interpret the 117 * {@code timeout} parameter 118 * @return the Future representing the next completed task or 119 * {@code null} if the specified waiting time elapses 120 * before one is present 121 * @throws InterruptedException if interrupted while waiting 122 */ poll(long timeout, TimeUnit unit)123 Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException; 124 } 125