To create a thread of control, you start by creating a Thread object:

Thread worker = new Thread();

After a Thread object is created, you can configure it and then run it. Configuring a thread involves setting its initial priority, name, and so on. When the thread is ready to run, you invoke its start method. The start method spawns a new thread of control based on the data in the Thread object, then returns. Now the virtual machine invokes the new thread's run method, making the thread active. You can invoke start only once for each thread—invoking it again results in an IllegalThreadStateException.

When a thread's run method returns, the thread has exited. You can request that a thread cease running by invoking its interrupt method—a request a well-written thread will always respond to. While a thread is running you can interact with it in other ways, as you shall soon see.

The standard implementation of Thread.run does nothing. To get a thread that does something you must either extend Thread to provide a new run method or create a Runnable object and pass it to the thread's constructor. We first discuss how to create new kinds of threads by extending Thread. We describe how to use Runnable in the next section.

Here is a simple two-threaded program that prints the words “ping” and “PONG” at different rates:

public class PingPong extends Thread {
    private String word;  // what word to print
    private int delay;    // how long to pause

    public PingPong(String whatToSay, int delayTime) {
        word = whatToSay;
        delay = delayTime;
    }

    public void run() {
        try {
            for (;;) {
                System.out.print(word + " ");
                Thread.sleep(delay); // wait until next time
            }
        } catch (InterruptedException e) {
            return;             // end this thread
        }
    }
    public static void main(String[] args) {
        new PingPong("ping",  33).start(); // 1/30 second
        new PingPong("PONG", 100).start(); // 1/10 second
    }
}

We define a type of thread called PingPong. Its run method loops forever, printing its word field and sleeping for delay milliseconds. PingPong.run cannot throw exceptions because Thread.run, which it overrides, doesn't throw any exceptions. Accordingly, we must catch the InterruptedException that sleep can throw (more on InterruptedException later).

Now we can create some working threads, and PingPong.main does just that. It creates two PingPong objects, each with its own word and delay cycle, and invokes each thread object's start method. Now the threads are off and running. Here is some example output:

ping PONG ping ping PONG ping ping ping PONG ping
ping PONG ping ping ping PONG ping ping PONG ping
ping ping PONG ping ping PONG ping ping ping PONG
ping ping PONG ping ping ping PONG ping ping PONG
ping ping ping PONG ping ping PONG ping ping ping
PONG ping ping PONG ping ping ping PONG ping ping ...

You can give a thread a name, either as a String parameter to the constructor or as the parameter of a setName invocation. You can get the current name of a thread by invoking getName. Thread names are strictly for programmer convenience—they are not used by the runtime system—but a thread must have a name and so if none is specified, the runtime system will give it one, usually using a simple numbering scheme like Thread-1, Thread-2, and so on.

You can obtain the Thread object for the currently running thread by invoking the static method Thread.currentThread. There is always a currently running thread, even if you did not create one explicitly—main itself is executed by a thread created by the runtime system.

Exercise 14.1: Write a program that displays the name of the thread that executes main.

Threads abstract the concept of a worker—an entity that gets something done. The work done by a thread is packaged up in its run method. When you need to get some work done, you need both a worker and the work—the Runnable interface abstracts the concept of work and allows that work to be associated with a worker—the thread. The Runnable interface declares a single method:

public void run();

The Thread class itself implements the Runnable interface because a thread can also define a unit of work.

You have seen that Thread can be extended to provide specific computation for a thread, but this approach is awkward in many cases. First, class extension is single inheritance—if you extend a class to make it runnable in a thread, you cannot extend any other class, even if you need to. Also, if your class needs only to be runnable, inheriting all the overhead of Thread is more than you need.

Implementing Runnable is easier in many cases. You can execute a Runnable object in its own thread by passing it to a Thread constructor. If a Thread object is constructed with a Runnable object, the implementation of Thread.run will invoke the runnable object's run method.

Here is a Runnable version of the PingPong class. If you compare the versions, you will see that they look almost identical. The major differences are in the supertype (implementing Runnable versus extending Thread) and in main.

class RunPingPong implements Runnable {
    private String word;    // what word to print
    private int delay;      // how long to pause

    RunPingPong(String whatToSay, int delayTime) {
        word = whatToSay;
        delay = delayTime;
    }

    public void run() {
        try {
            for (;;) {
                System.out.print(word + " ");
                Thread.sleep(delay); // wait until next time
            }
        } catch (InterruptedException e) {
            return;             // end this thread
        }
    }

    public static void main(String[] args) {
        Runnable ping = new RunPingPong("ping",  33);
        Runnable pong = new RunPingPong("PONG", 100);
        new Thread(ping).start();
        new Thread(pong).start();
    }
}

First, a new class that implements Runnable is defined. Its implementation of the run method is the same as PingPong's. In main, two RunPingPong objects with different timings are created; a new Thread object is then created for each object and is started immediately.

Five Thread constructors enable you to specify a Runnable object:

Classes that have only a run method are not very interesting. Real classes define complete state and behavior, where having something execute in a separate thread is only a part of their functionality. For example, consider a print server that spools print requests to a printer. Clients invoke the print method to submit print jobs. But all the print method actually does is place the job in a queue and a separate thread then pulls jobs from the queue and sends them to the printer. This allows clients to submit print jobs without waiting for the actual printing to take place.

class PrintServer implements Runnable {
    private final PrintQueue requests = new PrintQueue();
    public PrintServer() {
        new Thread(this).start();
    }
    public void print(PrintJob job) {
        requests.add(job);
    }
    public void run() {
        for(;;)
            realPrint(requests.remove());
    }
    private void realPrint(PrintJob job) {
        // do the real work of printing
    }
}

When a PrintServer is created, it creates a new Thread to do the actual printing and passes itself as the Runnable instance. Starting a thread in a constructor in this way can be risky if a class can be extended. If it becomes extended, the thread could access fields of the object before the extended class constructor had been executed.

