Skip to end of metadata
Go to start of metadata

Threads preserve class invariants when they are allowed to exit normally. Programmers often attempt to terminate threads abruptly when they believe the task is complete, the request has been canceled, or the program or Java Virtual Machine (JVM) must shut down expeditiously.

Certain thread APIs were introduced to facilitate thread suspension, resumption, and termination but were later deprecated because of inherent design weaknesses. For example, the Thread.stop() method causes the thread to immediately throw a ThreadDeath exception, which usually stops the thread. More information about deprecated methods is available in MET02-J. Do not use deprecated or obsolete classes or methods.

Invoking Thread.stop() results in the release of all locks a thread has acquired, potentially exposing the objects protected by those locks when those objects are in an inconsistent state. The thread might catch the ThreadDeath exception and use a finally block in an attempt to repair the inconsistent object or objects. However, doing so requires careful inspection of all synchronized methods and blocks because a ThreadDeath exception can be thrown at any point during the thread's execution. Furthermore, code must be protected from ThreadDeath exceptions that might occur while executing catch or finally blocks [Sun 1999]. Consequently, programs must not invoke Thread.stop().

Removing the java.lang.RuntimePermission stopThread permission from the security policy file prevents threads from being stopped using the Thread.stop() method. Although this approach guarantees that the program cannot use the Thread.stop() method, it is nevertheless strongly discouraged. Existing trusted, custom-developed code that uses the Thread.stop() method presumably depends on the ability of the system to perform this action. Furthermore, the system might fail to correctly handle the resulting security exception. Additionally, third-party libraries may also depend on use of the Thread.stop() method.

Refer to ERR09-J. Do not allow untrusted code to terminate the JVM for information on preventing data corruption when the JVM is abruptly shut down.

Noncompliant Code Example (Deprecated Thread.stop())

This noncompliant code example shows a thread that fills a vector with pseudorandom numbers. The thread is forcefully stopped after a given amount of time.

public final class Container implements Runnable {
  private final Vector<Integer> vector = new Vector<Integer>(1000);

  public Vector<Integer> getVector() {
    return vector;
  }

  @Override public synchronized void run() {
    Random number = new Random(123L);
    int i = vector.capacity();
    while (i > 0) {
      vector.add(number.nextInt(100));
      i--;
    }
  }

  public static void main(String[] args) throws InterruptedException {
    Thread thread = new Thread(new Container());
    thread.start();
    Thread.sleep(5000);
    thread.stop();
  }
}

Because the Vector class is thread-safe, operations performed by multiple threads on its shared instance are expected to leave it in a consistent state. For instance, the Vector.size() method always returns the correct number of elements in the vector, even after concurrent changes to the vector, because the vector instance uses its own intrinsic lock to prevent other threads from accessing it while its state is temporarily inconsistent.

However, the Thread.stop() method causes the thread to stop what it is doing and throw a ThreadDeath exception. All acquired locks are subsequently released [API 2014]. If the thread were in the process of adding a new integer to the vector when it was stopped, the vector would become accessible while it is in an inconsistent state. For example, this could result in Vector.size() returning an incorrect element count because the element count is incremented after adding the element.

Compliant Solution (volatile flag)

This compliant solution uses a volatile flag to request thread termination. The shutdown() accessor method is used to set the flag to true. The thread's run() method polls the done flag and terminates when it is set.

public final class Container implements Runnable {
  private final Vector<Integer> vector = new Vector<Integer>(1000);
  private volatile boolean done = false;

  public Vector<Integer> getVector() {
    return vector;
  }

  public void shutdown() {
    done = true;
  }

  @Override public synchronized void run() {
    Random number = new Random(123L);
    int i = vector.capacity();
    while (!done && i > 0) {
      vector.add(number.nextInt(100));
      i--;
    }
  }

  public static void main(String[] args) throws InterruptedException {
    Container container = new Container();
    Thread thread = new Thread(container);
    thread.start();
    Thread.sleep(5000);
    container.shutdown();
  }
}

Compliant Solution (Interruptible)

In this compliant solution, the Thread.interrupt() method is called from main() to terminate the thread. Invoking Thread.interrupt() sets an internal interrupt status flag. The thread polls that flag using the Thread.interrupted() method, which both returns true if the current thread has been interrupted and clears the interrupt status flag.

public final class Container implements Runnable {
  private final Vector<Integer> vector = new Vector<Integer>(1000);

  public Vector<Integer> getVector() {
    return vector;
  }

  @Override public synchronized void run() {
    Random number = new Random(123L);
    int i = vector.capacity();
    while (!Thread.interrupted() && i > 0) {
      vector.add(number.nextInt(100));
      i--;
    }
  }

  public static void main(String[] args) throws InterruptedException {
    Container c = new Container();
    Thread thread = new Thread(c);
    thread.start();
    Thread.sleep(5000);
    thread.interrupt();
  }
}

