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
7package 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 */
32public 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     */
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     */
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     */
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     */
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     */
94    Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException;
95}
96