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