1 /* 2 * Written by Doug Lea with assistance from members of JCP JSR-166 3 * Expert Group and released to the public domain, as explained at 4 * http://creativecommons.org/publicdomain/zero/1.0/ 5 */ 6 7 package java.util.concurrent; 8 9 /** 10 * A service that decouples the production of new asynchronous tasks 11 * from the consumption of the results of completed tasks. Producers 12 * {@code submit} tasks for execution. Consumers {@code take} 13 * completed tasks and process their results in the order they 14 * complete. A {@code CompletionService} can for example be used to 15 * manage asynchronous I/O, in which tasks that perform reads are 16 * submitted in one part of a program or system, and then acted upon 17 * in a different part of the program when the reads complete, 18 * possibly in a different order than they were requested. 19 * 20 * <p>Typically, a {@code CompletionService} relies on a separate 21 * {@link Executor} to actually execute the tasks, in which case the 22 * {@code CompletionService} only manages an internal completion 23 * queue. The {@link ExecutorCompletionService} class provides an 24 * implementation of this approach. 25 * 26 * <p>Memory consistency effects: Actions in a thread prior to 27 * submitting a task to a {@code CompletionService} 28 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a> 29 * actions taken by that task, which in turn <i>happen-before</i> 30 * actions following a successful return from the corresponding {@code take()}. 31 */ 32 public interface CompletionService<V> { 33 /** 34 * Submits a value-returning task for execution and returns a Future 35 * representing the pending results of the task. Upon completion, 36 * this task may be taken or polled. 37 * 38 * @param task the task to submit 39 * @return a Future representing pending completion of the task 40 * @throws RejectedExecutionException if the task cannot be 41 * scheduled for execution 42 * @throws NullPointerException if the task is null 43 */ submit(Callable<V> task)44 Future<V> submit(Callable<V> task); 45 46 /** 47 * Submits a Runnable task for execution and returns a Future 48 * representing that task. Upon completion, this task may be 49 * taken or polled. 50 * 51 * @param task the task to submit 52 * @param result the result to return upon successful completion 53 * @return a Future representing pending completion of the task, 54 * and whose {@code get()} method will return the given 55 * result value upon completion 56 * @throws RejectedExecutionException if the task cannot be 57 * scheduled for execution 58 * @throws NullPointerException if the task is null 59 */ submit(Runnable task, V result)60 Future<V> submit(Runnable task, V result); 61 62 /** 63 * Retrieves and removes the Future representing the next 64 * completed task, waiting if none are yet present. 65 * 66 * @return the Future representing the next completed task 67 * @throws InterruptedException if interrupted while waiting 68 */ take()69 Future<V> take() throws InterruptedException; 70 71 /** 72 * Retrieves and removes the Future representing the next 73 * completed task, or {@code null} if none are present. 74 * 75 * @return the Future representing the next completed task, or 76 * {@code null} if none are present 77 */ poll()78 Future<V> poll(); 79 80 /** 81 * Retrieves and removes the Future representing the next 82 * completed task, waiting if necessary up to the specified wait 83 * time if none are yet present. 84 * 85 * @param timeout how long to wait before giving up, in units of 86 * {@code unit} 87 * @param unit a {@code TimeUnit} determining how to interpret the 88 * {@code timeout} parameter 89 * @return the Future representing the next completed task or 90 * {@code null} if the specified waiting time elapses 91 * before one is present 92 * @throws InterruptedException if interrupted while waiting 93 */ poll(long timeout, TimeUnit unit)94 Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException; 95 } 96