util/concurrent/ThreadedExecutor.java

/*
 * @(#)ThreadedExecutor.java
 */

package java.util.concurrent;

import java.util.List;

/**
 * An executor that executes submitted tasks on one or more dedicated threads.
 *
 * @fixme Document ThreadFactory, CannotExecuteHandler, Queue
 *
 * <p>A <tt>ThreadedExecutor</tt> can be shut down, which will cause it to stop
 * accepting new tasks.  After being shut down, the executor will 
 * eventually terminate, at which point no tasks are actively executing, no
 * tasks are awaiting execution, and no new tasks can be submitted.
 *
 * <p>Several concrete implementations of <tt>ThreadedExecutor</tt> are
 * included in <tt>java.util.concurrent</tt>, including <tt>ThreadPoolExecutor</tt>,
 * a flexible thread pool, and <tt>ScheduledExecutor</tt>, which adds support
 * for time-delayed and periodic execution.
 *
 * <p>The <tt>Executors</tt> class provides factory methods for the
 * executors provided in <tt>java.util.concurrent</tt>.
 *
 * @since 1.5
 * @see CannotExecuteHandler
 * @see Executors
 * @see ThreadFactory
 *
 * @spec JSR-166
 * @revised $Date: 2003/05/14 21:30:48 $
 * @editor $Author: tim $
 */
public interface ThreadedExecutor extends Executor {

    /*
     * Executor implementation. Overrides javadoc from Executor to indicate
     * that CannotExecuteHandler handles unexecutable tasks, and may throw
     * CannotExecuteException.
     */
    
    /**
     * Executes the given task sometime in the future.  The task
     * may execute in a new thread, in a pooled thread, or even in the calling
     * thread, at the discretion of the <tt>ThreadedExecutor</tt>
     * implementation.
     *
     * If the task cannot be submitted for execution, either because this
     * executor has been shutdown or because its capacity has been reached,
     * the task is handled by the current <tt>CannotExecuteHandler</tt>.  
     *
     * @param command the task to execute
     * @throws CannotExecuteException at discretion of
     * <tt>CannotExecuteHandler</tt>, if task cannot be accepted for execution
     */
    void execute(Runnable command);

    /**
     * Sets the thread factory used to create new threads.
     *
     * @param threadFactory the new thread factory
     */
    void setThreadFactory(ThreadFactory threadFactory);

    /**
     * Returns the thread factory used to create new threads.
     *
     * @return the current thread factory
     */
    ThreadFactory getThreadFactory();

    /**
     * Sets a new handler for unexecutable tasks.
     *
     * @param handler the new handler
     */
    void setCannotExecuteHandler(CannotExecuteHandler handler);

    /**
     * Returns the current handler for unexecutable tasks.
     *
     * @return the current handler
     */
    CannotExecuteHandler getCannotExecuteHandler();

    /**
     * Returns the task queue used by this executor.  Note that
     * this queue may be in active use.  Retrieveing the task queue
     * does not prevent queued tasks from executing.
     *
     * @return the task queue
     */
    BlockingQueue getQueue();

    /* Life-cycle management methods. */

    /**
     * Initiates an orderly shutdown in which previously submitted tasks
     * are executed, but no new tasks will be accepted.
     *
     * After shutdown, subsequent calls to <tt>execute</tt> will be handled
     * by the current <tt>CannotExecuteHandler</tt>, which may discard the
     * submitted tasks, or throw a <tt>CannotExecuteException</tt>,
     * among other options.
     */
    void shutdown();

    /**
     * Attempts to stop all actively executing tasks, halts the
     * processing of waiting tasks, and returns a list of the tasks that were
     * awaiting execution. As with <tt>shutdown</tt>, subsequent calls to
     * <tt>execute</tt> will be handled by the current <tt>CannotExecuteHandler</tt>.
     *  
     * <p>There are no guarantees beyond best-effort attempts to stop
     * processing actively executing tasks.  For example, typical
     * implementations will cancel via {@link Thread#interrupt}, so if any
     * tasks mask or fail to respond to interrupts, they may never terminate.
     *
     * @return list of tasks that never commenced execution
     */
    List shutdownNow();

