8178101: Migrate the thread deprecation technote to javadoc doc-files
Reviewed-by: dholmes
This commit is contained in:
parent
779aa6fe36
commit
04f6757027
jdk/src/java.base/share/classes/java/lang
@ -927,7 +927,7 @@ class Thread implements Runnable {
|
||||
* for example), the <code>interrupt</code> method should be used to
|
||||
* interrupt the wait.
|
||||
* For more information, see
|
||||
* <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
|
||||
* <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
|
||||
* are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
|
||||
*/
|
||||
@Deprecated(since="1.2")
|
||||
@ -960,7 +960,7 @@ class Thread implements Runnable {
|
||||
* could be used to generate exceptions that the target thread was
|
||||
* not prepared to handle.
|
||||
* For more information, see
|
||||
* <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
|
||||
* <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
|
||||
* are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
|
||||
* This method is subject to removal in a future version of Java SE.
|
||||
*/
|
||||
@ -1082,7 +1082,7 @@ class Thread implements Runnable {
|
||||
* If another thread ever attempted to lock this resource, deadlock
|
||||
* would result. Such deadlocks typically manifest themselves as
|
||||
* "frozen" processes. For more information, see
|
||||
* <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">
|
||||
* <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">
|
||||
* Why are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
|
||||
* This method is subject to removal in a future version of Java SE.
|
||||
* @throws NoSuchMethodError always
|
||||
@ -1122,7 +1122,7 @@ class Thread implements Runnable {
|
||||
* monitor prior to calling <code>resume</code>, deadlock results. Such
|
||||
* deadlocks typically manifest themselves as "frozen" processes.
|
||||
* For more information, see
|
||||
* <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
|
||||
* <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
|
||||
* are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
|
||||
*/
|
||||
@Deprecated(since="1.2")
|
||||
@ -1148,7 +1148,7 @@ class Thread implements Runnable {
|
||||
* @deprecated This method exists solely for use with {@link #suspend},
|
||||
* which has been deprecated because it is deadlock-prone.
|
||||
* For more information, see
|
||||
* <a href="{@docRoot}/../technotes/guides/concurrency/threadPrimitiveDeprecation.html">Why
|
||||
* <a href="{@docRoot}/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
|
||||
* are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
|
||||
*/
|
||||
@Deprecated(since="1.2")
|
||||
|
@ -0,0 +1,364 @@
|
||||
<!--
|
||||
Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
|
||||
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||||
|
||||
This code is free software; you can redistribute it and/or modify it
|
||||
under the terms of the GNU General Public License version 2 only, as
|
||||
published by the Free Software Foundation. Oracle designates this
|
||||
particular file as subject to the "Classpath" exception as provided
|
||||
by Oracle in the LICENSE file that accompanied this code.
|
||||
|
||||
This code is distributed in the hope that it will be useful, but WITHOUT
|
||||
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||||
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
||||
version 2 for more details (a copy is included in the LICENSE file that
|
||||
accompanied this code).
|
||||
|
||||
You should have received a copy of the GNU General Public License version
|
||||
2 along with this work; if not, write to the Free Software Foundation,
|
||||
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
||||
|
||||
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
||||
or visit www.oracle.com if you need additional information or have any
|
||||
questions.
|
||||
-->
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>Java Thread Primitive Deprecation</title>
|
||||
<link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style">
|
||||
</head>
|
||||
<body>
|
||||
<h2>Java Thread Primitive Deprecation</h2>
|
||||
<hr size="3" noshade="noshade" />
|
||||
<h3>Why is <code>Thread.stop</code> deprecated?</h3>
|
||||
<p>Because it is inherently unsafe. Stopping a thread causes it to
|
||||
unlock all the monitors that it has locked. (The monitors are
|
||||
unlocked as the <code>ThreadDeath</code> exception propagates up
|
||||
the stack.) If any of the objects previously protected by these
|
||||
monitors were in an inconsistent state, other threads may now view
|
||||
these objects in an inconsistent state. Such objects are said to be
|
||||
<i>damaged</i>. When threads operate on damaged objects, arbitrary
|
||||
behavior can result. This behavior may be subtle and difficult to
|
||||
detect, or it may be pronounced. Unlike other unchecked exceptions,
|
||||
<code>ThreadDeath</code> kills threads silently; thus, the user has
|
||||
no warning that his program may be corrupted. The corruption can
|
||||
manifest itself at any time after the actual damage occurs, even
|
||||
hours or days in the future.</p>
|
||||
<hr />
|
||||
<h3>Couldn't I just catch the <code>ThreadDeath</code> exception
|
||||
and fix the damaged object?</h3>
|
||||
<p>In theory, perhaps, but it would <em>vastly</em> complicate the
|
||||
task of writing correct multithreaded code. The task would be
|
||||
nearly insurmountable for two reasons:</p>
|
||||
<ol>
|
||||
<li>A thread can throw a <code>ThreadDeath</code> exception
|
||||
<i>almost anywhere</i>. All synchronized methods and blocks would
|
||||
have to be studied in great detail, with this in mind.</li>
|
||||
<li>A thread can throw a second <code>ThreadDeath</code> exception
|
||||
while cleaning up from the first (in the <code>catch</code> or
|
||||
<code>finally</code> clause). Cleanup would have to be repeated till
|
||||
it succeeded. The code to ensure this would be quite complex.</li>
|
||||
</ol>
|
||||
In sum, it just isn't practical.
|
||||
<hr />
|
||||
<h3>What about <code>Thread.stop(Throwable)</code>?</h3>
|
||||
<p>In addition to all of the problems noted above, this method may
|
||||
be used to generate exceptions that its target thread is unprepared
|
||||
to handle (including checked exceptions that the thread could not
|
||||
possibly throw, were it not for this method). For example, the
|
||||
following method is behaviorally identical to Java's
|
||||
<code>throw</code> operation, but circumvents the compiler's
|
||||
attempts to guarantee that the calling method has declared all of
|
||||
the checked exceptions that it may throw:</p>
|
||||
<pre>
|
||||
static void sneakyThrow(Throwable t) {
|
||||
Thread.currentThread().stop(t);
|
||||
}
|
||||
</pre>
|
||||
<hr />
|
||||
<h3>What should I use instead of <code>Thread.stop</code>?</h3>
|
||||
<p>Most uses of <code>stop</code> should be replaced by code that
|
||||
simply modifies some variable to indicate that the target thread
|
||||
should stop running. The target thread should check this variable
|
||||
regularly, and return from its run method in an orderly fashion if
|
||||
the variable indicates that it is to stop running. To ensure prompt
|
||||
communication of the stop-request, the variable must be
|
||||
<tt>volatile</tt> (or access to the variable must be
|
||||
synchronized).</p>
|
||||
<p>For example, suppose your applet contains the following
|
||||
<code>start</code>, <code>stop</code> and <code>run</code>
|
||||
methods:</p>
|
||||
<pre>
|
||||
private Thread blinker;
|
||||
|
||||
public void start() {
|
||||
blinker = new Thread(this);
|
||||
blinker.start();
|
||||
}
|
||||
|
||||
public void stop() {
|
||||
blinker.stop(); // UNSAFE!
|
||||
}
|
||||
|
||||
public void run() {
|
||||
while (true) {
|
||||
try {
|
||||
Thread.sleep(interval);
|
||||
} catch (InterruptedException e){
|
||||
}
|
||||
repaint();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
You can avoid the use of <code>Thread.stop</code> by replacing the
|
||||
applet's <code>stop</code> and <code>run</code> methods with:
|
||||
<pre>
|
||||
private volatile Thread blinker;
|
||||
|
||||
public void stop() {
|
||||
blinker = null;
|
||||
}
|
||||
|
||||
public void run() {
|
||||
Thread thisThread = Thread.currentThread();
|
||||
while (blinker == thisThread) {
|
||||
try {
|
||||
Thread.sleep(interval);
|
||||
} catch (InterruptedException e){
|
||||
}
|
||||
repaint();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<hr />
|
||||
<h3>How do I stop a thread that waits for long periods (e.g., for
|
||||
input)?</h3>
|
||||
<p>That's what the <code>Thread.interrupt</code> method is for. The
|
||||
same "state based" signaling mechanism shown above can be used, but
|
||||
the state change (<code>blinker = null</code>, in the previous
|
||||
example) can be followed by a call to
|
||||
<code>Thread.interrupt</code>, to interrupt the wait:</p>
|
||||
<pre>
|
||||
public void stop() {
|
||||
Thread moribund = waiter;
|
||||
waiter = null;
|
||||
moribund.interrupt();
|
||||
}
|
||||
</pre>
|
||||
For this technique to work, it's critical that any method that
|
||||
catches an interrupt exception and is not prepared to deal with it
|
||||
immediately reasserts the exception. We say <em>reasserts</em>
|
||||
rather than <em>rethrows</em>, because it is not always possible to
|
||||
rethrow the exception. If the method that catches the
|
||||
<code>InterruptedException</code> is not declared to throw this
|
||||
(checked) exception, then it should "reinterrupt itself" with the
|
||||
following incantation:
|
||||
<pre>
|
||||
Thread.currentThread().interrupt();
|
||||
</pre>
|
||||
This ensures that the Thread will reraise the
|
||||
<code>InterruptedException</code> as soon as it is able.
|
||||
<hr />
|
||||
<h3>What if a thread doesn't respond to
|
||||
<code>Thread.interrupt</code>?</h3>
|
||||
<p>In some cases, you can use application specific tricks. For
|
||||
example, if a thread is waiting on a known socket, you can close
|
||||
the socket to cause the thread to return immediately.
|
||||
Unfortunately, there really isn't any technique that works in
|
||||
general. <em>It should be noted that in all situations where a
|
||||
waiting thread doesn't respond to <code>Thread.interrupt</code>, it
|
||||
wouldn't respond to <code>Thread.stop</code> either.</em> Such
|
||||
cases include deliberate denial-of-service attacks, and I/O
|
||||
operations for which thread.stop and thread.interrupt do not work
|
||||
properly.</p>
|
||||
<hr />
|
||||
<h3>Why are <code>Thread.suspend</code> and
|
||||
<code>Thread.resume</code> deprecated?</h3>
|
||||
<p><code>Thread.suspend</code> is inherently deadlock-prone. If the
|
||||
target thread holds a lock on the monitor protecting a critical
|
||||
system resource when it is suspended, no thread can access this
|
||||
resource until the target thread is resumed. If the thread that
|
||||
would resume the target thread attempts to lock this monitor prior
|
||||
to calling <code>resume</code>, deadlock results. Such deadlocks
|
||||
typically manifest themselves as "frozen" processes.</p>
|
||||
<hr />
|
||||
<h3>What should I use instead of <code>Thread.suspend</code> and
|
||||
<code>Thread.resume</code>?</h3>
|
||||
<p>As with <code>Thread.stop</code>, the prudent approach is to
|
||||
have the "target thread" poll a variable indicating the desired
|
||||
state of the thread (active or suspended). When the desired state
|
||||
is suspended, the thread waits using <code>Object.wait</code>. When
|
||||
the thread is resumed, the target thread is notified using
|
||||
<code>Object.notify</code>.</p>
|
||||
<p>For example, suppose your applet contains the following
|
||||
mousePressed event handler, which toggles the state of a thread
|
||||
called <code>blinker</code>:</p>
|
||||
<pre>
|
||||
private boolean threadSuspended;
|
||||
|
||||
Public void mousePressed(MouseEvent e) {
|
||||
e.consume();
|
||||
|
||||
if (threadSuspended)
|
||||
blinker.resume();
|
||||
else
|
||||
blinker.suspend(); // DEADLOCK-PRONE!
|
||||
|
||||
threadSuspended = !threadSuspended;
|
||||
}
|
||||
</pre>
|
||||
You can avoid the use of <code>Thread.suspend</code> and
|
||||
<code>Thread.resume</code> by replacing the event handler above
|
||||
with:
|
||||
<pre>
|
||||
public synchronized void mousePressed(MouseEvent e) {
|
||||
e.consume();
|
||||
|
||||
threadSuspended = !threadSuspended;
|
||||
|
||||
if (!threadSuspended)
|
||||
notify();
|
||||
}
|
||||
</pre>
|
||||
and adding the following code to the "run loop":
|
||||
<pre>
|
||||
synchronized(this) {
|
||||
while (threadSuspended)
|
||||
wait();
|
||||
}
|
||||
</pre>
|
||||
The <code>wait</code> method throws the
|
||||
<code>InterruptedException</code>, so it must be inside a <code>try
|
||||
... catch</code> clause. It's fine to put it in the same clause as
|
||||
the <code>sleep</code>. The check should follow (rather than
|
||||
precede) the <code>sleep</code> so the window is immediately
|
||||
repainted when the thread is "resumed." The resulting
|
||||
<code>run</code> method follows:
|
||||
<pre>
|
||||
public void run() {
|
||||
while (true) {
|
||||
try {
|
||||
Thread.sleep(interval);
|
||||
|
||||
synchronized(this) {
|
||||
while (threadSuspended)
|
||||
wait();
|
||||
}
|
||||
} catch (InterruptedException e){
|
||||
}
|
||||
repaint();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
Note that the <code>notify</code> in the <code>mousePressed</code>
|
||||
method and the <code>wait</code> in the <code>run</code> method are
|
||||
inside <code>synchronized</code> blocks. This is required by the
|
||||
language, and ensures that <code>wait</code> and
|
||||
<code>notify</code> are properly serialized. In practical terms,
|
||||
this eliminates race conditions that could cause the "suspended"
|
||||
thread to miss a <code>notify</code> and remain suspended
|
||||
indefinitely.
|
||||
<p>While the cost of synchronization in Java is decreasing as the
|
||||
platform matures, it will never be free. A simple trick can be used
|
||||
to remove the synchronization that we've added to each iteration of
|
||||
the "run loop." The synchronized block that was added is replaced
|
||||
by a slightly more complex piece of code that enters a synchronized
|
||||
block only if the thread has actually been suspended:</p>
|
||||
<pre>
|
||||
if (threadSuspended) {
|
||||
synchronized(this) {
|
||||
while (threadSuspended)
|
||||
wait();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<p>In the absence of explicit synchronization,
|
||||
<tt>threadSuspended</tt> must be made <tt>volatile</tt> to ensure
|
||||
prompt communication of the suspend-request.</p>
|
||||
The resulting <code>run</code> method is:
|
||||
<pre>
|
||||
private volatile boolean threadSuspended;
|
||||
|
||||
public void run() {
|
||||
while (true) {
|
||||
try {
|
||||
Thread.sleep(interval);
|
||||
|
||||
if (threadSuspended) {
|
||||
synchronized(this) {
|
||||
while (threadSuspended)
|
||||
wait();
|
||||
}
|
||||
}
|
||||
} catch (InterruptedException e){
|
||||
}
|
||||
repaint();
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
<hr size="3" noshade="noshade" />
|
||||
<h3>Can I combine the two techniques to produce a thread that may
|
||||
be safely "stopped" or "suspended"?</h3>
|
||||
Yes, it's reasonably straightforward. The one subtlety is that the
|
||||
target thread may already be suspended at the time that another
|
||||
thread tries to stop it. If the <tt>stop</tt> method merely sets
|
||||
the state variable (<tt>blinker</tt>) to null, the target thread
|
||||
will remain suspended (waiting on the monitor), rather than exiting
|
||||
gracefully as it should. If the applet is restarted, multiple
|
||||
threads could end up waiting on the monitor at the same time,
|
||||
resulting in erratic behavior.
|
||||
<p>To rectify this situation, the <tt>stop</tt> method must ensure
|
||||
that the target thread resumes immediately if it is suspended. Once
|
||||
the target thread resumes, it must recognize immediately that it
|
||||
has been stopped, and exit gracefully. Here's how the resulting
|
||||
<tt>run</tt> and <tt>stop</tt> methods look:</p>
|
||||
<pre>
|
||||
public void run() {
|
||||
Thread thisThread = Thread.currentThread();
|
||||
while (blinker == thisThread) {
|
||||
try {
|
||||
Thread.sleep(interval);
|
||||
|
||||
synchronized(this) {
|
||||
while (threadSuspended && blinker==thisThread)
|
||||
wait();
|
||||
}
|
||||
} catch (InterruptedException e){
|
||||
}
|
||||
repaint();
|
||||
}
|
||||
}
|
||||
|
||||
public synchronized void stop() {
|
||||
blinker = null;
|
||||
notify();
|
||||
}
|
||||
</pre>
|
||||
If the <tt>stop</tt> method calls <tt>Thread.interrupt</tt>, as
|
||||
described above, it needn't call <tt>notify</tt> as well, but it
|
||||
still must be synchronized. This ensures that the target thread
|
||||
won't miss an interrupt due to a race condition.
|
||||
<hr />
|
||||
<h3>What about <code>Thread.destroy</code>?</h3>
|
||||
<code>Thread.destroy</code> was never implemented and has been
|
||||
deprecated. If it were implemented, it would be deadlock-prone in
|
||||
the manner of <code>Thread.suspend</code>. (In fact, it is roughly
|
||||
equivalent to <code>Thread.suspend</code> without the possibility
|
||||
of a subsequent <code>Thread.resume</code>.)
|
||||
<hr />
|
||||
<h3>Why is <code>Runtime.runFinalizersOnExit</code>
|
||||
deprecated?</h3>
|
||||
Because it is inherently unsafe. It may result in finalizers being
|
||||
called on live objects while other threads are concurrently
|
||||
manipulating those objects, resulting in erratic behavior or
|
||||
deadlock. While this problem could be prevented if the class whose
|
||||
objects are being finalized were coded to "defend against" this
|
||||
call, most programmers do <i>not</i> defend against it. They assume
|
||||
that an object is dead at the time that its finalizer is called.
|
||||
<p>Further, the call is not "thread-safe" in the sense that it sets
|
||||
a VM-global flag. This forces <i>every</i> class with a finalizer
|
||||
to defend against the finalization of live objects!</p>
|
||||
<p><!-- Body text ends here --></p>
|
||||
</body>
|
||||
</html>
|
Loading…
x
Reference in New Issue
Block a user