The requests queue takes care of synchronizing the different threads that access it—those calling print and our own internal thread—we look at such synchronization in later sections and define the PrintQueue class on page 356.

You may be wondering about the fact that we don't have a reference to the thread we created—doesn't that mean that the thread can be garbage collected? The answer is no. While we didn't keep a reference to the thread, when the thread itself was created, it stored a reference to itself in its ThreadGroup—we talk more about thread groups later.

The work that you define within a run method is normally of a fairly private nature—it should be performed only by the worker to whom the work was assigned. However, as part of an interface, run is public and so can be invoked indiscriminately by anyone with access to your object—something you usually don't desire. For example, we definitely don't want clients to invoke the run method of PrintServer. One solution is to use Thread.currentThread to establish the identity of the thread that invokes run and to compare it with the intended worker thread. But a simpler solution is not to implement Runnable, but to define an inner Runnable object. For example, we can rewrite PrintServer as follows:

class PrintServer2 {
    private final PrintQueue requests = new PrintQueue();
    public PrintServer2() {
        Runnable service = new Runnable() {
            public void run() {
                for(;;)
                    realPrint(requests.remove());
            }
        };
        new Thread(service).start();
    }
    public void print(PrintJob job) {
        requests.add(job);
    }
    private void realPrint(PrintJob job) {
        // do the real work of printing
    }
}

The run method is exactly the same as before, but now it is part of an anonymous inner class that implements Runnable. When the thread is created we pass service as the Runnable to execute. Now the work to be performed by the thread is completely private and can't be misused.

Using Runnable objects you can create very flexible multithreaded designs. Each Runnable becomes a unit of work and each can be passed around from one part of the system to another. We can store Runnable objects in a queue and have a pool of worker threads servicing the work requests in the queue—a very common design used in multithreaded server applications.

Exercise 14.2: Modify the first version of PrintServer so that only the thread created in the constructor can successfully execute run, using the identity of the thread as suggested.

Recall the bank teller example from the beginning of this chapter. When two tellers (threads) need to use the same file (object), there is a possibility of interleaved operations that can corrupt the data. Such potentially interfering actions are termed critical sections or critical regions, and you prevent interference by synchronizing access to those critical regions. In the bank, tellers synchronize their actions by putting notes in the files and agreeing to the protocol that a note in the file means that the file can't be used. The equivalent action in multithreading is to acquire a lock on an object. Threads cooperate by agreeing to the protocol that before certain actions can occur on an object, the lock of the object must be acquired. Acquiring the lock on an object prevents any other thread from acquiring that lock until the holder of the lock releases it. If done correctly, multiple threads won't simultaneously perform actions that could interfere with each other.

Every object has a lock associated with it, and that lock can be acquired and released through the use of synchronized methods and statements. The term synchronized code describes any code that is inside a synchronized method or statement.

synchronized Methods

A class whose objects must be protected from interference in a multithreaded environment usually has appropriate methods declared synchronized( “appropriate” is defined later). If one thread invokes a synchronized method on an object, the lock of that object is first acquired, the method body executed, and then the lock released. Another thread invoking a synchronized method on that same object will block until the lock is released:

Synchronization forces execution of the two threads to be mutually exclusive in time. Unsynchronized access does not wait for any locks but proceeds regardless of locks that may be held on the object.

Locks are owned per thread, so invoking a synchronized method from within another method synchronized on the same object will proceed without blocking, releasing the lock only when the outermost synchronized method returns. This per-thread behavior prevents a thread from blocking on a lock it already has, and permits recursive method invocations and invocations of inherited methods, which themselves may be synchronized.

The lock is released as soon as the synchronized method terminates—whether normally, with a return statement or by reaching the end of the method body, or abnormally by throwing an exception. In contrast to systems in which locks must be explicitly acquired and released, this synchronization scheme makes it impossible to forget to release a lock.

Synchronization makes the interleaved execution example work: If the code is in a synchronized method, then when the second thread attempts to access the object while the first thread is using it, the second thread is blocked until the first one finishes.

For example, if the BankAccount class were written to live in a multithreaded environment it would look like this:

public class BankAccount {
    private long number;    // account number
    private long balance;   // current balance (in cents)
    public BankAccount(long initialDeposit) {
        balance = initialDeposit;
    }
    public synchronized long getBalance() {
        return balance;
    }
    public synchronized void deposit(long amount) {
        balance += amount;
    }
    // ... rest of methods ...
}

Now we can explain what is “appropriate” in synchronizing methods.

The constructor does not need to be synchronized because it is executed only when creating an object, and that can happen in only one thread for any given new object. Constructors, in fact, cannot be declared synchronized.

The balance field is defended from unsynchronized modification by the synchronized accessor methods. If the value of a field can change, its value should never be read at the same time another thread is writing it. If one thread were reading the value while another was setting it, the read might return an invalid value. Even if the value were valid, a get–modify–set sequence requires that the value not change between being read and being set, otherwise the set value will be wrong. Access to the field must be synchronized. This is yet another reason to prefer accessor methods to public or protected fields: Using methods, you can synchronize access to the data, but you have no way to do so if the fields can be accessed directly outside your class.

With the synchronized declaration, two or more running threads are guaranteed not to interfere with each other. Each of the methods will execute in mutual exclusion—once one invocation of a method starts execution, no other invocations of any of the methods can commence until the original has completed. However, there is no guarantee as to the order of operations. If the balance is queried about the same time that a deposit occurs, one of them will complete first but you can't tell which. If you want actions to happen in a guaranteed order, threads must coordinate their activities in some application-specific way.

You can ask whether the current thread holds the lock on a given object by passing that object to the Thread class's static holdsLock method, which returns true if the current thread does hold the lock on that object. This is typically used to assert that a lock is held when needed. For example, a private method that expects to be invoked only from synchronized public methods might assert that fact:

assert Thread.holdsLock(this);

You will also occasionally find it important that a certain lock not be held in a method. And in some rare circumstances you might want to choose whether or not to acquire a given lock depending on whether or not another lock is held.

