At a bare minimum, you need an object to lock on and two threads to implement the wait/notify mechanism. For thread notification, two methods are available: notify() and notifyAll(). For simplicity, I'll use notify() here and explain the difference later in this chapter.

Imagine that there is a member variable, valueLock, that will be used for synchronization:

private Object valueLock = new Object();

The first thread comes along and executes this code fragment:

synchronized ( valueLock ) {
    try {
        valueLock.wait();
    } catch ( InterruptedException x ) {
        System.out.println("interrupted while waiting");
    }
}

The wait() method requires the calling thread to have previously acquired the object-level lock on the target object. In this case, the object that will be waited upon is valueLock, and two lines before the valueLock.wait() statement is the synchronized(valueLock) statement. The thread that invokes the wait() method releases the object-level lock and goes to sleep until notified or interrupted. If the waiting thread is interrupted, it competes with the other threads to reacquire the object-level lock and throws an InterruptedException from within wait(). If the waiting thread is notified, it competes with the other threads to reacquire the object-level lock and then returns from wait().

Many times, a thread is interrupted to signal it that it should clean up and die (see Chapter 5). The statements used to wait can be slightly rearranged to allow the InterruptedException to propagate up further:

try {
    synchronized ( valueLock ) {
        valueLock.wait();
    }
} catch ( InterruptedException x ) {
    System.out.println("interrupted while waiting");
    // clean up, and allow thread to return from run()
}

Instead of catching InterruptedException, methods can simply declare that they throw it to pass the exception further up the call chain:

public void someMethod() throws InterruptedException {
    // ...
    synchronized ( valueLock ) {
        valueLock.wait();
    }
    // ...
}

The thread doing the notification comes along and executes this code fragment:

synchronized ( valueLock ) {
    valueLock.notify();  // notifyAll() might be safer...
}

This thread blocks until it can get exclusive access to the object-level lock for valueLock. After the lock is acquired, this thread notifies one of the waiting threads. If no threads are waiting, the notification effectively does nothing. If more than one thread is waiting on valueLock, the thread scheduler arbitrarily chooses one to receive the notification. The other waiting threads are not notified and continue to wait. To notify all waiting threads (instead of just one of them), use notifyAll() (discussed later in this chapter).

In most cases, a member variable is checked by the thread doing the waiting and modified by the thread doing the notification. The checking and modification occur inside the synchronized blocks to be sure that no race conditions develop.

This time, two member variables are used:

private boolean value = false;
private Object valueLock = new Object();

The value variable is checked by the thread doing the waiting and is set by the thread doing the notification. Synchronization on valueLock controls concurrent access to value.

The first thread comes along and executes this code fragment:

try {
    synchronized ( valueLock ) {
        while ( value != true ) {
           valueLock.wait();
        }

        // value is now true
    }
} catch ( InterruptedException x ) {
    System.out.println("interrupted while waiting");
}

After acquiring the object-level lock for valueLock, the first thread checks value to see if it is true. If it is not, the thread executes wait(), releasing the object-level lock. When this thread is notified, it wakes up, reacquires the lock, and returns from wait(). To be sure that it was not falsely notified (see the Early Notification discussion later in this chapter), it re-evaluates the while expression. If value is still not true, the thread waits again. If it is true, the thread continues to execute the rest of the code inside the synchronized block.

While the first thread is waiting, a second thread comes along and executes this code fragment:

synchronized (valueLock ) {
    value = true;
    valueLock.notify();  // notifyAll() might be safer...
}

When the first thread executes the wait() method on valueLock, it releases the object-level lock it was holding. This release allows the second thread to get exclusive access to the object-level lock on valueLock and enter the synchronized block. Inside, the second thread sets value to true and invokes notify() on valueLock to signal one waiting thread that value has been changed.

In the previous examples, valueLock was used with the synchronized statement to require that threads get exclusive access to the object-level lock associated with valueLock. Sometimes, the class is designed to synchronize on this instead of another object. In this case, the synchronized method modifier can be used instead of a synchronized statement. The following code fragments are an adaptation of the previous example.

As before, a member variable value is initially set to false:

private boolean value = false;

The first thread (threadA) comes along and invokes this waitUntilTrue() method:

public synchronized void waitUntilTrue()
                throws InterruptedException {

    while ( value == false ) {
       wait();
    }
}

While threadA is blocked on the wait(), a second thread (threadB) comes along and executes this method, passing in true for newValue:

public synchronized void setValue(boolean newValue) {
    if ( newValue != value ) {
        value = newValue;
        notify();  // notifyAll() might be safer...
    }
}

Note that both methods are synchronized and are members of the same class. In addition, both threads are invoking methods on the same instance of this class. The waitUntilTrue() method (with the wait() inside) declares that it might throw an InterruptedException. In this case, when threadB passes in true, value is changed and notify() is used to signal the waiting threadA that it may proceed. threadA wakes up, reacquires the object-level lock on this, returns from wait(), and re-evaluates the while expression. This time, value is true, and threadA will return from waitUntilTrue().

Figure 8.1 shows a relative timeline of when everything occurs. When threadA wants to invoke waitUntilTrue(), it must first get exclusive access to the object-level lock on this (time T1). Just after threadA acquires the lock, it enters waitUntilTrue() (time T2). threadA determines that it must wait for value to change, so it invokes the wait() method on this (time T3). Just after threadA enters wait(), it releases the object-level lock on this (time T4).

Some time later, threadB acquires the lock (time T5) and enters the setValue() method (time T6). While inside setValue(), threadB sets value to true and invokes notify(). This action causes threadA to be notified, but threadA cannot return from wait() until it can get the lock, and threadB is still holding the lock. threadB then returns from setValue() (time T7) and releases the lock (time T8).

Soon after threadB releases the object-level lock on this, threadA is able to reacquire it (time T9) and returns from wait() (time T10). threadA sees that value is now true and proceeds to execute the rest of the waitUntilTrue() method. threadA returns from waitUntilTrue() (time T11) and releases the lock (time T12).

There are some particular points of interest in Figure 8.1. First, notice the small intervals of time between some events. For example, there is a very short, but non-zero interval between the time that threadA gets the lock (time T1) and the time that it is inside waitUntilTrue() (time T2). Also notice that threadA is inside wait() from time T3 through time T10, but releases the lock shortly after entering (time T4) and reacquires it just before returning (time T9). A thread might spend quite a bit of time inside a wait() method, but it is not holding the lock for most of that time. On the other hand, the time spent inside the notify() method is very brief, and the lock is held the whole time.

Figure 8.1. Timeline of events for wait/notify example.

public final native void notify()
        throws IllegalMonitorStateException  // RuntimeException

The notify() method is used by a thread to signal any other threads that might be waiting on the object. If more than one thread is waiting on the object, the thread scheduler will arbitrarily choose exactly one to be notified, and the others will continue to wait. If no threads are currently waiting on the object, notify() has no effect. Before invoking notify(), a thread must get exclusive access to the object-level lock for the object. Unlike wait(), the invocation of notify() does not temporarily release the lock. If the proper lock is not held when notify() is called, an IllegalMonitorStateException is thrown. This exception is a subclass of RuntimeException, so a try-catch construct is not necessary and is rarely used.

public final native void notifyAll()
        throws IllegalMonitorStateException  // RuntimeException

