util/concurrent/Cancellable.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;

/**
 * Something, usually a task, that can be cancelled.  Cancellation is
 * performed by the <tt>cancel</tt> method.  Additional methods are
 * provided to determine if the task completed normally or was
 * cancelled.
 *
 * @since 1.5
 *
 * @spec JSR-166
 * @revised $Date: 2003/06/21 12:23:28 $
 * @editor $Author: dl $
 * @see FutureTask
 * @see Executor
 */
public interface Cancellable {

    /**
     * Attempt to cancel execution of this task.  This attempt will
     * fail if the task has already completed, already been cancelled, or could not be
     * cancelled for some other reason. If successful, and this task
     * has not started when <tt>cancel</tt> is called, this task will
     * never run.  If the task has already started, then the
     * <tt>interruptIfRunning</tt> parameter determines whether the
     * thread executing this task should be interrupted in an attempt
     * to stop the task.
     *
     * @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
     * task should be interrupted; otherwise, in-progress tasks are allowed
     * to complete
     * @return <tt>false</tt> if the task could not be cancelled,
     * typically because is has already completed normally;
     * <tt>true</tt> otherwise
     */
    boolean cancel(boolean mayInterruptIfRunning);

    /**
     * Returns <tt>true</tt> if this task was cancelled before it completed
     * normally.
     *
     * @return <tt>true</tt> if task was cancelled before it completed
     */
    boolean isCancelled();

    /**
     * Returns <tt>true</tt> if this task ran to completion or was cancelled.
     *
     * @return <tt>true</tt> if task completed normally or was cancelled
     */
    boolean isDone();
}
Revision:	1.6
Committed:	Mon Jun 23 02:26:16 2003 UTC (20 years, 11 months ago) by brian
Branch:	MAIN
Changes since 1.5:	+7 -5 lines
Log Message:	Partial javadoc pass
#	User	Rev	Content
1	tim	1.1	/*
2	dl	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	tim	1.1	*/
6
7			package java.util.concurrent;
8
9			/**
10	brian	1.6	* Something, usually a task, that can be cancelled. Cancellation is
11	dl	1.3	* performed by the <tt>cancel</tt> method. Additional methods are
12			* provided to determine if the task completed normally or was
13			* cancelled.
14	tim	1.1	*
15			* @since 1.5
16			*
17			* @spec JSR-166
18	brian	1.6	* @revised $Date: 2003/06/21 12:23:28 $
19			* @editor $Author: dl $
20			* @see FutureTask
21			* @see Executor
22	tim	1.1	*/
23			public interface Cancellable {
24
25			/**
26	brian	1.6	* Attempt to cancel execution of this task. This attempt will
27			* fail if the task has already completed, already been cancelled, or could not be
28	dl	1.5	* cancelled for some other reason. If successful, and this task
29			* has not started when <tt>cancel</tt> is called, this task will
30			* never run. If the task has already started, then the
31			* <tt>interruptIfRunning</tt> parameter determines whether the
32			* thread executing this task should be interrupted in an attempt
33			* to stop the task.
34	tim	1.1	*
35	jozart	1.4	* @param mayInterruptIfRunning <tt>true</tt> if the thread executing this
36	tim	1.1	* task should be interrupted; otherwise, in-progress tasks are allowed
37			* to complete
38	dl	1.5	* @return <tt>false</tt> if the task could not be cancelled,
39			* typically because is has already completed normally;
40			* <tt>true</tt> otherwise
41	tim	1.1	*/
42			boolean cancel(boolean mayInterruptIfRunning);
43
44			/**
45			* Returns <tt>true</tt> if this task was cancelled before it completed
46			* normally.
47			*
48			* @return <tt>true</tt> if task was cancelled before it completed
49			*/
50			boolean isCancelled();
51
52			/**
53			* Returns <tt>true</tt> if this task ran to completion or was cancelled.
54			*
55			* @return <tt>true</tt> if task completed normally or was cancelled
56			*/
57			boolean isDone();
58			}