When an extended class overrides a synchronized method, the new method can be synchronized or not. The superclass's method will still be synchronized when it is invoked. If the unsynchronized method uses super to invoke the superclass's method, the object's lock will be acquired at that time and will be released when the superclass's method returns. Synchronization requirements are a part of the implementation of a class. An extended class may be able to modify a data structure such that concurrent invocations of a method do not interfere and so the method need not be synchronized; conversely the extended class may enhance the behavior of the method in such a way that interference becomes possible and so it must be synchronized.

synchronized (expr) {
    statements
}

/** make all elements in the array non-negative */
public static void abs(int[] values) {
    synchronized (values) {
        for (int i = 0; i < values.length; i++) {
            if (values[i] < 0)
                values[i] = -values[i];
        }
    }
}

class SeparateGroups {
    private double aVal = 0.0;
    private double bVal = 1.1;
    protected final Object lockA = new Object();
    protected final Object lockB = new Object();

    public double getA() {
        synchronized (lockA) {
            return aVal;
        }
    }
    public void setA(double val) {
        synchronized (lockA) {
            aVal = val;
        }
    }
    public double getB() {
        synchronized (lockB) {
            return bVal;
        }
    }
    public void setB(double val) {
        synchronized (lockB) {
            bVal = val;
        }
    }
    public void reset() {
        synchronized (lockA) {
            synchronized (lockB) {
                aVal = bVal = 0.0;
            }
        }
    }
}

public class Outer {
    private int data;
    // ...

    private class Inner {
        void setOuterData() {
            synchronized (Outer.this) {
                data = 12;
            }
        }
    }
}

Body() {
    synchronized (Body.class) {
        idNum = nextID++;
    }
}

The synchronized locking mechanism suffices for keeping threads from interfering with each other, but you also need a way to communicate between threads. For this purpose, the wait method lets one thread wait until some condition occurs, and the notification methods notifyAll and notify tell waiting threads that something has occurred that might satisfy that condition. The wait and notification methods are defined in class Object and are inherited by all classes. They apply to particular objects, just as locks do.

There is a standard pattern that is important to use with wait and notification. The thread waiting for a condition should always do something like this:

synchronized void doWhenCondition() {
    while (!condition)
        wait();
    … Do what must be done when the condition is true …
}

A number of things are going on here:

On the other side, the notification methods are invoked by synchronized code that changes one or more conditions on which some other thread may be waiting. Notification code typically looks something like this:

synchronized void changeCondition() {
    … change some value used in a condition test …
    notifyAll(); // or notify()
}

Using notifyAll wakes up all waiting threads, whereas notify picks only one thread to wake up.

Multiple threads may be waiting on the same object, possibly for different conditions. If they are waiting for different conditions, you should always use notifyAll to wake up all waiting threads instead of using notify. Otherwise, you may wake up a thread that is waiting for a different condition from the one you satisfied. That thread will discover that its condition has not been satisfied and go back to waiting, while some thread waiting on the condition you did satisfy will never get awakened. Using notify is an optimization that can be applied only when:

Otherwise you must use notifyAll. If a subclass violates either of the first two conditions, code in the superclass that uses notify may well be broken. To that end it is important that waiting and notification strategies, which include identifying the reference used (this or some other field), are documented for use by extended classes.

The following example implements the PrintQueue class that we used with the PrintServer on page 343. We reuse the SingleLinkQueue class that we defined in Chapter 11 to actually store the print jobs, and add the necessary synchronization:

class PrintQueue {
    private SingleLinkQueue<PrintJob> queue =
        new SingleLinkQueue<PrintJob>();

    public synchronized void add(PrintJob j) {
        queue.add(j);
        notifyAll();     // Tell waiters: print job added
    }

    public synchronized PrintJob remove()
        throws InterruptedException
    {
        while (queue.size() == 0)
            wait();      // Wait for a print job

        return queue.remove();
    }
}

In contrast to SingleLinkQueue itself, the methods are synchronized to avoid interference. When an item is added to the queue, waiters are notified; and instead of returning null when the queue is empty, the remove method waits for some other thread to insert something so that take will block until an item is available. Many threads (not just one) may be adding items to the queue, and many threads (again, not just one) may be removing items from the queue. Because wait can throw InterruptedException, we declare that in the throws clause—you'll learn about InterruptedException a little later.

Looking back at the PrintServer example, you can now see that although the internal thread appears to sit in an infinite loop, continually trying to remove jobs from the queue, the use of wait means that the thread is suspended whenever there is no work for it to do. In contrast, if we used a queue that returned null when empty, the printing thread would continually invoke remove, using the CPU the whole time—a situation known as busy-waiting. In a multithreaded system you very rarely want to busy-wait. You should always suspend until told that what you are waiting for may have happened. This is the essence of thread communication with the wait and notifyAll/notify mechanism.

There are three forms of wait and two forms of notification. All of them are methods in the Object class, and all are final so that their behavior cannot be changed:

If no threads are waiting when either notifyAll or notify is invoked, the notification is not remembered. If a thread subsequently decides to wait, an earlier notification will have no effect on it. Only notifications that occur after the wait commences will affect a waiting thread.

You can invoke these methods only from within synchronized code, using the lock for the object on which they are invoked. The invocation can be directly made from the synchronized code, or can be made indirectly from a method invoked in such code. You will get an IllegalMonitorStateException if you attempt to invoke these methods on an object when you don't hold its lock.

When a wait completes because the time-out period expires, there is no indication that this occurred rather than the thread being notified. If a thread needs to know whether or not it timed out, it has to track elapsed time itself. The use of a time-out is a defensive programming measure that allows you to recover when some condition should have been met but for some reason (probably a failure in another thread) has not. Because the lock of the object must be reacquired, the use of a time-out cannot guarantee that wait will return in a finite amount of time.