The notifyAll() method works the same as notify() (see above) with one important exception: When notifyAll() is invoked, all the threads waiting on the object are notified, not just one. The advantage of notifyAll() is that you don't have to be concerned about which one of the waiting threads will be notified—they will all be notified. The disadvantage is that it might be wasteful (in terms of processor resources) to notify all the waiting threads if only one will actually be able to proceed. When in doubt, err on the side of safety over speed and use notifyAll() instead of notify().

public final void wait()
        throws InterruptedException,
               IllegalMonitorStateException  // RuntimeException

The wait() method is used to put the current thread to sleep until it is notified or interrupted. Before invoking wait(), a thread must get exclusive access to the object-level lock for the object. Just after entering wait(), the current thread releases the lock. Before returning from wait(), the thread competes with the other threads to reacquire the lock. If the proper lock is not held when wait() is called, an IllegalMonitorStateException is thrown. This exception is a subclass of RuntimeException, so a try-catch construct is not necessary and is rarely used.

If the waiting thread is interrupted, it competes to reacquire the lock and throws an InterruptedException from within wait(). This exception is not a subclass of RuntimeException, so a try-catch construct is required.

public final native void wait(long msTimeout)
        throws InterruptedException,
               IllegalMonitorStateException, // RuntimeException
               IllegalArgumentException      // RuntimeException

The wait(long) method is used to put the current thread to sleep until it is notified, interrupted, or the specified timeout elapses. Other than the timeout, wait(long) behaves the same as wait() (see above). The argument msTimeout specifies the maximum number of milliseconds that the thread should wait for notification. If msTimeout is 0, the thread will never time out (just like wait()). If the argument is less than 0, an IllegalArgumentException will be thrown. IllegalArgumentException is a subclass of RuntimeException, so a try-catch block is not required and is rarely used.

If the specified number of milliseconds elapses before the waiting thread is notified or interrupted, it competes to reacquire the lock and returns from wait(long). There is no way for the caller to determine whether a notification or a timeout occurred because no information (void) is returned from wait(long).

public final void wait(long msTimeout, int nanoSec)
        throws InterruptedException,
               IllegalMonitorStateException, // RuntimeException
               IllegalArgumentException      // RuntimeException

The wait(long, int) method works just like wait(long, int) (see above) with the exception that nanoseconds can be added to the timeout value. The argument nanoSec is added to msTimeout to determine the total amount of time that the thread will wait for notification before returning. A nanosecond is one-billionth of a second (10E-9), and most common implementations of the Java VM don't truly support this fine a resolution of time. For this reason, the use of the method is currently quite rare.

MissedNotify (see Listing 8.1) demonstrates how a notification can be missed.

 1: public class MissedNotify extends Object {
 2:     private Object proceedLock;
 3:
 4:     public MissedNotify() {
 5:         print("in MissedNotify()");
 6:         proceedLock = new Object();
 7:     }
 8:
 9:     public void waitToProceed() throws InterruptedException {
10:         print("in waitToProceed() - entered");
11:
12:         synchronized ( proceedLock ) {
13:             print("in waitToProceed() - about to wait()");
14:             proceedLock.wait();
15:             print("in waitToProceed() - back from wait()");
16:         }
17:
18:         print("in waitToProceed() - leaving");
19:     }
20:
21:     public void proceed() {
22:         print("in proceed() - entered");
23:
24:         synchronized ( proceedLock ) {
25:             print("in proceed() - about to notifyAll()");
26:             proceedLock.notifyAll();
27:             print("in proceed() - back from notifyAll()");
28:         }
29:
30:         print("in proceed() - leaving");
31:     }
32:
33:     private static void print(String msg) {
34:         String name = Thread.currentThread().getName();
35:         System.out.println(name + ": " + msg);
36:     }
37:
38:     public static void main(String[] args) {
39:         final MissedNotify mn = new MissedNotify();
40: 
41:         Runnable runA = new Runnable() {
42:                 public void run() {
43:                     try {
44:                         Thread.sleep(1000);
45:                         mn.waitToProceed();
46:                     } catch ( InterruptedException x ) {
47:                         x.printStackTrace();
48:                     }
49:                 }
50:             };
51:
52:         Thread threadA = new Thread(runA, "threadA");
53:         threadA.start();
54:
55:         Runnable runB = new Runnable() {
56:                 public void run() {
57:                     try {
58:                         Thread.sleep(500);
59:                         mn.proceed();
60:                     } catch ( InterruptedException x ) {
61:                         x.printStackTrace();
62:                     }
63:                 }
64:             };
65:
66:         Thread threadB = new Thread(runB, "threadB");
67:         threadB.start();
68:
69:         try {
70:             Thread.sleep(10000);
71:         } catch ( InterruptedException x ) {
72:         }
73:
74:         print("about to invoke interrupt() on threadA");
75:         threadA.interrupt();
76:     }
77: }

The thread entering the waitToProceed() method (lines 9–19) blocks until it can get exclusive access to the object-level lock on proceedLock (line 12). After it does, it invokes wait() to go to sleep and await notification (line 14). The InterruptedException that might be thrown by wait() is passed along and is declared to be thrown from waitToProceed() (line 9).

The thread entering the proceed() method (lines 21–31) blocks until it gets the lock on proceedLock (line 24). It then invokes notifyAll() to signal any and all waiting threads (line 26).

In the main() method (lines 38–76), an instance of MissedNotify called mn is constructed (line 39) and two threads are spawned to interact with it. The first thread is threadA, which sleeps for one second (line 44) before invoking waitToProceed() (line 45). The second thread is threadB, which sleeps for 0.5 seconds (line 58) before invoking proceed() (line 59). Because threadB sleeps only half the time that threadA does, threadB will enter and exit proceed() while threadA is still sleeping. When threadA enters waitToProceed(), it will end up waiting indefinitely because it will have missed the notification.

After 10 seconds have elapsed (lines 69–72), the main thread invokes interrupt() on threadA (line 75) to get it to break out of wait(). Inside wait(), threadA throws an InterruptedException that causes waitToProceed() to abruptly terminate. The exception is caught (line 46) and a stack trace is printed (line 47).

Listing 8.2 shows the output produced when MissedNotify is run. Your output should match.

 1: main: in MissedNotify()
 2: threadB: in proceed() - entered
 3: threadB: in proceed() - about to notifyAll()
 4: threadB: in proceed() - back from notifyAll()
 5: threadB: in proceed() - leaving
 6: threadA: in waitToProceed() - entered
 7: threadA: in waitToProceed() - about to wait()
 8: main: about to invoke interrupt() on threadA
 9: java.lang.InterruptedException: operation interrupted
10:     at java.lang.Object.wait(Native Method)
11:     at java.lang.Object.wait(Object.java:424)
12:     at MissedNotify.waitToProceed(MissedNotify.java:14)
13:     at MissedNotify$1.run(MissedNotify.java:45)
14:     at java.lang.Thread.run(Thread.java:479)

You can see that threadB gets into proceed(), performs the notification, and leaves proceed() (lines 2–5). Long after threadB is finished, threadA enters waitToProceed() (line 6) and continues on to invoke wait() (line 7). threadA remains stuck here until the main thread interrupts it (lines 8–14).

Figure 8.2 shows the approximate sequence of events that occurs when MissedNotify is run. The lock on proceedLock is held by threadB from shortly after it enters proceed() until just before it returns from the method (from time T2 to T3). Soon after threadB leaves proceed() (time T4), threadA enters waitToProceed() (time T5). threadA acquires the lock on proceedLock (time T6) and invokes wait() (time T7). Just after entering the wait() method, it releases the lock (time T8). threadA remains inside wait() indefinitely because it has missed the notification.