    /**
     * Returns <tt>true</tt> if this executor has been shut down.
     *
     * @return <tt>true</tt> if this executor has been shut down
     */
    boolean isShutdown();

    /**
     * Interrupts the processing of all current tasks, while leaving this
     * executor enabled for future executions.
     * 
     * <p>Depending on whether the tasks ignore <tt>InterruptedException</tt>,
     * this method may or may not speed the completion of queued tasks,
     * and may cause improperly written tasks to fail.
     *
     * @fixme needs to document why you might want to interrupt the current task set
     */
    void interrupt();

    /**
     * Returns <tt>true</tt> if all tasks have completed following shut down.
     * Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
     * either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
     *
     * @return <tt>true</tt> if all tasks have completed following shut down
     */
    boolean isTerminated();

    /**
     * Blocks until all tasks have completed execution after a shutdown
     * request, or the timeout occurs, or the current thread is
     * interrupted, whichever happens first.
     *
     * @param timeout the maximum time to wait
     * @param granularity the time unit of the timeout argument
     * @return <tt>true</tt> if this executor terminated and <tt>false</tt>
     * if the timeout elapsed before termination
     * @throws IllegalStateException if not shut down
     * @throws InterruptedException if interrupted while waiting
     */
    boolean awaitTermination(long timeout, TimeUnit granularity)
        throws InterruptedException;
}
Revision:	1.2
Committed:	Tue May 27 18:16:20 2003 UTC (20 years, 11 months ago) by tim
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+2 -2 lines
State:	*FILE REMOVED*
Log Message:	Not needed, use TPE
#	Content
1	/*
2	* @(#)ThreadedExecutor.java
3	*/
4
5	package java.util.concurrent;
6
7	import java.util.List;
8
9	/**
10	* An executor that executes submitted tasks on one or more dedicated threads.
11	*
12	* @fixme Document ThreadFactory, CannotExecuteHandler, Queue
13	*
14	* <p>A <tt>ThreadedExecutor</tt> can be shut down, which will cause it to stop
15	* accepting new tasks. After being shut down, the executor will
16	* eventually terminate, at which point no tasks are actively executing, no
17	* tasks are awaiting execution, and no new tasks can be submitted.
18	*
19	* <p>Several concrete implementations of <tt>ThreadedExecutor</tt> are
20	* included in <tt>java.util.concurrent</tt>, including <tt>ThreadPoolExecutor</tt>,
21	* a flexible thread pool, and <tt>ScheduledExecutor</tt>, which adds support
22	* for time-delayed and periodic execution.
23	*
24	* <p>The <tt>Executors</tt> class provides factory methods for the
25	* executors provided in <tt>java.util.concurrent</tt>.
26	*
27	* @since 1.5
28	* @see CannotExecuteHandler
29	* @see Executors
30	* @see ThreadFactory
31	*
32	* @spec JSR-166
33	* @revised $Date: 2003/05/14 21:30:48 $
34	* @editor $Author: tim $
35	*/
36	public interface ThreadedExecutor extends Executor {
37
38	/*
39	* Executor implementation. Overrides javadoc from Executor to indicate
40	* that CannotExecuteHandler handles unexecutable tasks, and may throw
41	* CannotExecuteException.
42	*/
43
44	/**
45	* Executes the given task sometime in the future. The task
46	* may execute in a new thread, in a pooled thread, or even in the calling
47	* thread, at the discretion of the <tt>ThreadedExecutor</tt>
48	* implementation.
49	*
50	* If the task cannot be submitted for execution, either because this
51	* executor has been shutdown or because its capacity has been reached,
52	* the task is handled by the current <tt>CannotExecuteHandler</tt>.
53	*
54	* @param command the task to execute
55	* @throws CannotExecuteException at discretion of
56	* <tt>CannotExecuteHandler</tt>, if task cannot be accepted for execution
57	*/
58	void execute(Runnable command);
59
60	/**
61	* Sets the thread factory used to create new threads.
62	*
63	* @param threadFactory the new thread factory
64	*/
65	void setThreadFactory(ThreadFactory threadFactory);
66
67	/**
68	* Returns the thread factory used to create new threads.
69	*
70	* @return the current thread factory
71	*/
72	ThreadFactory getThreadFactory();
73
74	/**
75	* Sets a new handler for unexecutable tasks.
76	*
77	* @param handler the new handler
78	*/
79	void setCannotExecuteHandler(CannotExecuteHandler handler);
80
81	/**
82	* Returns the current handler for unexecutable tasks.
83	*
84	* @return the current handler
85	*/
86	CannotExecuteHandler getCannotExecuteHandler();
87
88	/**
89	* Returns the task queue used by this executor. Note that
90	* this queue may be in active use. Retrieveing the task queue
91	* does not prevent queued tasks from executing.
92	*
93	* @return the task queue
94	*/
95	BlockingQueue getQueue();
96
97	/* Life-cycle management methods. */
98
99	/**
100	* Initiates an orderly shutdown in which previously submitted tasks
101	* are executed, but no new tasks will be accepted.
102	*
103	* After shutdown, subsequent calls to <tt>execute</tt> will be handled
104	* by the current <tt>CannotExecuteHandler</tt>, which may discard the
105	* submitted tasks, or throw a <tt>CannotExecuteException</tt>,
106	* among other options.
107	*/
108	void shutdown();
109
110	/**
111	* Attempts to stop all actively executing tasks, halts the
112	* processing of waiting tasks, and returns a list of the tasks that were
113	* awaiting execution. As with <tt>shutdown</tt>, subsequent calls to
114	* <tt>execute</tt> will be handled by the current <tt>CannotExecuteHandler</tt>.
115	*
116	* <p>There are no guarantees beyond best-effort attempts to stop
117	* processing actively executing tasks. For example, typical
118	* implementations will cancel via {@link Thread#interrupt}, so if any
119	* tasks mask or fail to respond to interrupts, they may never terminate.
120	*
121	* @return list of tasks that never commenced execution
122	*/
123	List shutdownNow();
124
125	/**
126	* Returns <tt>true</tt> if this executor has been shut down.
127	*
128	* @return <tt>true</tt> if this executor has been shut down
129	*/
130	boolean isShutdown();
131
132	/**
133	* Interrupts the processing of all current tasks, while leaving this
134	* executor enabled for future executions.
135	*
136	* <p>Depending on whether the tasks ignore <tt>InterruptedException</tt>,
137	* this method may or may not speed the completion of queued tasks,
138	* and may cause improperly written tasks to fail.
139	*
140	* @fixme needs to document why you might want to interrupt the current task set
141	*/
142	void interrupt();
143
144	/**
145	* Returns <tt>true</tt> if all tasks have completed following shut down.
146	* Note that <tt>isTerminated</tt> is never <tt>true</tt> unless
147	* either <tt>shutdown</tt> or <tt>shutdownNow</tt> was called first.
148	*
149	* @return <tt>true</tt> if all tasks have completed following shut down
150	*/
151	boolean isTerminated();
152
153	/**
154	* Blocks until all tasks have completed execution after a shutdown
155	* request, or the timeout occurs, or the current thread is
156	* interrupted, whichever happens first.
157	*
158	* @param timeout the maximum time to wait
159	* @param granularity the time unit of the timeout argument
160	* @return <tt>true</tt> if this executor terminated and <tt>false</tt>
161	* if the timeout elapsed before termination
162	* @throws IllegalStateException if not shut down
163	* @throws InterruptedException if interrupted while waiting
164	*/
165	boolean awaitTermination(long timeout, TimeUnit granularity)
166	throws InterruptedException;
167	}