It is also possible that some virtual machine implementations will allow so-called “spurious wakeups” to occur—when a thread returns from wait without being the recipient of a notification, interruption, or time-out. This is another reason that wait should always be performed in a loop that tests the condition being waited on.

Exercise 14.6: Write a program that prints the elapsed time each second from the start of execution, with another thread that prints a message every fifteen seconds. Have the message-printing thread be notified by the time-printing thread as each second passes by. Add another thread that prints a different message every seven seconds without modifying the time-printing thread.

Threads perform different tasks within your programs and those tasks can have different importance levels attached to them. To reflect the importance of the tasks they are performing, each thread has a priority that is used by the runtime system to help determine which thread should be running at any given time. Programs can be run on both single- and multiprocessor machines and you can run with multiple threads or a single thread, so the thread scheduling guarantees are very general. On a system with N available processors, you will usually see N of the highest-priority runnable threads executing. Lower-priority threads generally run only when higher-priority threads are blocked (not runnable). But lower-priority threads might, in fact, run at other times to prevent starvation—a feature generally known as priority aging—though you cannot rely on it.

A running thread continues to run until it performs a blocking operation (such as wait, sleep, or some types of I/O) or it is preempted. A thread can be preempted by a higher-priority thread becoming runnable or because the thread scheduler decides it's another thread's turn to get some cycles—for example, time slicing limits the amount of time a single thread can run before being preempted.

Exactly when preemption can occur depends on the virtual machine you have. There are no guarantees, only a general expectation that preference is typically given to running higher-priority threads. Use priority only to affect scheduling policy for efficiency. Do not rely on thread priority for algorithm correctness. To write correct, cross-platform multithreaded code you must assume that a thread could be preempted at any time, and so you always protect access to shared resources. If you require that preemption occur at some specific time, you must use explicit thread communication mechanisms such as wait and notify. You also can make no assumptions about the order in which locks are granted to threads, nor the order in which waiting threads will receive notifications—these are all system dependent.

A thread's priority is initially the same as the priority of the thread that created it. You can change the priority using setPriority with a value between Thread's constants MIN_PRIORITY and MAX_PRIORITY. The standard priority for the default thread is NORM_PRIORITY. The priority of a running thread can be changed at any time. If you assign a thread a priority lower than its current one, the system may let another thread run because the original thread may no longer be among those with the highest priority. The getPriority method returns the priority of a thread.

Generally, if you are to worry about priorities at all, the continuously running part of your application should run in a lower-priority thread than the thread dealing with rarer events such as user input. When users push a “Cancel” button, for example, they expect the application to cancel what it's doing. If display update and user input are at the same priority and the display is updating, considerable time may pass before the user input thread reacts to the button. If you put the display thread at a lower priority, it will still run most of the time because the user interface thread will be blocked waiting for user input. When user input is available, the user interface thread will typically preempt the display thread to act on the user's request. For this reason, a thread that does continual updates is often set to NORM_PRIORITY-1 so that it doesn't hog all available cycles, while a user interface thread is often set to NORM_PRIORITY+1.

Using small “delta” values around the normal priority level is usually preferable to using MIN_PRIORITY or MAX_PRIORITY directly. Exactly what effect priorities have depends on the system you are running on. In some systems your thread priorities not only assign an importance relative to your program, they assign an importance relative to other applications running on the system.^[1] Extreme priority settings may result in undesirable behavior and so should be avoided unless their effects are known and needed.

Some algorithms are sensitive to the number of processors available to the virtual machine to run threads on. For example, an algorithm might split work up into smaller chunks to take advantage of more parallel processing power. The availableProcessors method of the Runtime class (see Chapter 23) returns the number of processors currently available. Note that the number of processors can change at any time, so you want to check this number when it is important rather than remember the number from a previous check.

class Babble extends Thread {
    static boolean doYield; // yield to other threads?
    static int howOften;    // how many times to print
    private String word;    // my word

    Babble(String whatToSay) {
        word = whatToSay;
    }

    public void run() {
        for (int i = 0; i < howOften; i++) {
            System.out.println(word);
            if (doYield)
                Thread.yield(); // let other threads run
        }
    }

    public static void main(String[] args) {
        doYield = new Boolean(args[0]).booleanValue();
        howOften = Integer.parseInt(args[1]);

        // create a thread for each word
        for (int i = 2; i < args.length; i++)
            new Babble(args[i]).start();
    }
}

Babble false 2 Did DidNot

Did
Did
DidNot
DidNot

Babble true 2 Did DidNot

Did
DidNot
DidNot
Did

Whenever you have two threads and two objects with locks, you can have a deadlock, in which each thread has the lock on one of the objects and is waiting for the lock on the other object. If object X has a synchronized method that invokes a synchronized method on object Y, which in turn has a synchronized method invoking a synchronized method on object X, two threads may wait for each other to complete in order to get a lock, and neither thread will be able to run. This situation is also called a deadly embrace. Here's a Friendly class in which one friend, upon being hugged, insists on hugging back:

class Friendly {
    private Friendly partner;
    private String name;

    public Friendly(String name) {
        this.name = name;
    }

    public synchronized void hug() {
        System.out.println(Thread.currentThread().getName()+
              " in " + name + ".hug() trying to invoke " +
              partner.name + ".hugBack()");
        partner.hugBack();
    }

    private synchronized void hugBack() {
        System.out.println(Thread.currentThread().getName()+
              " in " + name + ".hugBack()");
    }

    public void becomeFriend(Friendly partner) {
        this.partner = partner;
    }
}

Now consider this scenario, in which jareth and cory are two Friendly objects that have become friends:

We have now achieved deadlock: cory won't proceed until the lock on jareth is released and vice versa, so the two threads are stuck in a permanent embrace.

We can try to set up this scenario:

public static void main(String[] args) {
    final Friendly jareth = new Friendly("jareth");
    final Friendly cory = new Friendly("cory");


    jareth.becomeFriend(cory);
    cory.becomeFriend(jareth);

    new Thread(new Runnable() {
        public void run() { jareth.hug(); }
    }, "Thread1").start();

    new Thread(new Runnable() {
        public void run() { cory.hug(); }
    }, "Thread2").start();
}

