Source for java.util.concurrent.CompletionService

   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: }