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