And when you run the program, you might get the following output before the program “hangs”:

Thread1 in jareth.hug() trying to invoke cory.hugBack()
Thread2 in cory.hug() trying to invoke jareth.hugBack()

You could get lucky, of course, and have one thread complete the entire hug without the other one starting. If steps 2 and 3 happened to occur in the opposite order, jareth would complete both hug and hugBack before cory needed the lock on jareth. But a future run of the same application might deadlock because of a different choice of the thread scheduler. Several design changes would fix this problem. The simplest would be to make hug and hugBack not synchronized but have both methods synchronize on a single object shared by all Friendly objects. This technique would mean that only one hug could happen at a time in all the threads of a single application, but it would eliminate the possibility of deadlock. Other, more complicated techniques would enable multiple simultaneous hugs without deadlock.

You are responsible for avoiding deadlock. The runtime system neither detects nor prevents deadlocks. It can be frustrating to debug deadlock problems, so you should solve them by avoiding the possibility in your design. One common technique is to use resource ordering. With resource ordering you assign an order on all objects whose locks must be acquired and make sure that you always acquire locks in that order. This makes it impossible for two threads to hold one lock each and be trying to acquire the lock held by the other—they must both request the locks in the same order, and so once one thread has the first lock, the second thread will block trying to acquire that lock, and then the first thread can safely acquire the second lock.

Exercise 14.8: Experiment with the Friendly program. How often does the deadlock actually happen on your system? If you add yield calls, can you change the likelihood of deadlock? If you can, try this exercise on more than one kind of system. Remove the deadlock potential without getting rid of the synchronization.

A thread that has been started becomes alive and the isAlive method will return true for that thread. A thread continues to be alive until it terminates, which can occur in one of three ways:

Having run return is the normal way for a thread to terminate. Every thread performs a task and when that task is over the thread should go away. If something goes wrong, however, and an exception occurs that is not caught, then that will also terminate the thread—we look at this further in Section 14.12 on page 379. By the time a thread terminates it will not hold any locks, because all synchronized code must have been exited by the time run has completed.

A thread can also be terminated when its application terminates, which you'll learn about in “Ending Application Execution” on page 369.

Cancelling a Thread

There are often occasions when you create a thread to perform some work and then need to cancel that work before it is complete—the most obvious example being a user clicking a cancel button in a user interface. To make a thread cancellable takes a bit of work on the programmer's part, but it is a clean and safe mechanism for getting a thread to terminate. You request cancellation by interrupting the thread and by writing the thread such that it watches for, and responds to, being interrupted. For example:

Thread 1

Thread 2

Interrupting the thread advises it that you want it to pay attention, usually to get it to halt execution. An interrupt does not force the thread to halt, although it will interrupt the slumber of a sleeping or waiting thread.

Interruption is also useful when you want to give the running thread some control over when it will handle an event. For example, a display update loop might need to access some database information using a transaction and would prefer to handle a user's “cancel” after waiting until that transaction completes normally. The user-interface thread might implement a “Cancel” button by interrupting the display thread to give the display thread that control. This approach will work well as long as the display thread is well behaved and checks at the end of every transaction to see whether it has been interrupted, halting if it has.

The following methods relate to interrupting a thread: interrupt, which sends an interrupt to a thread; isInterrupted, which tests whether a thread has been interrupted; and interrupted, a static method that tests whether the current thread has been interrupted and then clears the “interrupted” state of the thread. The interrupted state of a thread can be cleared only by that thread—there is no way to “uninterrupt” another thread. There is generally little point in querying the interrupted state of another thread, so these methods tend to be used by the current thread on itself. When a thread detects that it has been interrupted, it often needs to perform some cleanup before actually responding to the interrupt. That cleanup may involve actions that could be affected if the thread is left in the inter rupted state, so the thread will test and clear its interrupted state using interrupted.

Interrupting a thread will normally not affect what it is doing, but a few methods, such as sleep and wait, throw InterruptedException. If your thread is executing one of these methods when it is interrupted, the method will throw the InterruptedException. Such a thrown interruption clears the interrupted state of the thread, so handling code for InterruptedException commonly looks like this:

void tick(int count, long pauseTime) {
    try {
        for (int i = 0; i < count; i++) {
            System.out.println('.'),
            System.out.flush();
            Thread.sleep(pauseTime);
        }
    } catch (InterruptedException e) {
        Thread.currentThread().interrupt();
    }
}

The tick method prints a dot every pauseTime milliseconds up to a maximum of count times—see “Timer and TimerTask” on page 653 for a better way to do this. If something interrupts the thread in which tick is running, sleep will throw InterruptedException. The ticking will then cease, and the catch clause will reinterrupt the thread. You could instead declare that tick itself throws InterruptedException and simply let the exception percolate upward, but then every invoker of tick would have to handle the same possibility. Reinterrupting the thread allows tick to clean up its own behavior and then let other code handle the interrupt as it normally would.

In general any method that performs a blocking operation (either directly or indirectly) should allow that blocking operation to be cancelled with interrupt and should throw an appropriate exception if that occurs. This is what sleep and wait do. In some systems, blocking I/O operations will respond to interruption by throwing InterruptedIOException (which is a subclass of the general IOException that most I/O methods can throw—see Chapter 20 for more details on I/O). Even if the interruption cannot be responded to during the I/O operation, systems may check for interruption at the start of the operation and throw the exception—hence the need for an interrupted thread to clear its interrupted state if it needs to perform I/O as part of its cleanup. In general, however, you cannot assume that interrupt will unblock a thread that is performing I/O.