Figure 8.2. Timeline of events for a missed notification.

To fix MissedNotify, a boolean indicator variable should be added. The indicator is only accessed and modified inside synchronized blocks. This indicator will be initially false and will be set true whenever the proceed() method happens to be called. Inside waitToProceed(), the indicator will be checked to see if a wait is necessary or not. Listing 8.3 shows the code for MissedNotifyFix.

 1: public class MissedNotifyFix extends Object {
 2:     private Object proceedLock;
 3:     private boolean okToProceed;
 4:
 5:     public MissedNotifyFix() {
 6:         print("in MissedNotify()");
 7:         proceedLock = new Object();
 8:         okToProceed = false;
 9:     }
10:
11:     public void waitToProceed() throws InterruptedException {
12:         print("in waitToProceed() - entered");
13:
14:         synchronized ( proceedLock ) {
15:             print("in waitToProceed() - entered sync block");
16:
17:             while ( okToProceed == false ) {
18:                 print("in waitToProceed() - about to wait()");
19:                 proceedLock.wait();
20:                 print("in waitToProceed() - back from wait()");
21:             }
22:
23:             print("in waitToProceed() - leaving sync block");
24:         }
25:
26:         print("in waitToProceed() - leaving");
27:     }
28:
29:     public void proceed() {
30:         print("in proceed() - entered");
31:
32:         synchronized ( proceedLock ) {
33:             print("in proceed() - entered sync block");
34:
35:             okToProceed = true;
36:             print("in proceed() - changed okToProceed to true");
37:             proceedLock.notifyAll();
38:             print("in proceed() - just did notifyAll()");
39:
40:             print("in proceed() - leaving sync block");
41:         }
42: 
43:         print("in proceed() - leaving");
44:     }
45:
46:     private static void print(String msg) {
47:         String name = Thread.currentThread().getName();
48:         System.out.println(name + ": " + msg);
49:     }
50:
51:     public static void main(String[] args) {
52:         final MissedNotifyFix mnf = new MissedNotifyFix();
53:
54:         Runnable runA = new Runnable() {
55:                 public void run() {
56:                     try {
57:                         Thread.sleep(1000);
58:                         mnf.waitToProceed();
59:                     } catch ( InterruptedException x ) {
60:                         x.printStackTrace();
61:                     }
62:                 }
63:             };
64:
65:         Thread threadA = new Thread(runA, "threadA");
66:         threadA.start();
67:
68:         Runnable runB = new Runnable() {
69:                 public void run() {
70:                     try {
71:                         Thread.sleep(500);
72:                         mnf.proceed();
73:                     } catch ( InterruptedException x ) {
74:                         x.printStackTrace();
75:                     }
76:                 }
77:             };
78:
79:         Thread threadB = new Thread(runB, "threadB");
80:         threadB.start();
81:
82:         try { 
83:             Thread.sleep(10000);
84:         } catch ( InterruptedException x ) {
85:         }
86: 
87:         print("about to invoke interrupt() on threadA");
88:         threadA.interrupt();
89:     }
90: }

MissedNotifyFix adds the private member variable okToProceed (line 3) to be used as the indicator. It is initially set to false in the constructor (line 8). The proceedLock object is used to control concurrent access to okToProceed and to facilitate the wait/notify implementation.

Inside the synchronized block (lines 32–41) of proceed() (lines 29–44), okToProceed is set true (line 35) just before notifyAll() is invoked. This way, if the notifyAll() method is ineffective because no threads are currently waiting, okToProceed indicates that proceed() has been called.

Inside the synchronized block (lines 14–24) of waitToProceed() (lines 11–27), okToProceed is checked to see if any waiting is necessary. Instead of just using an if statement to check, a while statement (lines 17–21) is used as a safeguard against early notifications (explained later in this chapter). As long as okToProceed is false, the calling thread (threadA) will wait() for notification (line 19). Even if threadA is notified while waiting, it will double-check okToProceed. If okToProceed is still false, threadA will wait() again.

In this particular case, okToProceed is set true by threadB long before threadA enters waitToProceed(). When threadA evaluates the while expression (line 17), it determines that no waiting is necessary and skips the body of the loop. The notification is still missed, but the indicator variable okToProceed prevents threadA from waiting.

Listing 8.4 shows the output produced when MissedNotifyFix is run. Your output should match. Notice that threadB gets in and out of proceed() (lines 2–7) before threadA enters waitToProceed() (line 8). With this indicator fix in place, threadA moves right through waitToProceed() (lines 8–11). Notice that none of the messages about wait() are printed. The indicator variable kept threadA from waiting for notification that would never come.

 1: main: in MissedNotify()
 2: threadB: in proceed() - entered
 3: threadB: in proceed() - entered sync block
 4: threadB: in proceed() - changed okToProceed to true
 5: threadB: in proceed() - just did notifyAll()
 6: threadB: in proceed() - leaving sync block
 7: threadB: in proceed() - leaving
 8: threadA: in waitToProceed() - entered
 9: threadA: in waitToProceed() - entered sync block
10: threadA: in waitToProceed() - leaving sync block
11: threadA: in waitToProceed() - leaving
12: main: about to invoke interrupt() on threadA

Figure 8.3 shows the sequence of events for MissedNotifyFix. The main difference to note is that threadA never calls wait().

Figure 8.3. Timeline of events for MissedNotifyFix.

