GNU Classpath (0.98) | |
Frames | No Frames |
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/licenses/publicdomain 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: * <tt>submit</tt> tasks for execution. Consumers <tt>take</tt> 13: * completed tasks and process their results in the order they 14: * complete. A <tt>CompletionService</tt> can for example be used to 15: * manage asynchronous IO, 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 <tt>CompletionService</tt> relies on a separate 21: * {@link Executor} to actually execute the tasks, in which case the 22: * <tt>CompletionService</tt> 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: */ 33: public interface CompletionService<V> { 34: /** 35: * Submits a value-returning task for execution and returns a Future 36: * representing the pending results of the task. Upon completion, 37: * this task may be taken or polled. 38: * 39: * @param task the task to submit 40: * @return a Future representing pending completion of the task 41: * @throws RejectedExecutionException if the task cannot be 42: * scheduled for execution 43: * @throws NullPointerException if the task is null 44: */ 45: Future<V> submit(Callable<V> task); 46: 47: /** 48: * Submits a Runnable task for execution and returns a Future 49: * representing that task. Upon completion, this task may be 50: * taken or polled. 51: * 52: * @param task the task to submit 53: * @param result the result to return upon successful completion 54: * @return a Future representing pending completion of the task, 55: * and whose <tt>get()</tt> method will return the given 56: * result value upon completion 57: * @throws RejectedExecutionException if the task cannot be 58: * scheduled for execution 59: * @throws NullPointerException if the task is null 60: */ 61: Future<V> submit(Runnable task, V result); 62: 63: /** 64: * Retrieves and removes the Future representing the next 65: * completed task, waiting if none are yet present. 66: * 67: * @return the Future representing the next completed task 68: * @throws InterruptedException if interrupted while waiting 69: */ 70: Future<V> take() throws InterruptedException; 71: 72: 73: /** 74: * Retrieves and removes the Future representing the next 75: * completed task or <tt>null</tt> if none are present. 76: * 77: * @return the Future representing the next completed task, or 78: * <tt>null</tt> if none are present 79: */ 80: Future<V> poll(); 81: 82: /** 83: * Retrieves and removes the Future representing the next 84: * completed task, waiting if necessary up to the specified wait 85: * time if none are yet present. 86: * 87: * @param timeout how long to wait before giving up, in units of 88: * <tt>unit</tt> 89: * @param unit a <tt>TimeUnit</tt> determining how to interpret the 90: * <tt>timeout</tt> parameter 91: * @return the Future representing the next completed task or 92: * <tt>null</tt> if the specified waiting time elapses 93: * before one is present 94: * @throws InterruptedException if interrupted while waiting 95: */ 96: Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException; 97: }
GNU Classpath (0.98) |