Every method of every class executes in some thread, but the behavior defined by those methods generally concerns the state of the object involved, not the state of the thread executing the method. Given that, how do you write methods that will allow threads to respond to interrupts and be cancellable? If your method can block, then it should respond to interruption as just discussed. Otherwise, you must decide what interruption or cancellation would mean for your method and then make that behavior part of the methods contract—in the majority of cases methods need not concern themselves with interruption at all. The golden rule, however, is to never hide an interrupt by clearing it explicitly or by catching an InterruptedException and continuing normally—that prevents any thread from being cancellable when executing your code.

The interruption mechanism is a tool that cooperating code can use to make multithreading effective. Neither it, nor any other mechanism, can deal with hostile or malicious code.

class CalcThread extends Thread {
    private double result;

    public void run() {
        result = calculate();
    }

    public double getResult() {
        return result;
    }

    public double calculate() {
        // ... calculate a value for "result"
    }
}

class ShowJoin {
    public static void main(String[] args) {
        CalcThread calc = new CalcThread();
        calc.start();
        doSomethingElse();
        try {
            calc.join();
            System.out.println("result is "
                + calc.getResult());
        } catch (InterruptedException e) {
            System.out.println("No answer: interrupted");
        }
    }
    // ... definition of doSomethingElse ...
}

while (isAlive())
    wait();

Each application starts with one thread—the one that executes main. If your application creates no other threads, the application will finish when main returns. But if you create other threads, what happens to them when main returns?

There are two kinds of threads: user and daemon. The presence of a user thread keeps the application running, whereas a daemon thread is expendable. When the last user thread is finished, any daemon threads are terminated and the application is finished. This termination is like that of invoking destroy—abrupt and with no chance for any cleanup—so daemon threads are limited in what they can do. You use the method setDaemon(true) to mark a thread as a daemon thread, and you use isDaemon to test that flag. By default, daemon status is inherited from the thread that creates the new thread and cannot be changed after a thread is started; an IllegalThreadStateException is thrown if you try.

If your main method spawns a thread, that thread inherits the user-thread status of the original thread. When main finishes, the application will continue to run until the other thread finishes, too. There is nothing special about the original thread—it just happened to be the first one to get started for a particular run of an application, and it is treated just like any other user thread. An application will run until all user threads have completed. For all the runtime system knows, the original thread was designed to spawn another thread and die, letting the spawned thread do the real work. If you want your application to exit when the original thread dies, you can mark all the threads you create as daemon threads.

You can force an application to end by invoking either the System or Runtime method exit. This method terminates the current execution of the Java virtual machine and again is like invoking destroy on each thread. However, an application can install special threads to be run before the application shuts down—the methods for doing this are described in “Shutdown” on page 672.

Many classes implicitly create threads within an application. For example, the Abstract Window Toolkit (AWT), described briefly in Chapter 25, provides an event-based graphical user-interface and creates a special thread for dealing with all associated events. Similarly, Remote Method Invocation, also mentioned in Chapter 25, creates threads for responding to remote method invocations. Some of these threads may be daemons and others may not, so use of these classes can keep your application running longer than you may intend. In these circumstances the use of the exit method becomes essential if there is no other way to terminate the threads.

Any mutable (that is, changeable) value shared between different threads should always be accessed under synchronization to prevent interference from occurring. Synchronization comes at a cost, however, and may not always be necessary to prevent interference. The language guarantees that reading or writing any variables, other than those of type long or double, is atomic—the variable will only ever hold a value that was written by some thread, never a partial value intermixing two different writes. This means, for example, that an atomic variable that is only written by one thread and read by many threads need not have access to it synchronized to prevent corruption because there is no possibility of interference. This does not help with get–modify–set sequences (such as ++), which always require synchronization.

Atomic access does not ensure that a thread will always read the most recently written value of a variable. In fact, without synchronization, a value written by one thread may never become visible to another thread. A number of factors affect when a variable written by one thread becomes visible to another thread. Modern multiprocessing hardware can do very strange things when it comes to the way in which shared memory values get updated, as can dynamic compilation environments at runtime. Further, in the absence of synchronization the order in which variables are seen to be updated by different threads can be completely different. To the programmer these things are not only strange, they often seem completely unreasonable and invariably not what the programmer wanted. The rules that determine how memory accesses are ordered and when they are guaranteed to be visible are known as the memory model of the Java programming language.

The actions of a thread are determined by the semantics of the statements in the methods that it executes. Logically, these statements are executed in the order the statements are written—an order known as program order. However, the values of any variables read by the thread are determined by the memory model. The memory model defines the set of allowed values that can be returned when a variable is read. In this context variables consist only of fields (both static and non-static) and array elements. From a programmer's perspective this set of values should only consist of a single value: that value most recently written by some thread. However, as we shall see, in the absence of proper synchronization, the actual set of values available may consist of many different values.

For example, suppose you had a field, currentValue, that was continuously displayed by a graphics thread and that could be changed by other threads using a non-synchronized method:

public void updateCurrent() {
    currentValue = (int) Math.random();
}

The display code might look something like this:

currentValue = 5;
for (;;) {
    display.showValue(currentValue);
    Thread.sleep(1000); // wait 1 second
}

When the loop is first entered (assuming no calls to updateCurrent have occurred in other threads) the only possible value for currentValue is 5. However, because there is no synchronization, each time a thread invokes updateCurrent the new value is added to the set of possible values to be read. By the time currentValue is read in the loop, the possible values might consist of 5, 25, 42, and 326, any of which may be returned by the read. According to the rules of the memory model any value written by some thread (but not some “out of thin air” value) may be returned by the read. In practical terms, if there is no way for showValue to change the value of currentValue, the compiler can assume that it can treat currentValue as unchanged inside the loop and simply use the constant 5 each time it invokes showValue. This is consistent with the memory model because 5 is one of the available values and the memory model doesn't control which value gets returned. For the program to work as desired we have to do something such that when currentValue is written, that written value becomes the only value that the memory model will allow to be read. To do that we have to synchronize the writes and the reads of variables.

The Happens-Before Relationship