A thread may use interruption for performing tasks other than cancellation and shutdown. Consequently, a thread should be interrupted only when its interruption policy is known in advance. Failure to do so can result in failed interruption requests.

Risk Assessment

Forcing a thread to stop can result in inconsistent object state. Critical resources could also leak if cleanup operations are not carried out as required.

Rule

Severity

Likelihood

Remediation Cost

Priority

Level

THI05-J

Low

Probable

Medium

P4

L3

Automated Detection

ToolVersionCheckerDescription
Parasoft Jtest 10.3 TRS.THRDImplemented

Related Guidelines

Android Implementation Details

On Android, Thread.stop() was deprecated in API level 1.

Bibliography

[API 2006]

Class Thread, Method stop
InterfaceExecutorService

[Darwin 2004]

Section 24.3, "Stopping a Thread"

[Goetz 2006]

Chapter 7, "Cancellation and Shutdown"

[JavaThreads 2004]

Section 2.4, "Two Approaches to Stopping a Thread"

[JDK7 2008]

Concurrency Utilities, More information: Java Thread Primitive Deprecation

[JPL 2006]

Section 14.12.1, "Don't Stop"
Section 23.3.3, "Shutdown Strategies"

[Sun 1999]

 

 


11 Comments

  1. Here is some text from the JDK7 docs -

    In addition to all of the problems noted above, this method [Thread.stop()] 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 throw operation, but circumvents the compiler's attempts to guarantee that the calling method has declared all of the checked exceptions that it may throw:

        static void sneakyThrow(Throwable t) {
            Thread.currentThread().stop(t);
        }
    

    We could use this as a separate rule that warns against such silent exceptions if there are more cases like this. If anyone remembers any from the top of the head (or otherwise), please do write.

    1. Off the top of my head, undeclared checked exceptions can also be thrown by:

      • Producing class files with something other than javac.
      • Using javac twice with different versions of the caller class.
      • Class.newInstance (use Constructor.newInstance instead).
      • Unchecked cast (produces a compiler warning unless supressed) of a generic type with parameterised exception declaration:
      interface Thr<EXC extends Exception> {
          void fn() throws EXC;
      }
      
      static void undeclaredThrow() throws RuntimeException {
          Thr<RuntimeException> thr = (Thr<RuntimeException>)(Thr)
              new Thr<IOException>() {
                  public void fn() throws IOException {
                      throw new IOException();
                  }
              };
          thr.fn();
      }
      
  2. Throwing a ThreadDeath error to stop a thread is considered bad practice, however, the finally block is still executed. Assuming consistency of object state is maintained there, this may not be an issue.

  3. The NCE uses a deprecated method Thread.stop(). Not sure if this qualifies and how I can suggest better solutions without this NCE. Perhaps this whole guideline belongs in MET15-J. Do not use deprecated or obsolete methods.

  4. The blocking I/O NCEs are less appealing because they share a socket between multiple threads. This is essentially coarse grained locking and violates LCK09-J. Do not perform operations that may block while holding a lock. A better idea is to leave the socket local to the method in the NCEs so that each thread has its own copy. But then we cannot provide ths shutdown method in the CS. Consequently, the CS can solve the problem by using a static thread local and providing a way to shut down the socket.

    1. In the 2nd NCCE/CS code samples, the socket object is private to the class; consequently the socket is only accessible to the thread running the run() method. In the CS closure of the socket is encapsulated in the shutdown() method; hence no socket-sharing is going on. So the only way you can relate this rule to CON20 is the implicit locking that goes on when a socket blocks on input, which is what this rule is all about.

      1. I've added an isRunning flag to prevent multiple threads from blocking on the socket.

  5. In the new title "Ensure that threads are properly terminated", what does properly constitute? Is thread cancellation proper termination (cancellation != forced thread shutdown != Thread.stop())? This guideline only talks about cleanly stopping threads as opposed to cleanly canceling threads. So the title was - "Ensure that threads are stopped cleanly".

  6. I wonder if Thread.stop() would be appropriate in the following case: We build a tool that consists of a complex parser and an outer control loop. Although we are careful (and check for interruption etc.), there's always a chance that the parser will enter an infinite loop. If so, the control loop kills the parser with Thread.stop(). Because there is no connection between the two parts of our tool (locking, shared data structures, ...), I see no problem in doing so. The only other option I see is starting the parser in its own JVM, which is then killed in case.

    1. I suppose with sufficient work, you can argue that Thread.stop() is appropriate in cancelling a specific thread. In order to do that you must know the following:

      1. The thread cannot be stopped while in a section of code that must not throw an exception...such as in a finally clause.
      2. The details of how Thread.stop() does its work. This includes details of your JVM and OS...and hardware most likely.

      I suspect that having a sufficient understanding of these factors will be very difficult...harder than understanding why your control loop might freeze and preventing that.