util/concurrent/CompletionService.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain. Use, modify, and
 * redistribute this code in any way without acknowledgement.
 */

package java.util.concurrent;

/**
 * A service that decouples the production of new asynchronous tasks
 * from the consumption of the results of completed tasks.  Producers
 * <tt>submit</tt> tasks for execution. Consumers <tt>take</tt>
 * completed tasks and process their results in the order they
 * complete.  A <tt>CompletionService</tt> can for example be used to
 * manage asynchronous IO, in which tasks that perform reads are
 * submitted in one part of a program or system, and then acted upon
 * in a different part of the program when the reads complete,
 * possibly in a different order than they were requested.

 * <p>
 *
 * Typically, a <tt>CompletionService</tt> relies on a separate {@link
 * Executor} to actually execute the tasks, in which case the
 * <tt>CompletionService</tt> only manages an internal completion
 * queue. The {@link ExecutorCompletionService} class provides an
 * implementation of this approach.
 *
 */
public interface CompletionService<V> {
    /**
     * Submits a value-returning task for execution and returns a Future
     * representing the pending results of the task. Upon completion,
     * this task may be taken or polled.
     *
     * @param task the task to submit
     * @return a Future representing pending completion of the task
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     */
    Future<V> submit(Callable<V> task);


    /**
     * Submits a Runnable task for execution and returns a Future 
     * representing that task.Upon completion,
     * this task may be taken or polled.
     *
     * @param task the task to submit
     * @param result the result to return upon successful completion
     * @return a Future representing pending completion of the task,
     * and whose <tt>get()</tt> method will return the given result value 
     * upon completion
     * @throws RejectedExecutionException if task cannot be scheduled
     * for execution
     */
    Future<V> submit(Runnable task, V result);

    /**
     * Retrieves and removes the Future representing the next
     * completed task, waiting if none are yet present.
     * @return the Future representing the next completed task
     * @throws InterruptedException if interrupted while waiting.
     */
    Future<V> take() throws InterruptedException;


    /**
     * Retrieves and removes the Future representing the next
     * completed task or <tt>null</tt> if none are present.
     *
     * @return the Future representing the next completed task, or
     * <tt>null</tt> if none are present.
     */
    Future<V> poll();

    /**
     * Retrieves and removes the Future representing the next
     * completed task, waiting if necessary up to the specified wait
     * time if none are yet present.
     * @param timeout how long to wait before giving up, in units of
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return the Future representing the next completed task or
     * <tt>null</tt> if the specified waiting time elapses before one
     * is present.
     * @throws InterruptedException if interrupted while waiting.
     */
    Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException;
}
Revision:	1.3
Committed:	Sat Dec 20 17:05:27 2003 UTC (20 years, 5 months ago) by dl
Branch:	MAIN
Changes since 1.2:	+8 -8 lines
Log Message:	Updated documentation
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5			*/
6
7			package java.util.concurrent;
8
9			/**
10			* A service that decouples the production of new asynchronous tasks
11	dl	1.3	* 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	dl	1.2
20			* <p>
21			*
22			* Typically, a <tt>CompletionService</tt> relies on a separate {@link
23			* Executor} to actually execute the tasks, in which case the
24			* <tt>CompletionService</tt> only manages an internal completion
25			* queue. The {@link ExecutorCompletionService} class provides an
26			* implementation of this approach.
27			*
28	dl	1.1	*/
29			public interface CompletionService<V> {
30			/**
31			* Submits a value-returning task for execution and returns a Future
32			* representing the pending results of the task. Upon completion,
33			* this task may be taken or polled.
34			*
35			* @param task the task to submit
36			* @return a Future representing pending completion of the task
37			* @throws RejectedExecutionException if task cannot be scheduled
38			* for execution
39			*/
40			Future<V> submit(Callable<V> task);
41
42
43			/**
44			* Submits a Runnable task for execution and returns a Future
45			* representing that task.Upon completion,
46			* this task may be taken or polled.
47			*
48			* @param task the task to submit
49			* @param result the result to return upon successful completion
50			* @return a Future representing pending completion of the task,
51			* and whose <tt>get()</tt> method will return the given result value
52			* upon completion
53			* @throws RejectedExecutionException if task cannot be scheduled
54			* for execution
55			*/
56			Future<V> submit(Runnable task, V result);
57
58			/**
59			* Retrieves and removes the Future representing the next
60			* completed task, waiting if none are yet present.
61			* @return the Future representing the next completed task
62			* @throws InterruptedException if interrupted while waiting.
63			*/
64			Future<V> take() throws InterruptedException;
65
66
67			/**
68			* Retrieves and removes the Future representing the next
69			* completed task or <tt>null</tt> if none are present.
70			*
71			* @return the Future representing the next completed task, or
72			* <tt>null</tt> if none are present.
73			*/
74			Future<V> poll();
75
76			/**
77			* Retrieves and removes the Future representing the next
78			* completed task, waiting if necessary up to the specified wait
79			* time if none are yet present.
80			* @param timeout how long to wait before giving up, in units of
81			* <tt>unit</tt>
82			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
83			* <tt>timeout</tt> parameter
84			* @return the Future representing the next completed task or
85			* <tt>null</tt> if the specified waiting time elapses before one
86			* is present.
87			* @throws InterruptedException if interrupted while waiting.
88			*/
89			Future<V> poll(long timeout, TimeUnit unit) throws InterruptedException;
90			}