The description of synchronizations actions above is a simplification of the operation of the memory model. The use of synchronized blocks and methods and the use of volatile variables provide guarantees concerning the reading and writing of variables beyond the volatile variables themselves or the variables accessed within the synchronized block. These synchronization actions establish what is called a happens-before relationship and it is this relationship that determines what values can be returned by a read of a variable. The happens-before relationship is transitive, and a statement that occurs ahead of another in program order happens-before that second statement. This allows actions other than synchronization actions to become synchronized across threads. For example, if a non-volatile variable is written before a volatile variable, and in another thread the same volatile variable is read before reading the non-volatile variable, then the write of the non-volatile variable happens-before the read of that variable and so the read is guaranteed to return the value written. Consider the following:

If the read of dataReady by thread-2 yields true, then the write of dataReady by thread-1 happened-before that read. Since the write to data by thread-1 happens-before the write to dataReady by thread-1, it follows that it also happens-before the read of dataReady by thread-2, hence the read of data by thread-2. In short, if thread-2 sees dataReady is true then it is guaranteed to see the new Data object created by thread-1. This is true because dataReady is a volatile variable,^[2] even though data is not itself a volatile variable.

Finally, note that the actual execution order of instructions and memory accesses can be in any order as long as the actions of the thread appear to that thread as if program order were followed, and provided all values read are allowed for by the memory model. This allows the programmer to fully understand the semantics of the programs they write, and it allows compiler writers and virtual machine implementors to perform complex optimizations that a simpler memory model would not permit.

This discussion gives you an idea of how the memory model interacts with multithreading. The full details of the memory model are beyond the scope of this book. Fortunately, if you pursue a straightforward locking strategy using the tools in this book, the subtleties of the memory model will work for you and your code will be fine.

When you're programming multiple threads—some of them created by library classes—it can be useful to organize them into related groups, manage the threads in a group as a unit, and, if necessary, place limitations on what threads in different groups can do.

Threads are organized into thread groups for management and security reasons. A thread group can be contained within another thread group, providing a hierarchy—originating with the top-level or system thread group. Threads within a group can be managed as a unit, for example, by interrupting all threads in the group at once, or placing a limit on the maximum priority of threads in a group. The thread group can also be used to define a security domain. Threads within a thread group can generally modify other threads in that group, including any threads farther down the hierarchy. In this context “modifying” means invoking any method that could affect a thread's behavior—such as changing its priority, or interrupting it. However, an application can define a security policy that prevents a thread from modifying threads outside of its group. Threads within different thread groups can also be granted different permissions for performing actions within the application, such as performing I/O.

Generally speaking, security-sensitive methods always check with any installed security manager before proceeding. If the security policy in force forbids the action, the method throws a SecurityException. By default there is no security manager installed when an application starts. If your code is executed in the context of another application, however, such as an applet within a browser, you can be fairly certain that a security manager has been installed. Actions such as creating threads, controlling threads, performing I/O, or terminating an application, are all security sensitive. For further details, see “Security” on page 677.

Every thread belongs to a thread group. Each thread group is represented by a ThreadGroup object that describes the limits on threads in that group and allows the threads in the group to be interacted with as a group. You can specify the thread group for a new thread by passing it to the thread constructor. By default each new thread is placed in the same thread group as that of the thread that created it, unless a security manager specifies differently. For example, if some event-handling code in an applet creates a new thread, the security manager can make the new thread part of the applet thread group rather than the system thread group of the event-processing thread. When a thread terminates, the Thread object is removed from its group and so may be garbage collected if no other references to it remain.

There are four Thread constructors that allow you to specify the ThreadGroup of the thread. You saw three of them on page 343 when looking at Runnable. The fourth is:

To prevent threads from being created in arbitrary thread groups (which would defeat the security mechanism), these constructors can themselves throw SecurityException if the current thread is not permitted to place a thread in the specified thread group.

The ThreadGroup object associated with a thread cannot be changed after the thread is created. You can get a thread's group by invoking its getThreadGroup method. You can also check whether you are allowed to modify a Thread by invoking its checkAccess method, which throws SecurityException if you cannot modify the thread and simply returns if you can (it is a void method).

A thread group can be a daemon group—which is totally unrelated to the concept of daemon threads. A daemon ThreadGroup is automatically destroyed when it becomes empty. Setting a ThreadGroup to be a daemon group does not affect whether any thread or group contained in that group is a daemon. It affects only what happens when the group becomes empty.

Thread groups can also be used to set an upper limit on the priority of the threads they contain. After you invoke setMaxPriority with a maximum priority, any attempt to set a thread priority higher than the thread group's maximum is silently reduced to that maximum. Existing threads are not affected by this invocation. To ensure that no other thread in the group will ever have a higher priority than that of a particular thread, you can set that thread's priority and then set the group's maximum priority to be less than that. The limit also applies to the thread group itself. Any attempt to set a new maximum priority for the group that is higher than the current maximum will be silently reduced.

static synchronized void
    maxThread(Thread thr, int priority)
{
    ThreadGroup grp = thr.getThreadGroup();
    thr.setPriority(priority);
    grp.setMaxPriority(thr.getPriority() - 1);
}

This method works by setting the thread's priority to the desired value and then setting the group's maximum allowable priority to less than the thread's priority. The new group maximum is set to one less than the thread's actual priority—not to priority- 1 because an existing group maximum might limit your ability to set the thread to that priority. Of course, this method assumes that no thread in the group already has a higher priority.

ThreadGroup supports the following constructors and methods:

You can examine the contents of a thread group using two parallel sets of methods: One gets the threads contained in the group, and the other gets the thread groups contained in the group.

You can also use a ThreadGroup to manage threads in the group. Invoking interrupt on a group invokes the interrupt method on each thread in the group, including threads in all subgroups. This method is the only way to use a ThreadGroup to directly affect threads—there used to be others but they have been deprecated.

There are also two static methods in the Thread class to act on the current thread's group. They are shorthands for invoking currentThread, invoking getThreadGroup on that thread, and then invoking the method on that group.