EarlyNotify (see Listing 8.5) shows how an early notification can occur and the resulting problems it causes. Basically, two threads are waiting to remove an item, while another thread adds just one item.

 1: import java.util.*;
 2:
 3: public class EarlyNotify extends Object {
 4:     private List list;
 5:
 6:     public EarlyNotify() {
 7:         list = Collections.synchronizedList(new LinkedList());
 8:     }
 9:
10:     public String removeItem() throws InterruptedException {
11:         print("in removeItem() - entering");
12:
13:         synchronized ( list ) {
14:             if ( list.isEmpty() ) {  // dangerous to use 'if'!
15:                 print("in removeItem() - about to wait()");
16:                 list.wait();
17:                 print("in removeItem() - done with wait()");
18:             }
19:
20:             // extract the new first item
21:             String item = (String) list.remove(0);
22:
23:             print("in removeItem() - leaving");
24:             return item;
25:         } // sync
26:     }
27:
28:     public void addItem(String item) {
29:         print("in addItem() - entering");
30:         synchronized ( list ) {
31:             // There'll always be room to add to this List
32:             // because it expands as needed.
33:             list.add(item);
34:             print("in addItem() - just added: '" + item + "'");
35:
36:             // After adding, notify any and all waiting
37:             // threads that the list has changed.
38:             list.notifyAll();
39:             print("in addItem() - just notified");
40:         } // sync
41:         print("in addItem() - leaving");
42:     }
43: 
44:     private static void print(String msg) {
45:         String name = Thread.currentThread().getName();
46:         System.out.println(name + ": " + msg);
47:     }
48:
49:     public static void main(String[] args) {
50:         final EarlyNotify en = new EarlyNotify();
51:
52:         Runnable runA = new Runnable() {
53:                 public void run() {
54:                     try {
55:                         String item = en.removeItem();
56:                         print("in run() - returned: '" +
57:                                 item + "'");
58:                     } catch ( InterruptedException ix ) {
59:                         print("interrupted!");
60:                     } catch ( Exception x ) {
61:                         print("threw an Exception!!!
" + x);
62:                     }
63:                 }
64:             };
65:
66:         Runnable runB = new Runnable() {
67:                 public void run() {
68:                     en.addItem("Hello!");
69:                 }
70:             };
71:
72:         try {
73:             Thread threadA1 = new Thread(runA, "threadA1");
74:             threadA1.start();
75:
76:             Thread.sleep(500);
77:
78:             // start a *second* thread trying to remove
79:             Thread threadA2 = new Thread(runA, "threadA2");
80:             threadA2.start();
81:
82:             Thread.sleep(500);
83: 
84:             Thread threadB = new Thread(runB, "threadB");
85:             threadB.start();
86:
87:             Thread.sleep(10000); // wait 10 seconds
88:
89:             threadA1.interrupt();
90:             threadA2.interrupt();
91:         } catch ( InterruptedException x ) {
92:             // ignore
93:         }
94:     }
95: }

In the constructor for EarlyNotify (lines 6–9), a multithread-safe List is created and used to hold the items added and removed. When a thread enters the removeItem() method (lines 10–26), it blocks until it can get exclusive access to the object-level lock for list (line 13). The thread checks to see if the list is empty (line 14). If the list is empty, the thread invokes wait() and sleeps until notified (line 16). If the thread is interrupted while waiting, it throws an InterruptedException (line 10) that is passed out of removeItem(). When notified, the thread removes the first item from the list and casts it into a String (line 21). This String is returned to the caller (line 24) and in the process of leaving the synchronized block, the lock is automatically released.

When a thread enters the addItem() method (lines 28–42), it blocks until it can get exclusive access to the object-level lock for list (line 30). The thread adds the item to list (line 33) and notifies any and all waiting threads with notifyAll() that list has been modified (line 38).

In the main() method (lines 49–94), three threads are started and simultaneously interact with one instance of EarlyNotify referred to by en (line 50). threadA1 is started (line 74) and invokes removeItem() (line 55). The list is initially empty, so threadA1 invokes wait() inside removeItem(). threadA2 is started (line 80) 0.5 seconds after threadA1. threadA2 invokes removeItem() and also finds the list is empty and blocks waiting for notification.

After another 0.5 seconds pass, threadB is started (line 85) and invokes addItem(), passing in Hello! (line 68). Both threadA1 and threadA2 have temporarily released the object-level lock on list while inside wait(), so threadB is free to acquire the lock. threadB adds the String to list and notifies any and all waiting threads with notifyAll().

The trouble arises from the fact that both threadA1 and threadA2 return from wait() and try to remove the added item from the list. Only one of the two will succeed. The other will end up trying to remove an item that has just disappeared from the list.

Listing 8.6 shows possible output when EarlyNotify is run. Your output might differ somewhat. In particular, whether threadA1 or threadA2 succeeds appears to be randomly determined and can change each time EarlyNotify is run.

 1: threadA1: in removeItem() - entering
 2: threadA1: in removeItem() - about to wait()
 3: threadA2: in removeItem() - entering
 4: threadA2: in removeItem() - about to wait()
 5: threadB: in addItem() - entering
 6: threadB: in addItem() - just added: 'Hello!'
 7: threadB: in addItem() - just notified
 8: threadB: in addItem() - leaving
 9: threadA1: in removeItem() - done with wait()
10: threadA1: in removeItem() - leaving
11: threadA1: in run() - returned: 'Hello!'
12: threadA2: in removeItem() - done with wait()
13: threadA2: threw an Exception!!!
14: java.lang.IndexOutOfBoundsException: Index: 0, Size: 0

For this particular run of EarlyNotify, threadA1 returns from wait() first (line 9) and successfully removes the item from the list (lines 10–11). When threadA2 returns from wait() (line 12), it also tries to remove the item from the list. Because the list was just emptied by threadA1, threadA2 ends up causing an exception to be thrown when it tries to remove the nonexistent item (lines 13–14). In this case, threadA2 was notified too early and should not proceed to execute the rest of removeItem().

This problem of early notification is fixed in EarlyNotifyFix (see Listing 8.7). Now, when a thread returns from wait(), it rechecks the condition it was waiting for to be sure that it has been met.

 1: import java.util.*;
 2:
 3: public class EarlyNotifyFix extends Object {
 4:     private List list;
 5:
 6:     public EarlyNotifyFix() {
 7:         list = Collections.synchronizedList(new LinkedList());
 8:     }
 9:
10:     public String removeItem() throws InterruptedException {
11:         print("in removeItem() - entering");
12:
13:         synchronized ( list ) {
14:             while ( list.isEmpty() ) {
15:                 print("in removeItem() - about to wait()");
16:                 list.wait();
17:                 print("in removeItem() - done with wait()");
18:             }
19:
20:             // extract the new first item
21:             String item = (String) list.remove(0);
22:
23:             print("in removeItem() - leaving");
24:             return item;
25:         }
26:     }
27:
28:     public void addItem(String item) {
29:         print("in addItem() - entering");
30:         synchronized ( list ) {
31:             // There'll always be room to add to this List
32:             // because it expands as needed.
33:             list.add(item);
34:             print("in addItem() - just added: '" + item + "'");
35:
36:             // After adding, notify any and all waiting
37:             // threads that the list has changed.
38:             list.notifyAll();
39:             print("in addItem() - just notified");
40:         }
41:         print("in addItem() - leaving");
42:     }
43: 
44:     private static void print(String msg) {
45:         String name = Thread.currentThread().getName();
46:         System.out.println(name + ": " + msg);
47:     }
48:
49:     public static void main(String[] args) {
50:         final EarlyNotifyFix enf = new EarlyNotifyFix();
51:
52:         Runnable runA = new Runnable() {
53:                 public void run() {
54:                     try {
55:                         String item = enf.removeItem();
56:                         print("in run() - returned: '" +
57:                                 item + "'");
58:                     } catch ( InterruptedException ix ) {
59:                         print("interrupted!");
60:                     } catch ( Exception x ) {
61:                         print("threw an Exception!!!
" + x);
62:                     }
63:                 }
64:             };
65:
66:         Runnable runB = new Runnable() {
67:                 public void run() {
68:                     enf.addItem("Hello!");
69:                 }
70:             };
71:
72:         try {
73:             Thread threadA1 = new Thread(runA, "threadA1");
74:             threadA1.start();
75:
76:             Thread.sleep(500);
77:    
78:             // start a *second* thread trying to remove
79:             Thread threadA2 = new Thread(runA, "threadA2");
80:             threadA2.start();
81: 
82:             Thread.sleep(500);
83:    
84:             Thread threadB = new Thread(runB, "threadB");
85:             threadB.start();
86:
87:             Thread.sleep(10000); // wait 10 seconds
88:
89:             threadA1.interrupt();
90:             threadA2.interrupt();
91:         } catch ( InterruptedException x ) {
92:             // ignore
93:         }
94:     }
95: }

To properly protect the removeItem() method from early notifications, all that was necessary was to change the if to a while (line 14). Now, whenever a thread returns from wait() (line 16), it rechecks to see if it was notified early or if the list is really no longer empty (line 14). It is important that the code that checks to see if the list is empty, and the code that removes an item if it was not empty, all be within the same synchronized block.

Listing 8.8 shows the output produced from a particular run of EarlyNotifyFix. Your output might differ due to thread-scheduling randomness.

 1: threadA1: in removeItem() - entering
 2: threadA1: in removeItem() - about to wait()
 3: threadA2: in removeItem() - entering
 4: threadA2: in removeItem() - about to wait()
 5: threadB: in addItem() - entering
 6: threadB: in addItem() - just added: 'Hello!'
 7: threadB: in addItem() - just notified
 8: threadB: in addItem() - leaving
 9: threadA1: in removeItem() - done with wait()
10: threadA1: in removeItem() - leaving
11: threadA1: in run() - returned: 'Hello!'
12: threadA2: in removeItem() - done with wait()
13: threadA2: in removeItem() - about to wait()
14: threadA2: interrupted!

Notice that threadA1 got to the list first and removed the item (lines 9–11). After threadA2 returns from wait() (line 12), it rechecks the list and finds that the list is empty, so threadA2 ignores the early notification and invokes wait() again (line 13). After the application has been running for about 10 seconds, the main thread interrupts threadA1 and threadA2. In this case, threadA1 has already died, but threadA2 is blocked waiting inside removeItem(). When threadA2 is interrupted, wait() throws an InterruptedException (line 14).

Missed notifications and early notifications can be tough bugs to track down in your code. Many times they are exposed only under rare conditions. It is important to be careful in your coding by using an indicator variable in addition to the wait/notify mechanism.

public final void join()
        throws InterruptedException

The join() method causes the current thread to block and wait an unlimited amount of time for this thread to die. The current thread will throw an InterruptedException if interrupted while waiting for the specified thread to die.

public final synchronized void join(long msTimeout)
        throws InterruptedException,
               IllegalArgumentException      // RuntimeException

The join(long) method causes the current thread to block and wait up to msTimeout milliseconds for the specified thread to die. If msTimeout is 0, the current thread will never time out and will wait forever for the specified thread to die (just like join()). If msTimeout is less than 0, an IllegalArgumentException is thrown. The current thread will throw an InterruptedException if interrupted while waiting for the specified thread to die.

public final synchronized void join(long msTimeout, int nanoSec)
        throws InterruptedException,
               IllegalArgumentException      // RuntimeException

The join(long, int) method works just like join(long) (see above) with the exception that nanoseconds can be added to the timeout value. The argument nanoSec is added to msTimeout to determine the total amount of time that the thread will wait for the specified thread to die before returning. An IllegalArgumentException is thrown if msTimeout is less than 0 or if nanoSec is less than 0 or greater than 999999. The current thread will throw an InterruptedException if interrupted while waiting for the specified thread to die.

The class JoinDemo (see Listing 8.12) demonstrates how join() can be used to wait for threads to die. The main thread spawns three new threads and then waits for each of them to die. Each of the threads lives for a different amount of time.

 1: public class JoinDemo extends Object {
 2:     public static Thread launch(String name, long napTime) {
 3:         final long sleepTime = napTime;
 4:
 5:         Runnable r = new Runnable() {
 6:                 public void run() {
 7:                     try {
 8:                         print("in run() - entering");
 9:                         Thread.sleep(sleepTime);
10:                     } catch ( InterruptedException x ) {
11:                         print("interrupted!");
12:                     } finally {
13:                         print("in run() - leaving");
14:                     }
15:                 }
16:             };
17:
18:         Thread t = new Thread(r, name);
19:         t.start();
20:
21:         return t;
22:     }
23:
24:     private static void print(String msg) {
25:         String name = Thread.currentThread().getName();
26:         System.out.println(name + ": " + msg);
27:     }
28:
29:     public static void main(String[] args) {
30:         Thread[] t = new Thread[3];
31:
32:         t[0] = launch("threadA", 2000);
33:         t[1] = launch("threadB", 1000);
34:         t[2] = launch("threadC", 3000);
35:
36:         for ( int i = 0; i < t.length; i++ ) {
37:             try {
38:                 String idxStr = "t[" + i + "]";
39:                 String name = "[" + t[i].getName() + "]";
40: 
41:                 print(idxStr + ".isAlive()=" +
42:                         t[i].isAlive() + " " + name);
43:                 print("about to do: " + idxStr +
44:                         ".join() " + name);
45:
46:                 long start = System.currentTimeMillis();
47:                 t[i].join(); // wait for the thread to die
48:                 long stop = System.currentTimeMillis();
49:
50:                 print(idxStr + ".join() - took " +
51:                         ( stop - start ) + " ms " + name);
52:             } catch ( InterruptedException x ) {
53:                 print("interrupted waiting on #" + i);
54:             }
55:         }
56:     }
57: }

In the static method launch() (lines 2–22) of JoinDemo, a new Runnable instance r is created. Inside the run() method of r, the thread prints an announcement (line 8), sleeps for the specified delay (line 9), and prints another message just before leaving run() (line 13). A new Thread is constructed and started for r and is given the name passed into launch() (lines 18–19). A reference to this new running Thread is returned to the caller (line 21).

In main() (lines 29–56), a Thread[] named t is created to hold three references (line 30). The launch() method is called three times with different parameters and the references returned are stored into t (lines 32–34):

All three threads are running concurrently. threadB finishes first, threadA finishes second, and threadC finishes last.

After launching all three threads, the main thread continues on into the for loop (lines 36–55). In this loop, main prints out some diagnostic information for each of the launched threads and then invokes join() on each of them to wait for each to die (line 47). Without all the extra information gathering and printing, the for loop boils down to this:

for ( int i = 0; i < t.length; i++ ) {
    try {
        t[i].join(); // wait for the thread to die
    } catch ( InterruptedException x ) {
    }
}

The main thread blocks for about two seconds waiting for threadA to die. Meanwhile, threadB has already died, so when the main thread invokes join() on threadB, join() returns right away. The main thread then proceeds to block for about one second waiting for threadC to die.

Listing 8.13 shows the output produced from a particular run of JoinDemo. Your output should match fairly closely. The only differences should be a little variation in the number of milliseconds that the main thread spends inside join() and perhaps a few lines of output swapped with each other.

 1: main: t[0].isAlive()=true [threadA]
 2: threadA: in run() - entering
 3: threadB: in run() - entering
 4: threadC: in run() - entering
 5: main: about to do: t[0].join() [threadA]
 6: threadB: in run() - leaving
 7: threadA: in run() - leaving
 8: main: t[0].join() - took 1920 ms [threadA]
 9: main: t[1].isAlive()=false [threadB]
10: main: about to do: t[1].join() [threadB]
11: main: t[1].join() - took 0 ms [threadB]
12: main: t[2].isAlive()=true [threadC]
13: main: about to do: t[2].join() [threadC]
14: threadC: in run() - leaving
15: main: t[2].join() - took 990 ms [threadC]

The main thread finds threadA still alive (line 1), invokes join() on it (line 5), and waits 1920 milliseconds for it to die (line 8). Notice that threadB reported that it was leaving its run() method while the main thread was waiting on threadA (line 6). Therefore, the main thread finds threadB already dead (line 9) and when join() is invoked (line 10), the main thread returns right away (line 11). Next, the main thread finds threadC still alive (line 12), invokes join() on it (line 13), and waits 990 milliseconds for it to die (line 15).

The PipedBytes class (see Listing 8.14) shows how data can be sent through a pipe from one thread to another. Integers are written to a PipedOutputStream by one thread and are read from a PipedInputStream by another thread.

 1: import java.io.*;
 2:
 3: public class PipedBytes extends Object {
 4:     public static void writeStuff(OutputStream rawOut) {
 5:         try {
 6:             DataOutputStream out = new DataOutputStream(
 7:                     new BufferedOutputStream(rawOut));
 8:    
 9:             int[] data = { 82, 105, 99, 104, 97, 114, 100, 32,
10:                            72, 121, 100, 101 } ;
11:
12:             for ( int i = 0; i < data.length; i++ ) {
13:                 out.writeInt(data[i]);
14:             }
15:
16:             out.flush();
17:             out.close();
18:         } catch ( IOException x ) {
19:             x.printStackTrace();
20:         }
21:     }
22:
23:     public static void readStuff(InputStream rawIn) {
24:         try {
25:             DataInputStream in = new DataInputStream(
26:                     new BufferedInputStream(rawIn));
27:
28:             boolean eof = false;
29:             while ( !eof ) {
30:                 try {
31:                     int i = in.readInt();
32:                     System.out.println("just read: " + i);
33:                 } catch ( EOFException eofx ) {
34:                     eof = true;
35:                 }
36:             }
37:
38:             System.out.println("Read all data from the pipe");
39:         } catch ( IOException x ) {
40:             x.printStackTrace();
41:         }
42:     }
43: 
44:     public static void main(String[] args) {
45:         try {
46:             final PipedOutputStream out =
47:                     new PipedOutputStream();
48:
49:             final PipedInputStream in =
50:                     new PipedInputStream(out);
51:
52:             Runnable runA = new Runnable() {
53:                     public void run() {
54:                         writeStuff(out);
55:                     }
56:                 } ;
57:
58:             Thread threadA = new Thread(runA, "threadA");
59:             threadA.start();
60:
61:             Runnable runB = new Runnable() {
62:                     public void run() {
63:                         readStuff(in);
64:                     }
65:                 };
66:
67:             Thread threadB = new Thread(runB, "threadB");
68:             threadB.start();
69:         } catch ( IOException x ) {
70:             x.printStackTrace();
71:         }
72:     }
73: }

In the main() method (lines 44–72), a data pipe is created and two threads are started to transfer data through it. First, the PipedOutputStream is constructed (lines 46–47). Next, the associated PipedInputStream is created by passing a reference to the PipedOutputStream that makes up the other end of the pipe (lines 49–50). threadA is started and executes the writeStuff() method, passing in a reference to the PipedOutputStream (line 54). threadB is started and executes the readStuff() method, passing in a reference to the PipedInputStream (line 63). threadA is writing data into one end of the pipe while threadB is simultaneously reading data from the other end of the pipe.

The writeStuff() method (lines 4–21) only expects an OutputStream to be passed to it and makes no special considerations for the fact that it might just happen to be a PipedOutputStream (line 4). When threadA invokes writeStuff(), it wraps the OutputStream in a DataOuptutStream to be able to use the writeInt() method to put the integers into the pipe (lines 6–7). The integer data to be sent is stored into the int[] referred to by data (lines 9–10). Each of the integers in the array is written to the DataOutputStream (lines 12–14). Before returning, the stream is flushed and closed (lines 16–17).

Like writeStuff(), the readStuff() method (lines 23–42) only expects an InputStream to be passed to it and makes no special considerations for the fact that it might happen to be a PipedInputStream (line 23). This raw InputStream is wrapped in a DataInputStream to facilitate the reading of integers (lines 25–26). As long as the end-of-file is not detected, threadB continues to read integers from the stream (lines 28–36).

Listing 8.15 shows the output produced when PipedBytes is run. Your output should match. Notice that all the integers are read by threadB in exactly the same order as they are written by threadA.

 1: just read: 82
 2: just read: 105
 3: just read: 99
 4: just read: 104
 5: just read: 97
 6: just read: 114
 7: just read: 100
 8: just read: 32
 9: just read: 72
10: just read: 121
11: just read: 100
12: just read: 101
13: Read all data from the pipe

The PipedCharacters class (see Listing 8.16) shows how character-based data can be sent through a pipe from one thread to another. Strings are written to a PipedWriter by one thread and are read from a PipedReader by another thread.

 1: import java.io.*;
 2:
 3: public class PipedCharacters extends Object {
 4:     public static void writeStuff(Writer rawOut) {
 5:         try {
 6:             BufferedWriter out = new BufferedWriter(rawOut);
 7:
 8:             String[][] line = {
 9:                     { "Java", "has", "nice", "features." },
10:                     { "Pipes", "are", "interesting." },
11:                     { "Threads", "are", "fun", "in", "Java." },
12:                     { "Don't", "you", "think", "so?" }
13:                 };
14:
15:             for ( int i = 0; i < line.length; i++ ) {
16:                 String[] word = line[i];
17:
18:                 for ( int j = 0; j < word.length; j++ ) {
19:                     if ( j > 0 ) {
20:                         // put a space between words
21:                         out.write(" ");
22:                     } 
23:
24:                     out.write(word[j]);
25:                 }
26:
27:                 // mark the end of a line
28:                 out.newLine();
29:             }
30:
31:             out.flush();
32:             out.close();
33:         } catch ( IOException x ) {
34:             x.printStackTrace();
35:         }
36:     }
37:
38:     public static void readStuff(Reader rawIn) {
39:         try {
40:             BufferedReader in = new BufferedReader(rawIn);
41: 
42:             String line;
43:             while ( ( line = in.readLine() ) != null ) {
44:                 System.out.println("read line: " + line);
45:             }
46:
47:             System.out.println("Read all data from the pipe");
48:         } catch ( IOException x ) {
49:             x.printStackTrace();
50:         }
51:     }
52:
53:     public static void main(String[] args) {
54:         try {
55:             final PipedWriter out = new PipedWriter();
56:
57:             final PipedReader in = new PipedReader(out);
58:
59:             Runnable runA = new Runnable() {
60:                     public void run() {
61:                         writeStuff(out);
62:                     }
63:                 };
64:
65:             Thread threadA = new Thread(runA, "threadA");
66:             threadA.start();
67:    
68:             Runnable runB = new Runnable() {
69:                     public void run() {
70:                         readStuff(in);
71:                     }
72:                 };
73:    
74:             Thread threadB = new Thread(runB, "threadB");
75:             threadB.start();
76:         } catch ( IOException x ) {
77:             x.printStackTrace();
78:         }
79:     }
80: }

In the main() method (lines 53–79), a character-based data pipe is created and two threads are started to transfer data through it. First, a PipedWriter is constructed (line 55). Next, the associated PipedReader is constructed by passing a reference to the PipedWriter (line 57). threadA is started and executes the writeStuff() method, passing in a reference to the PipedWriter (line 61). threadB is started and executes the readStuff() method, passing in a reference to the PipedReader (line 70). threadA is writing characters into one end of the pipe while threadB is simultaneously reading characters from the other end of the pipe.

The writeStuff() method (lines 4–36) only expects a Writer to be passed to it and makes no special considerations for the fact that it might be a PipedWriter (line 4). When threadA invokes writeStuff(), it wraps the Writer in a BufferedWriter to be able to use the newLine() method to mark the end of each line (line 6). The sentences to be sent are stored in the String[][] referred to by line (lines 8–13). The two-dimensional array stores the sentences in one dimension and the individual words that make up each sentence in the other dimension. Each line (sentence) is stepped through using the outer for loop (lines 15–29). Each word in a line is stepped through using the inner for loop (lines 18–25). After the last word of each line is written, the newLine() method is used to mark the end-of-line (line 28). Before returning, the BufferedWriter is flushed and closed (lines 31–32).

The readStuff() method (lines 38–51) only expects a Reader to be passed to it and makes no special considerations for the fact that it might happen to be a PipedReader (line 38). This raw Reader is wrapped in a BufferedReader to facilitate the reading of whole lines at a time (line 40). Each line is read from the BufferedReader until the end-of-file is detected by a null return from readLine() (lines 42–45).

Listing 8.17 shows the output produced when PipedCharacters is run. Your output should match. Notice that all the lines (sentences) are read by threadB in exactly the same order that they are written by threadA.

1: read line: Java has nice features.
2: read line: Pipes are interesting.
3: read line: Threads are fun in Java.
4: read line: Don't you think so?
5: Read all data from the pipe

ThreadLocal has two public methods. The first one is get():

public Object get()

get() is used to retrieve the thread-specific value. Internally, it looks up to see if the calling thread has a value stored. If is does, it returns that value. If not, it calls the protected method initialValue() to initialize a value for the calling thread, stores it in the internal WeakHashMap for future lookups, and returns the value to the caller. Typically, get() is the only method called on a ThreadLocal object.

However, on rare occasions, a thread can set its own value for future use by invoking the other public method of ThreadLocal directly:

public void set(Object value)

set() takes the value passed and stores it in the internal WeakHashMap for future lookups.

ThreadLocal is not abstract, but it generally needs to be subclassed to be useful. This protected method should be overridden in the subclass:

protected Object initialValue()

By default, initialValue() returns null, but in the subclass it can return a more meaningful value.

The class ThreadID (see Listing 8.18) is a subclass of ThreadLocal and creates a unique ID for every thread that invokes get(). If a thread comes back and invokes get() again, the same value is returned.

 1: public class ThreadID extends ThreadLocal {
 2:     private int nextID;
 3:
 4:     public ThreadID() {
 5:         nextID = 10001;
 6:     }
 7:
 8:     private synchronized Integer getNewID() {
 9:         Integer id = new Integer(nextID);
10:         nextID++;
11:         return id;
12:     }
13:
14:     // override ThreadLocal's version
15:     protected Object initialValue() {
16:         print("in initialValue()");
17:         return getNewID();
18:     }
19:
20:     public int getThreadID() {
21:         // Call get() in ThreadLocal to get the calling
22:         // thread's unique ID.
23:         Integer id = (Integer) get();
24:         return id.intValue();
25:     }
26:
27:     private static void print(String msg) {
28:         String name = Thread.currentThread().getName();
29:         System.out.println(name + ": " + msg);
30:     }
31: }

ThreadID is a subclass of ThreadLocal (line 1) and creates a unique ID for every thread that invokes the get() method. The next unique ID to be assigned is held in nextID (line 2) and is initialized to be 10001 (line 5). The getNewID() method (lines 8–12) is synchronized to ensure that only one thread is inside it at a time. The initialValue() method (lines 15–18) overrides the superclass's method and calls getNewID() to generate a new, unique ID.

The only public method is getThreadID() (lines 20–25). Inside, get() is invoked to look up the value for the calling thread (line 23). This action might indirectly cause initialValue() to be called if it is the first time that the calling thread has invoked get().

The class ThreadIDMain (see Listing 8.19) starts up three threads to demonstrate how ThreadID works. Each thread calls getThreadID() twice to show that the first call for each thread generates a new ID and that the second call simply returns the same value generated during the first call.

 1: public class ThreadIDMain extends Object implements Runnable {
 2:     private ThreadID var;
 3:
 4:     public ThreadIDMain(ThreadID var) {
 5:         this.var = var;
 6:     }
 7:
 8:     public void run() {
 9:         try { 
10:             print("var.getThreadID()=" + var.getThreadID());
11:             Thread.sleep(2000);
12:             print("var.getThreadID()=" + var.getThreadID());
13:         } catch ( InterruptedException x ) {
14:             // ignore
15:         }
16:     }
17:
18:     private static void print(String msg) {
19:         String name = Thread.currentThread().getName();
20:         System.out.println(name + ": " + msg);
21:     }
22:
23:     public static void main(String[] args) {
24:         ThreadID tid = new ThreadID();
25:         ThreadIDMain shared = new ThreadIDMain(tid);
26:
27:         try {
28:             Thread threadA = new Thread(shared, "threadA");
29:             threadA.start();
30:
31:             Thread.sleep(500);
32:
33:             Thread threadB = new Thread(shared, "threadB");
34:             threadB.start();
35:
36:             Thread.sleep(500);
37:
38:             Thread threadC = new Thread(shared, "threadC");
39:             threadC.start();
40:         } catch ( InterruptedException x ) {
41:             // ignore
42:         }
43:     }
44: }

In main() (lines 23–43), one instance of ThreadID is constructed (line 24) and passed into the constructor for ThreadIDMain (line 25). The instance of ThreadIDMain is referred to by shared and implements the Runnable interface. The main thread proceeds to create three new threads (threadA, threadB, and threadC) that will all simultaneously run the one instance referenced by shared (lines 28–39).

When each thread runs, the thread invokes the run() method (lines 8–16). Inside run(), getThreadID() is invoked and the result is printed (line 10). After sleeping for two seconds (line 11), getThreadID() is invoked again and the result is printed (line 12).

Listing 8.20 shows the output produced when ThreadIDMain is run. Your output should match.

1: threadA: in initialValue()
2: threadA: var.getThreadID()=10001
3: threadB: in initialValue()
4: threadB: var.getThreadID()=10002
5: threadC: in initialValue()
6: threadC: var.getThreadID()=10003
7: threadA: var.getThreadID()=10001
8: threadB: var.getThreadID()=10002
9: threadC: var.getThreadID()=10003

When threadA invokes getThreadID(), it indirectly causes initialValue() to be called (line 1). The unique ID for threadA is 10001 (line 2). When threadB and threadC invoke getThreadID(), they both get a new unique ID (lines 3–6). The second time that each of the threads invokes getThreadID(), a unique ID does not have to be generated and the same ID that was returned the first time is returned again (lines 7–9).

InheritableThreadLocal is a subclass of ThreadLocal and allows a thread-specific value to be inherited from the parent thread to the child thread. There are not any public methods on InheritableThreadLocal. It can be used directly as a special kind of ThreadLocal that passes its value from parent thread to child thread.

If you don't want to use the parent thread's value directly, you can override

protected Object childValue(Object parentValue)

to produce a customized child value at the time that the child thread is created. By default, childValue() simply returns parentValue.

The class InheritableThreadID (see Listing 8.21) demonstrates three different ways that thread-specific variables can behave regarding inheritance from parent thread to child thread. First, a ThreadLocal variable is used to demonstrate that the child thread will have a different thread-specific value than its parent thread does. Second, an InheritableThreadLocal is used without overriding childValue() to demonstrate that the child thread will have the exact same thread-specific value as its parent. Third, an InheritableThreadLocal is used with the childValue() method overridden to demonstrate that the child's value can be based on the parent's value.

  1: public class InheritableThreadID extends Object {
  2:     public static final int UNIQUE  = 101;
  3:     public static final int INHERIT = 102;
  4:     public static final int SUFFIX  = 103;
  5:
  6:     private ThreadLocal threadLocal;
  7:     private int nextID;
  8:
  9:     public InheritableThreadID(int type) {
 10:         nextID = 201;
 11:
 12:         switch ( type ) {
 13:             case UNIQUE:
 14:                 threadLocal = new ThreadLocal() {
 15:                         // override from ThreadLocal
 16:                         protected Object initialValue() {
 17:                             print("in initialValue()");
 18:                             return getNewID();
 19:                         }
 20:                     };
 21:                 break;
 22:
 23:             case INHERIT:
 24:                 threadLocal = new InheritableThreadLocal() {
 25:                         // override from ThreadLocal
 26:                         protected Object initialValue() {
 27:                             print("in initialValue()");
 28:                             return getNewID();
 29:                         }
 30:                     };
 31:                 break;
 32:
 33:             case SUFFIX:
 34:                 threadLocal = new InheritableThreadLocal() {
 35:                         // override from ThreadLocal
 36:                         protected Object initialValue() {
 37:                             print("in initialValue()");
 38:                             return getNewID();
 39:                         }
 40: 
 41:                         // override from InheritableThreadLocal
 42:                         protected Object childValue(
 43:                                     Object parentValue
 44:                                 ) {
 45:
 46:                             print("in childValue() - " +
 47:                                 "parentValue=" + parentValue);
 48:
 49:                             return parentValue + "-CH";
 50:                         }
 51:                     } ;
 52:                 break;
 53:             default:
 54:                 break;
 55:         }
 56:     }
 57:
 58:     private synchronized String getNewID() {
 59:         String id = "ID" + nextID;
 60:         nextID++;
 61:         return id;
 62:     }
 63:
 64:     public String getID() {
 65:         return (String) threadLocal.get();
 66:     }
 67:
 68:     public static void print(String msg) {
 69:         String name = Thread.currentThread().getName();
 70:         System.out.println(name + ": " + msg);
 71:     }
 72:
 73:     public static Runnable createTarget(InheritableThreadID id) {
 74:         final InheritableThreadID var = id;
 75:
 76:         Runnable parentRun = new Runnable() {
 77:             public void run() {
 78:                 print("var.getID()=" + var.getID());
 79:                 print("var.getID()=" + var.getID());
 80:                 print("var.getID()=" + var.getID());
 81: 
 82:                 Runnable childRun = new Runnable() {
 83:                         public void run() {
 84:                             print("var.getID()=" + var.getID());
 85:                             print("var.getID()=" + var.getID());
 86:                             print("var.getID()=" + var.getID());
 87:                         }
 88:                     };
 89:
 90:                 Thread parentT = Thread.currentThread();
 91:                 String parentName = parentT.getName();
 92:                 print("creating a child thread of " +
 93:                     parentName);
 94:
 95:                 Thread childT = new Thread(childRun,
 96:                         parentName + "-child");
 97:                 childT.start();
 98:             }
 99:         };
100:
101:         return parentRun;
102:     }
103:
104:     public static void main(String[] args) {
105:         try {
106:             System.out.println("======= ThreadLocal =======");
107:             InheritableThreadID varA =
108:                 new InheritableThreadID(UNIQUE);
109:
110:             Runnable targetA = createTarget(varA);
111:             Thread threadA = new Thread(targetA, "threadA");
112:             threadA.start();
113:
114:             Thread.sleep(2500);
115:             System.out.println("
======= " +
116:                 "InheritableThreadLocal =======");
117:
118:             InheritableThreadID varB =
119:                 new InheritableThreadID(INHERIT);
120:
121:             Runnable targetB = createTarget(varB);
122:             Thread threadB = new Thread(targetB, "threadB");
123:             threadB.start();
124: 
125:             Thread.sleep(2500);
126:             System.out.println("
======= " +
127:                 "InheritableThreadLocal - custom childValue()" +
128:                 " =======");
129:
130:             InheritableThreadID varC =
131:                 new InheritableThreadID(SUFFIX);
132:
133:             Runnable targetC = createTarget(varC);
134:             Thread threadC = new Thread(targetC, "threadC");
135:             threadC.start();
136:         } catch ( InterruptedException x ) {
137:             // ignore
138:         }
139:
140:     }
141: }

In the constructor for InheritableThreadID (lines 9–56), one of three different ThreadLocal instances is created. If type is UNIQUE (line 13), a plain ThreadLocal is used with its initialValue() method overridden to call getNewID() (lines 16–19). If type is INHERIT, an InheritableThreadLocal is used with its initialValue() method overridden to call getNewID() (lines 26–29). If type is SUFFIX, an InheritableThreadLocal is used with its initialValue() method overridden to call getNewID() (lines 36–39) and its childValue() method overridden to return the parent's value with "-CH" appended to it (lines 42–50).

Every time the synchronized method getNewID() is called, it generates a new String-based ID and returns it (lines 58–62).

When the getID() method (lines 64–66) is called, it invokes the get() method on whichever one of the three types of ThreadLocal variables was created in the constructor.

The static method createTarget() (lines 73–102) is used by main() to create a Runnable. When run() is invoked, the getID() method for the particular instance of InheritableThreadID is invoked three times (lines 78–80). Then this parent thread creates a new child thread (lines 95–97). The child thread is then started and invokes getID() three more times to see what value is returned to the child thread (lines 84–86).

In the main() method (lines 104–140), three different instances of InheritableThreadID are constructed and three different threads work with them.

First, varA refers to an InheritableThreadID that simply creates a unique ID for every thread—regardless of parent-child relationships (lines 107–108). A Runnable is created to use varA (line 110), and threadA is started to run it (lines 111–112).

Second, varB refers to an InheritableThreadID that allows the parent thread to pass its ID unmodified to the child thread—the child inherits the parent's value (lines 118–119). A Runnable is created to use varB (line 121), and threadB is started to run it (lines 122–123).

Third, varC refers to an InheritableThreadID that intercepts the passing of the value from the parent to child and adds a suffix to the child's value (lines 130–131). A Runnable is created to use varC (line 133), and threadC is started to run it (lines 134–135).

Listing 8.22 shows the output produced when InheritableThreadID is run. Your output should match.

 1: ======= ThreadLocal =======
 2: threadA: in initialValue()
 3: threadA: var.getID()=ID201
 4: threadA: var.getID()=ID201
 5: threadA: var.getID()=ID201
 6: threadA: creating a child thread of threadA
 7: threadA-child: in initialValue()
 8: threadA-child: var.getID()=ID202
 9: threadA-child: var.getID()=ID202
10: threadA-child: var.getID()=ID202
11:
12: ======= InheritableThreadLocal =======
13: threadB: in initialValue()
14: threadB: var.getID()=ID201
15: threadB: var.getID()=ID201
16: threadB: var.getID()=ID201
17: threadB: creating a child thread of threadB
18: threadB-child: var.getID()=ID201
19: threadB-child: var.getID()=ID201
20: threadB-child: var.getID()=ID201
21:
22: ======= InheritableThreadLocal - custom childValue() =======
23: threadC: in initialValue()
24: threadC: var.getID()=ID201
25: threadC: var.getID()=ID201
26: threadC: var.getID()=ID201
27: threadC: creating a child thread of threadC
28: threadC: in childValue() - parentValue=ID201
29: threadC-child: var.getID()=ID201-CH
30: threadC-child: var.getID()=ID201-CH
31: threadC-child: var.getID()=ID201-CH

Notice that when UNIQUE is used, the parent and child have completely different ID values: ID201 and ID202 (lines 1–10). When INHERIT is used, the parent and child have exactly the same ID values: ID201 (lines 12–20). When SUFFIX is used, the child's value is the same as the parent's with "-CH" added to the end: ID201 and ID201-CH (lines 22–31).