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/02/26 10:53:21 $
 * @editor $Author: jozart $
 */
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.1
Committed:	Wed May 14 21:30:48 2003 UTC (21 years ago) by tim
Branch:	MAIN
Log Message:	Moved main source rooted at . to ./src/main Moved test source rooted at ./etc/testcases to ./src/test
#	User	Rev	Content
1	tim	1.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/02/26 10:53:21 $
34			* @editor $Author: jozart $
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			}