The ThreadGroup class also supports a method that is invoked when a thread dies because of an uncaught exception:

public void uncaughtException(Thread thr, Throwable exc)

We'll look at this in more detail in the next section.

Exercise 14.9: Write a method that takes a thread group and starts a thread that periodically prints the hierarchy of threads and thread groups within that group, using the methods just described. Test it with a program that creates several short-lived threads in various groups.

Exceptions always occur in a specific thread, due to the actions of that thread—for example, trying to perform division by zero, or explicitly throwing an exception. Such exceptions are synchronous exceptions and always remain within the thread. If a “parent” thread wants to know why a “child” terminated, the child will have to store that information somewhere the “parent” can get it. Placing a thread start invocation in a try-catch block does not catch exceptions that may be thrown by the new thread—it simply catches any exception thrown by start.

When an exception is thrown it causes statements to complete abruptly and propagates up the call stack as each method invocation completes abruptly. If the exception is not caught by the time the run method completes abruptly then it is, by definition, an uncaught exception. At that point the thread that experienced the exception has terminated and the exception no longer exists. Because uncaught exceptions are usually a sign of a serious error, their occurrence needs to be tracked in some way. To enable this, every thread can have associated with it an instance of UncaughtExceptionHandler. The UncaughtExceptionHandler interface is a nested interface of class Thread and declares a single method:

A thread's uncaught exception handler can be set, if security permissions allow it, using its setUncaughtExceptionHandler method.

When a thread is about to terminate due to an uncaught exception, the runtime queries it for its handler by invoking the getUncaughtExceptionHandler method on it, and invokes the returned handler's uncaughtException method, passing the thread and the exception as parameters.

The getUncaughtExceptionHandler method will return the handler explicitly set by the thread's setUncaughtExceptionHandler method, or if no handler has been explicitly set, then the thread's ThreadGroup object is returned. Once a thread has terminated, and it has no group, getUncaughtExceptionHandler may return null.

The default implementation of the ThreadGroupuncaughtException method invokes uncaughtException on the group's parent group if there is one. If the thread group has no parent, then the system is queried for a default uncaught exception handler, using the static Thread class method getDefaultUncaughtExceptionHandler. If such a default handler exists, its uncaughtException method is called with the thread and exception. If there is no default handler, ThreadGroup's uncaughtException method simply invokes the exception's printStackTrace method to display information about the exception that occurred (unless it is an instance of ThreadDeath in which case nothing further happens).

An application can control the handling of uncaught exceptions, both for the threads it creates, and threads created by libraries it uses, at three levels:

For example, if you were writing a graphical environment, you might want to display the stack trace in a window rather than simply print it to System.err, which is where the method printStackTrace puts its output. You could define your own UncaughtExceptionHandler that implement uncaughtException to create the window you need and redirect the stack trace into the window.

The ThreadLocal class allows you to have a single logical variable that has independent values in each separate thread. Each ThreadLocal object has a set method that lets you set the value of the variable in the current thread, and a get method that returns the value for the current thread. It is as if you had defined a new field in each thread class, but without the need to actually change any thread class. This is a feature you may well never need, but if you do need it ThreadLocal may simplify your work.

For example, you might want to have a user object associated with all operations, set on a per-thread basis. You could create a ThreadLocal object to hold each thread's current user object:

public class Operations {
    private static ThreadLocal<User> users = 
        new ThreadLocal<User>() {
            /** Initially start as the "unknown user". */
            protected User initialValue() {
                return User.UNKNOWN_USER;
            }
        };

    private static User currentUser() {
        return users.get();
    }

    public static void setUser(User newUser) {
        users.set(newUser);
    }
    public void setValue(int newValue) {
        User user = currentUser();
        if (!canChange(user))
            throw new SecurityException();
        // ... modify the value ...
    }

    // ...
}

The static field users holds a ThreadLocal variable whose initial value in each thread will be User.UNKNOWN_USER. This initial value is defined by overriding the method initialValue, whose default behavior is to return null. The programmer can set the user for a given thread by invoking setUser. Once set, the method currentUser will return that value when invoked in that thread. As shown in the method setValue, the current user might be used to determine privileges.

You can clear the value in a ThreadLocal by invoking its remove method. If get is invoked again, then initialValue will again be used to determine what to return.

When a thread dies, the values set in ThreadLocal variables for that thread are not reachable, and so can be collected as garbage if not otherwise referenced.

When you spawn a new thread, the values of ThreadLocal variables for that thread will be the value returned by its initialValue method. If you want the value in a new thread to be inherited from the spawning thread, you can use the class InheritableThreadLocal, a subclass of ThreadLocal. It has a protected method childValue that is invoked to get the child's (spawned thread's) initial value. The method is passed the parent's value for the variable and returns the value for the child. The default implementation of childValue returns the parent's value, but you can subclass to do something different, such as cloning the parent's value for the child.

Use of ThreadLocal objects is an inherently risky tool. You should use them only where you thoroughly understand the thread model that will be used. The problems arise with thread pooling, a technique that is sometimes used to reuse threads instead of creating new ones for each task. In a thread pooling system a thread might be used several times. Any ThreadLocal object used in such an environment would contain the state set by the last code that happened to use the same thread, instead of an uninitialized state expected at the beginning of a new thread of execution. If you write a general class that uses ThreadLocal objects and someone uses your class in a thread pool, the behavior might be dangerously wrong.

For example, the users variable in the Operations example above could have just this problem—if an Operations object was used in multiple threads, or different Operations objects were used in the same thread, the “current user” notion could easily be wrong. Programmers who use Operations objects must understand this and only use the objects in threading situations that match the assumptions of the class's code.

A few Thread methods are designed to help you debug a multithreaded application. These print-style debugging aids can be used to print the state of an application. You can invoke the following methods on a Thread object to help you debug your threads:

There are also debugging aids to track the state of a thread group. You can invoke the following methods on ThreadGroup objects to print their state: