As BothInMethod (see Listing 7.4) shows, normally more than one thread is allowed to be inside a method at a time.

 1: public class BothInMethod extends Object {
 2:     private String objID;
 3:
 4:     public BothInMethod(String objID) {
 5:         this.objID = objID;
 6:     }
 7:
 8:     public void doStuff(int val) {
 9:         print("entering doStuff()");
10:         int num = val * 2 + objID.length();
11:         print("in doStuff() - local variable num=" + num);
12:
13:         // slow things down to make observations
14:         try { Thread.sleep(2000); } catch ( InterruptedException x ) { }
15:
16:         print("leaving doStuff()");
17:     }
18:
19:     public void print(String msg) {
20:         threadPrint("objID=" + objID + " - " + msg);
21:     }
22:
23:     public static void threadPrint(String msg) {
24:         String threadName = Thread.currentThread().getName();
25:         System.out.println(threadName + ": " + msg);
26:     }
27:
28:     public static void main(String[] args) {
29:         final BothInMethod bim = new BothInMethod("obj1");
30:
31:         Runnable runA = new Runnable() {
32:                 public void run() {
33:                     bim.doStuff(3);
34:                 }
35:             };
36:
37:         Thread threadA = new Thread(runA, "threadA");
38:         threadA.start();
39: 
40:         try { Thread.sleep(200); } catch ( InterruptedException x ) { }
41:
42:         Runnable runB = new Runnable() {
43:                 public void run() {
44:                     bim.doStuff(7);
45:                 }
46:             };
47:
48:         Thread threadB = new Thread(runB, "threadB");
49:         threadB.start();
50:     }
51: }

In main() (lines 28–50), one BothInMethod object is instantiated with an identifier of obj1 (line 29). Next, two threads are created to simultaneously access the doStuff() method. The first is named threadA, and the second threadB. After threadA is started (line 38), it invokes doStuff() and passes in 3 (line 33). About 200 milliseconds later, threadB is started (line 49) and invokes doStuff() on the same object, passing in 7 (line 44).

Both threadA and threadB will be inside doStuff() (lines 8–17) at the same time; threadA will enter first, and threadB will follow 200 milliseconds later. Inside doStuff(), the local variable num is calculated using the int passed in as parameter val and the member variable objID (line 10). Because threadA and threadB each pass in a different val, the local variable num will be different for each thread. A sleep is used inside doStuff() to slow things down enough to prove that both threads are simultaneously inside the same method of the same object (line 14).

Listing 7.5 shows the output produced when BothInMethod is run. Your output should match. Notice that threadA enters doStuff() first (line 1) and calculates that its local variable num is 10 (line 2). While threadA is still inside doStuff(), threadB also enters it (line 3) and calculates that its local variable num is 18 (line 4). Next, threadA reports that it is leaving doStuff() (line 5) and is followed closely by threadB (line 6).

1: threadA: objID=obj1 - entering doStuff()
2: threadA: objID=obj1 - in doStuff() - local variable num=10
3: threadB: objID=obj1 - entering doStuff()
4: threadB: objID=obj1 - in doStuff() - local variable num=18
5: threadA: objID=obj1 - leaving doStuff()
6: threadB: objID=obj1 - leaving doStuff()

More than one thread can be inside a method, and each thread keeps a copy of its own local variables. However, there are times when application constraints require that only one thread be permitted inside a method at a time. In OnlyOneInMethod (see Listing 7.6), the method modifier synchronized has been added to doStuff() (line 8). Other than this change, the rest of the class works the same as it did in BothInMethod.

 1: public class OnlyOneInMethod extends Object {
 2:     private String objID;
 3:
 4:     public OnlyOneInMethod(String objID) {
 5:         this.objID = objID;
 6:     }
 7:
 8:     public synchronized void doStuff(int val) {
 9:         print("entering doStuff()");
10:         int num = val * 2 + objID.length();
11:         print("in doStuff() - local variable num=" + num);
12:
13:         // slow things down to make observations
14:         try { Thread.sleep(2000); } catch ( InterruptedException x ) { }
15:
16:         print("leaving doStuff()");
17:     }
18:
19:     public void print(String msg) {
20:         threadPrint("objID=" + objID + " - " + msg);
21:     }
22:
23:     public static void threadPrint(String msg) {
24:         String threadName = Thread.currentThread().getName();
25:         System.out.println(threadName + ": " + msg);
26:     }
27:
28:     public static void main(String[] args) {
29:         final OnlyOneInMethod ooim = new OnlyOneInMethod("obj1");
30:
31:         Runnable runA = new Runnable() {
32:                 public void run() {
33:                     ooim.doStuff(3);
34:                 }
35:             };
36:
37:         Thread threadA = new Thread(runA, "threadA");
38:         threadA.start();
39: 
40:         try { Thread.sleep(200); } catch ( InterruptedException x ) { }
41:
42:         Runnable runB = new Runnable() {
43:                 public void run() {
44:                     ooim.doStuff(7);
45:                 }
46:             };
47:
48:         Thread threadB = new Thread(runB, "threadB");
49:         threadB.start();
50:     }
51: }

Only one thread at a time will be allowed into doStuff() because it is now synchronized. Listing 7.7 shows the output when OnlyOneInMethod is run. Your output should match. Notice that this time, threadA enters (line 1) and leaves (line 3) the doStuff() method before threadB is allowed to enter (line 4). The addition of the synchronized modifier successfully guarded doStuff() and allowed only one thread to enter at a time.

1: threadA: objID=obj1 - entering doStuff()
2: threadA: objID=obj1 - in doStuff() - local variable num=10
3: threadA: objID=obj1 - leaving doStuff()
4: threadB: objID=obj1 - entering doStuff()
5: threadB: objID=obj1 - in doStuff() - local variable num=18
6: threadB: objID=obj1 - leaving doStuff()

When a thread encounters a synchronized instance method, it blocks until it can get exclusive access to the object-level mutex lock. Mutex is short for mutual exclusion. A mutex lock can be held by only one thread at a time. Other threads waiting for the lock will block until it is released. When the lock is released, all the threads waiting for it compete for exclusive access. Only one will be successful, and the other threads will go back into a blocked state waiting for the lock to be released again.

If one synchronized method on an object invokes another synchronized method on that same object, it will not block trying to get the object-level lock because it already has exclusive access to the lock.

Every instance of a class has its own object-level lock. The TwoObjects class shown in Listing 7.8 demonstrates that each object has its own object-level lock.

 1: public class TwoObjects extends Object {
 2:     private String objID;
 3:
 4:     public TwoObjects(String objID) {
 5:         this.objID = objID;
 6:     }
 7:
 8:     public synchronized void doStuff(int val) {
 9:         print("entering doStuff()");
10:         int num = val * 2 + objID.length();
11:         print("in doStuff() - local variable num=" + num);
12:
13:         // slow things down to make observations
14:         try { Thread.sleep(2000); } catch ( InterruptedException x ) { }
15:
16:         print("leaving doStuff()");
17:     }
18:
19:     public void print(String msg) {
20:         threadPrint("objID=" + objID + " - " + msg);
21:     }
22:
23:     public static void threadPrint(String msg) {
24:         String threadName = Thread.currentThread().getName();
25:         System.out.println(threadName + ": " + msg);
26:     }
27:
28:     public static void main(String[] args) {
29:         final TwoObjects obj1 = new TwoObjects("obj1");
30:         final TwoObjects obj2 = new TwoObjects("obj2");
31:
32:         Runnable runA = new Runnable() {
33:                 public void run() {
34:                     obj1.doStuff(3);
35:                 }
36:             };
37: 
38:         Thread threadA = new Thread(runA, "threadA");
39:         threadA.start();
40:
41:         try { Thread.sleep(200); } catch ( InterruptedException x ) { }
42:
43:         Runnable runB = new Runnable() {
44:                 public void run() {
45:                     obj2.doStuff(7);
46:                 }
47:             };
48:
49:         Thread threadB = new Thread(runB, "threadB");
50:         threadB.start();
51:     }
52: }

This time, two different objects are created (lines 29–30). The doStuff() method of obj1 is invoked by threadA (line 34). A fraction of a second later, the doStuff() method of obj2 is invoked by threadB (line 45). The doStuff() method is synchronized (line 8), but this time there is no competition between threadA and threadB for exclusive access. Each thread gets exclusive access to the object-level lock of the instance it is working on. Listing 7.9 shows the output when TwoObjects is run. Your output should match.

1: threadA: objID=obj1 - entering doStuff()
2: threadA: objID=obj1 - in doStuff() - local variable num=10
3: threadB: objID=obj2 - entering doStuff()
4: threadB: objID=obj2 - in doStuff() - local variable num=18
5: threadA: objID=obj1 - leaving doStuff()
6: threadB: objID=obj2 - leaving doStuff()

Although the doStuff() method is synchronized, there is no competition for exclusive access to the object-level lock. Each instance, obj1 and obj2, has its own object-level lock. When threadA enters the doStuff() method of obj1 (line 1), it acquires exclusive access to the object-level lock for obj1. When threadB enters the doStuff() method of obj2 (line 3), it acquires exclusive access to the object-level lock for obj2.

CorruptWrite, shown in Listing 7.10, demonstrates the need to control concurrent access to a method. In this example, two strings are passed to a method for assignment into member variables. The trouble is that two threads are simultaneously trying to make assignments, and their assignments might get interleaved.

 1: public class CorruptWrite extends Object {
 2:     private String fname;
 3:     private String lname;
 4:
 5:     public void setNames(String firstName, String lastName) {
 6:         print("entering setNames()");
 7:         fname = firstName;
 8:
 9:         // A thread might be swapped out here, and may stay
10:         // out for a varying amount of time. The different
11:         // sleep times exaggerate this.
12:         if ( fname.length() < 5 ) {
13:             try { Thread.sleep(1000); }
14:             catch ( InterruptedException x ) { }
15:         } else {
16:             try { Thread.sleep(2000); } 
17:             catch ( InterruptedException x ) { }
18:         }
19:
20:         lname = lastName;
21:
22:         print("leaving setNames() - " + lname + ", " + fname);
23:     }
24:
25:     public static void print(String msg) {
26:         String threadName = Thread.currentThread().getName();
27:         System.out.println(threadName + ": " + msg);
28:     }
29:
30:     public static void main(String[] args) {
31:         final CorruptWrite cw = new CorruptWrite();
32:
33:         Runnable runA = new Runnable() {
34:                 public void run() {
35:                     cw.setNames("George", "Washington");
36:                 }
37:             };
38:
39:         Thread threadA = new Thread(runA, "threadA");
40:         threadA.start();
41: 
42:         try { Thread.sleep(200); } 
43:         catch ( InterruptedException x ) { }
44:
45:         Runnable runB = new Runnable() {
46:                 public void run() {
47:                     cw.setNames("Abe", "Lincoln");
48:                 }
49:             };
50:
51:         Thread threadB = new Thread(runB, "threadB");
52:         threadB.start();
53:     }
54: }

In main() (lines 30–53), a single instance of CorruptWrite is created and referred to by cw (line 31). Two threads are started and both call the setNames() method passing in a first and last name. First, threadA executes cw.setNames("George", "Washington") (line 35) and 200 milliseconds later, threadB executes cw.setNames("Abe", "Lincoln") (line 47).

CorruptWrite has two member variables, fname and lname (lines 2–3), that hold the names passed to setNames(). Inside setNames() (lines 5–23), the first parameter passed is assigned to fname (line 7). Then, depending on the length of fname, the thread sleeps for either one or two seconds (lines 12–18). After the nap, the second parameter is assigned to the member variable lname (line 20).

I used the variable length sleep inside setNames() to exaggerate what might really happen. The exaggeration will help to land the object in an inconsistent state. Real-world code would look more like the following:

public void setNames(String firstName, String lastName) {
   fname = firstName;
   lname = lastName;
}

This revised and quick setNames() method is still subtly dangerous in a multithreaded environment. It is possible that threadA could be swapped off the processor by the thread scheduler just after making the fname assignment, and just before making the lname assignment. Although threadA is halfway complete with its work, threadB could come along and assign its parameters to both fname and lname. When threadA gets scheduled to run again, it finishes up by assigning its second parameter to lname. This leaves the object in an inconsistent state. Most of the time this code will run fine, but now and then it will corrupt the object. By adding the variable-length sleeps in the setNames() method used in CorruptWrite, I have guaranteed that the object will wind up corrupted for the purposes of demonstration. Table 7.2 summarizes the states of the object at various points in time.

Listing 7.11 shows the output produced when CorruptWrite is run. Your output should match. Before going to sleep, threadA reports that it has entered the setNames() method (line 1). While threadA is sleeping, threadB comes along and enters setNames() (line 2). It assigns values to both member variables and just before returning, prints their values (line 3). When threadA wakes up, it assigns its second value and just before returning, prints the current values of the member variables (line 4) showing the inconsistent state. The name-pair "Abe" and "Washington" was never passed to setNames(), but this is the current (corrupted) state of the object.

1: threadA: entering setNames()
2: threadB: entering setNames()
3: threadB: leaving setNames() - Lincoln, Abe
4: threadA: leaving setNames() - Washington, Abe

FixedWrite (see Listing 7.12) corrects the dangerous code in CorruptWrite simply by adding the synchronized method modifier to the setNames() method (line 5). Otherwise, FixedWrite is basically the same as CorruptWrite.

 1: public class FixedWrite extends Object {
 2:     private String fname;
 3:     private String lname;
 4:
 5:     public synchronized void setNames(
 6:                 String firstName,
 7:                 String lastName
 8:             ) {
 9:
10:         print("entering setNames()");
11:         fname = firstName;
12:
13:         // A thread might be swapped out here, and may stay
14:         // out for a varying amount of time. The different
15:         // sleep times exaggerate this.
16:         if ( fname.length() < 5 ) {
17:             try { Thread.sleep(1000); } 
18:             catch ( InterruptedException x ) { }
19:         } else {
20:             try { Thread.sleep(2000); }
21:             catch ( InterruptedException x ) { }
22:         }
23:
24:         lname = lastName;
25:
26:         print("leaving setNames() - " + lname + ", " + fname);
27:     }
28:
29:     public static void print(String msg) {
30:         String threadName = Thread.currentThread().getName();
31:         System.out.println(threadName + ": " + msg);
32:     }
33:
34:     public static void main(String[] args) {
35:         final FixedWrite fw = new FixedWrite();
36:
37:         Runnable runA = new Runnable() {
38:                 public void run() {
39:                     fw.setNames("George", "Washington");
40:                 }
41:             };
42:
43:         Thread threadA = new Thread(runA, "threadA");
44:         threadA.start();
45:
46:         try { Thread.sleep(200); } 
47:         catch ( InterruptedException x ) { }
48:
49:         Runnable runB = new Runnable() {
50:                 public void run() {
51:                     fw.setNames("Abe", "Lincoln");
52:                 }
53:             };
54:
55:         Thread threadB = new Thread(runB, "threadB");
56:         threadB.start();
57:     }
58: }

If you make setNames() a sychronized method, each thread that tries to enter this method will block until it can get exclusive access to the object-level lock. Now when threadA goes to sleep (or if the thread scheduler had otherwise decided to swap it out), threadB is prevented from entering the method. When threadA finally completes its work inside setNames(), it automatically releases the lock as it returns. Now, threadB is able to gain exclusive access to the lock and enters setNames().

The variable-length sleeps are still inside setNames() to demonstrate that the addition of the synchronized method modifier solved the problem. Real-world code (that is truly safe) would look more like the following:

public synchronized void setNames(String firstName, String lastName) {
   fname = firstName;
   lname = lastName;
}

Listing 7.13 shows the output when FixedWrite is run. Your output should match. Notice that threadB doesn't enter setNames() (line 3) until threadA has left it (line 2). In this fixed version, both threadA and threadB print consistent name-pairs when they leave (lines 2, 4).

1: threadA: entering setNames()
2: threadA: leaving setNames() - Washington, George
3: threadB: entering setNames()
4: threadB: leaving setNames() - Lincoln, Abe

FixedWrite solved the problem by ensuring that the object was left in a consistent state by a call to setNames(). The object is consistent both before and after a thread invokes setNames(), but it is inconsistent while a thread is inside setNames(). If one thread is executing setNames() at the same time that a second thread is accessing the member variables, the second thread might occasionally see an inconsistent name-pair. DirtyRead (see Listing 7.14) demonstrates this problem.

 1: public class DirtyRead extends Object {
 2:     private String fname;
 3:     private String lname;
 4:
 5:     public String getNames() {
 6:         return lname + ", " + fname;
 7:     }
 8:
 9:     public synchronized void setNames(
10:                 String firstName,
11:                 String lastName
12:             ) {
13:
14:         print("entering setNames()");
15:         fname = firstName;
16:
17:         try { Thread.sleep(1000); } 
18:         catch ( InterruptedException x ) { }
19:
20:         lname = lastName;
21:         print("leaving setNames() - " + lname + ", " + fname);
22:     }
23:
24:     public static void print(String msg) {
25:         String threadName = Thread.currentThread().getName();
26:         System.out.println(threadName + ": " + msg);
27:     }
28:
29:     public static void main(String[] args) {
30:         final DirtyRead dr = new DirtyRead();
31:         dr.setNames("George", "Washington"); // initially
32:
33:         Runnable runA = new Runnable() {
34:                 public void run() {
35:                     dr.setNames("Abe", "Lincoln");
36:                 }
37:             };
38:
39:         Thread threadA = new Thread(runA, "threadA");
40:         threadA.start();
41: 
42:         try { Thread.sleep(200); } 
43:         catch ( InterruptedException x ) { }
44:
45:         Runnable runB = new Runnable() {
46:                 public void run() {
47:                     print("getNames()=" + dr.getNames());
48:                 }
49:             };
50:
51:         Thread threadB = new Thread(runB, "threadB");
52:         threadB.start();
53:     }
54: }

DirtyRead is an evolution of FixedWrite. A new method called getNames() has been added (lines 5–7). This method constructs and returns a new String that is a combination of the lname and fname member variables (line 6).

The setNames() method (lines 9–22) is still synchronized (line 9). It has been simplified to just sleep for one second between the setting of the first name and last name.

Inside main() (lines 29–53), a few different actions are taken. First, just after the DirtyRead instance is created (line 30), setNames() is invoked by the main thread to initially set the names to "George" and "Washington" (line 31). After that, threadA invokes setNames(), passing in "Abe" and "Lincoln" (line 35). threadA runs for about 200 milliseconds before threadB is started (line 42).

The setNames() method is still slow, so while the names are in the process of being changed by threadA, threadB invokes the getNames() method (line 47). Listing 7.15 shows the output when DirtyRead is run. Your output should match.

1: main: entering setNames()
2: main: leaving setNames() - Washington, George
3: threadA: entering setNames()
4: threadB: getNames()=Washington, Abe
5: threadA: leaving setNames() - Lincoln, Abe

The setNames() method is invoked by threadA (line 3). Before it can finish setting both names, threadB invokes getNames() (line 4). It returns the combination of "Abe" and "Washington," catching the object in an inconsistent state. When threadA finishes executing setNames(), the object is back to a consistent state (line 5).

It's an unavoidable fact that the object must be in an inconsistent state for a brief period of time, even with everything except the assignments taken out:

public synchronized void setNames(String firstName, String lastName) {
   fname = firstName;
   lname = lastName;
}

No matter how fast the processor is, it's possible that the thread scheduler could swap out the thread making the changes after it has changed fname but before it has changed lname. Holding an object-level lock does not prevent a thread from being swapped out. And if it is swapped out, it continues to hold the object-level lock. Because of this, care must be taken to ensure that all reads are blocked when the data is in an inconsistent state. CleanRead (see Listing 7.16) simply adds the synchronized method modifier to getNames() to control concurrent reading and writing.

 1: public class CleanRead extends Object {
 2:     private String fname;
 3:     private String lname;
 4:
 5:     public synchronized String getNames() {
 6:         return lname + ", " + fname;
 7:     }
 8:
 9:     public synchronized void setNames(
10:                 String firstName,
11:                 String lastName
12:             ) {
13:
14:         print("entering setNames()");
15:         fname = firstName;
16:
17:         try { Thread.sleep(1000); } 
18:         catch ( InterruptedException x ) { }
19:
20:         lname = lastName;
21:         print("leaving setNames() - " + lname + ", " + fname);
22:     }
23:
24:     public static void print(String msg) {
25:         String threadName = Thread.currentThread().getName();
26:         System.out.println(threadName + ": " + msg);
27:     }
28:
29:     public static void main(String[] args) {
30:         final CleanRead cr = new CleanRead();
31:         cr.setNames("George", "Washington"); // initially
32:
33:         Runnable runA = new Runnable() {
34:                 public void run() {
35:                     cr.setNames("Abe", "Lincoln");
36:                 }
37:             };
38:
39:         Thread threadA = new Thread(runA, "threadA");
40:         threadA.start();
41: 
42:         try { Thread.sleep(200); } 
43:         catch ( InterruptedException x ) { }
44:
45:         Runnable runB = new Runnable() {
46:                 public void run() {
47:                     print("getNames()=" + cr.getNames());
48:                 }
49:             };
50:
51:         Thread threadB = new Thread(runB, "threadB");
52:         threadB.start();
53:     }
54: }

Inside main() (lines 29–53), the same actions are taken as were for DirtyRead. First, just after the CleanRead instance is created (line 30), setNames() is invoked by the main thread to initially set the names to "George" and "Washington" (line 31). After that, threadA invokes setNames(), passing in "Abe" and "Lincoln" (line 35). threadA runs for about 200 milliseconds before threadB is started (line 42).

The setNames() method is still slow, so while the names are in the process of being changed by threadA, threadB invokes the getNames() method (line 47). Because getNames() is now synchronized, threadB blocks trying to get exclusive access to the object-level lock. When threadA returns from setNames(), it automatically releases the object-level lock. Then threadB proceeds to acquire the object-level lock and enters the getNames() method. Listing 7.17 shows the output when CleanRead is run. Your output should match.

1: main: entering setNames()
2: main: leaving setNames() - Washington, George
3: threadA: entering setNames()
4: threadA: leaving setNames() - Lincoln, Abe
5: threadB: getNames()=Lincoln, Abe

Although threadB invokes getNames() before threadA is finished with setNames(), it blocks waiting to get exclusive access to the object-level lock. This time, getNames() returns a valid name-pair (line 5).

A synchronized block can be used to reduce the time that the object-level lock is held. If a method does a lot of other things that don't require access to the member variables, it can shorten the time that it holds the lock to just the critical portion:

public void setValues(int x, double ratio) {
    // Some other, long-running statements that don't work
    // with the member variables go here.
    // ...
    double processedValA = // ... long calculation ...
    double processedValB = // ... long calculation ...
    // ...
    synchronized ( this ) {
        a = processedValA;
        b = processedValB;
    }
}

In setValues(), exclusive access to the object-level lock is not needed until the time-consuming calculations have been made and the results are ready to be stored. At the bottom of the method, the object-level lock is acquired and held briefly to simply assign new values to the member variables a and b.

When a synchronized statement is used as follows,

synchronized ( mutex ) {
    // block of code
}

the reference mutex indicates the object whose object-level lock must be acquired before entering the statement block. It can be a reference to any object in the VM, not just this. Regardless of how a thread leaves a synchronized block, it automatically releases the lock. This includes a return statement, a throw statement, or just falling through to the next statement after the block. Calling a method from within the synchronized block does not constitute leaving the block (the lock is still held).

Sometimes you will need to call two synchronized methods on an object and be sure that no other thread sneaks in between the calls. Consider this code fragment from a class called Bucket:

public class Bucket extends Object {
    // ...
    public synchronized boolean isSpaceAvailable() { // ...
    public synchronized void add(BucketItem o)
                         throws NoSpaceAvailableException { // ...
    public synchronized BucketItem remove() { // ...
    // ...
}

All three methods use the synchronized modifier to control concurrent access by multiple threads. Items of the type BucketItem can be added and removed from Bucket. When using the object, a call should be made to isSpaceAvailable() before trying to add another BucketItem, to prevent the NoSpaceAvailableException from being thrown. Of course, there are other ways to design Bucket, but imagine that you are stuck with this class as is. To add an item to Bucket, the following code fragment could be used:

Bucket b = // ...
// ...
if ( b.isSpaceAvailable() ) {
    b.add(item);
}

This is fine if only one thread is interacting with this instance of Bucket. But if multiple threads are potentially trying to add BucketItem objects to the same Bucket, a new approach has to be taken to avoid a race condition. Imagine that threadA checks and sees that space is available, but before it actually adds its item, threadB checks and also sees that space is available. Now threadA and threadB are racing to actually add an item. Only one can win the race, and that thread gets to add its item. The other thread will fail to add its item and will throw a NoSpaceAvailableException. To prevent this problem, a synchronized block should be wrapped around the two method calls:

Bucket b = // ...
// ...
synchronized ( b ) {
    if ( b.isSpaceAvailable() ) {
        b.add(item);
    }
}

The synchronized block uses the object-level lock on b, the Bucket instance. This is the same lock that must be acquired before entering the isSpaceAvailable() and add() methods. If a thread can get the object-level lock and enter the synchronized block, it is guaranteed to be able to invoke isSpaceAvailable() and add() without blocking. Because it already has the object-level lock for b, there is no delay or competition to enter the synchronized methods. In addition, no other thread can invoke these methods until the first thread leaves the synchronized block.

Imagine that threadA is able to get exclusive access to the object-level lock on b and enters the synchronized block. It checks to see if space is available, but before it actually adds its item, the thread scheduler swaps it out. threadB comes along and is blocked from acquiring the lock on b, so it is swapped out. Regardless of any particular thread scheduling, no other thread will be able to get the object-level lock on b until threadA releases it. When threadA is finally scheduled to run again, it will proceed to add its element to b and release the lock as it leaves the synchronized block. After threadA leaves the synchronized block, threadB can acquire the object-level lock on b.

The Vector class is used to hold an expandable array of objects. Some of its methods are shown following:

public final synchronized void addElement(Object o)
public final synchronized void insertElementAt(Object o, int pos)
public final synchronized void setElementAt(Object o, int pos)
public final synchronized void removeElementAt(int pos)
public final synchronized boolean removeElement(Object o)
public final synchronized void removeAllElements()
public final int size()
public final synchronized Object elementAt(int pos)
public final synchronized Object firstElement()
public final synchronized Object lastElement()
public final synchronized Enumeration elements()
public final boolean contains(Object obj)
public final int indexOf(Object obj)

I generated this information using reflection on the Vector class in JDK 1.1 (information on 1.2 and Collections is included later in this chapter). Notice that many of the methods are synchronized—particularly the ones used to add and remove elements from the Vector.

SafeVectorCopy in Listing 7.18 shows how a synchronized block can be used in conjunction with the synchronized methods of Vector to copy the current contents of the Vector into a String[].

 1: import java.util.*;
 2:
 3: public class SafeVectorCopy extends Object {
 4:     public static void main(String[] args) {
 5:         Vector vect = new Vector();
 6:         vect.addElement("Synchronization");
 7:         vect.addElement("is");
 8:         vect.addElement("important");
 9:
10:         String[] word;
11:
12:         synchronized ( vect ) {
13:             int size = vect.size();
14:             word = new String[size];
15:
16:             for ( int i = 0; i < word.length; i++ ) {
17:                 word[i] = (String) vect.elementAt(i);
18:             }
19:         }
20:
21:         System.out.println("word.length=" + word.length);
22:         for ( int i = 0; i < word.length; i++ ) {
23:             System.out.println("word[" + i + "]=" + word[i]);
24:         }
25:     }
26: }

In SafeVectorCopy, three strings are added to a new Vector referred to by vect (lines 5–8). The synchronized block (lines 12–19) uses the object-level lock of vect to keep out other threads while the copying is taking place. Inside the block, the current number of elements in the Vector is used to allocate a new String[] (lines 13–14). One by one, each element is retrieved, cast into a String, and stored into the array (lines 16–18). If another thread had been trying to access vect to add or remove elements during this time, it would have been blocked until the thread doing the copying left the synchronized block.

Vector and Hashtable were originally designed to be multithread-safe. Take Vector, for example—the methods used to add and remove elements are synchronized. If only one thread will ever interact with an instance of Vector, the work required to acquire and release the object-level lock is wasted.

The designers of the Collections API wanted to avoid the overhead of synchronization when it wasn't necessary. As a result, none of the methods that alter the contents of a collection are synchronized. If a Collection or Map will be accessed by multiple threads, it should be wrapped by a class that synchronizes all the methods.

There are several static methods in the Collections class that are used to wrap unsynchronized collections with synchronized methods:

public static Collection synchronizedCollection(Collection c)
public static List synchronizedList(List l)
public static Map synchronizedMap(Map m)
public static Set synchronizedSet(Set s)
public static SortedMap synchronizedSortedMap(SortedMap sm)
public static SortedSet synchronizedSortedSet(SortedSet ss)

Basically, these methods return new classes that have synchronized versions of the collections'methods. To create a List that is multithread-safe and backed by an ArrayList, use the following:

List list = Collections.synchronizedList(new ArrayList());

Notice that the ArrayList instance was immediately wrapped and that no direct reference to the unsynchronized ArrayList exists. This is the safest approach. If another thread was to get a direct reference to the ArrayList instance, it could perform unsynchronized changes.

The SafeListCopy class in Listing 7.25 shows three different ways that the contents of a List can be safely copied into a String[] in a multithreaded environment.

 1: import java.util.*;
 2:
 3: public class SafeListCopy extends Object {
 4:     public static void printWords(String[] word) {
 5:         System.out.println("word.length=" + word.length);
 6:         for ( int i = 0; i < word.length; i++ ) {
 7:             System.out.println("word[" + i + "]=" + word[i]);
 8:         }
 9:     }
10:
11:     public static void main(String[] args) {
12:         // To be safe, only keep a reference to the
13:         // *synchronized* list so that you are sure that
14:         // all accesses are controlled.
15:         List wordList =
16:                 Collections.synchronizedList(new ArrayList());
17:
18:         wordList.add("Synchronization");
19:         wordList.add("is");
20:         wordList.add("important");
21:
22:         // First technique (favorite)
23:         String[] wordA =
24:                 (String[]) wordList.toArray(new String[0]);
25:
26:         printWords(wordA);
27:
28:         // Second technique
29:         String[] wordB;
30:         synchronized ( wordList ) {
31:             int size = wordList.size();
32:             wordB = new String[size];
33:             wordList.toArray(wordB);
34:         }
35:
36:         printWords(wordB);
37:
38:         // Third technique (the 'synchronized'*is* necessary)
39:         String[] wordC;
40:         synchronized ( wordList ) {
41:             wordC = (String[]) wordList.toArray(
42:                                 new String[wordList.size()]);
43:         }
44: 
45:         printWords(wordC);
46:     }
47: }

In SafeListCopy, a multithread-safe version of List is constructed using Collections.synchronizedList() and is backed by an ArrayList instance (lines 15–16). Three Strings are added to the List (lines 18–20).

The first technique for copying the contents of wordList into a String[] is the simplest and exploits a convenient feature of collections. The toArray() method is used to copy the contents into an array of the type specified by the parameter (lines 23–24). Because the toArray() method was synchronized by wrapping, this is all that is necessary to safely copy the contents. If other threads were trying to add or remove elements during this operation, they would be blocked until it completed.

The second technique uses a synchronized statement to keep other threads out while two steps are performed (lines 29–34). The first step is to determine the exact length needed for the destination String[] and to allocate the array (lines 31–32). The second step is to pass this perfectly sized array to the toArray() method (line 33). This second technique has a slight efficiency advantage over the first one in that it does not create a throw-away, zero-length String[].

The third technique combines the steps of the second technique into one line (lines 39–43). It still needs to be inside a synchronized block because another thread could intervene after the size() method is called but before the toArray() method is called (line 42).

I would recommend that you stick with the first technique in most cases because it is the most straightforward and least error-prone. Listing 7.26 shows the output when SafeListCopy is run. Your output should match. Notice that in all three cases the proper set of strings is produced.

word.length=3
word[0]=Synchronization
word[1]=is
word[2]=important
word.length=3
word[0]=Synchronization
word[1]=is
word[2]=important
word.length=3
word[0]=Synchronization
word[1]=is
word[2]=important

The elements of a Collection can be stepped through one by one by using an Iterator. In a multithreaded environment, you will generally want to block other threads from adding or removing elements while you are iterating through the current collection of elements.

The class SafeCollectionIteration shown in Listing 7.27 demonstrates how to block other threads while using an Iterator.

 1: import java.util.*;
 2:
 3: public class SafeCollectionIteration extends Object {
 4:     public static void main(String[] args) {
 5:         // To be safe, only keep a reference to the
 6:         // *synchronized* list so that you are sure
 7:         // that all accesses are controlled.
 8:
 9:         // The collection *must* be synchronized
10:         // (a List in this case).
11:         List wordList =
12:                 Collections.synchronizedList(new ArrayList());
13:
14:         wordList.add("Iterators");
15:         wordList.add("require");
16:         wordList.add("special");
17:         wordList.add("handling");
18:
19:         // All of this must be in a synchronized block to
20:         // block other threads from modifying wordList while
21:         // the iteration is in progress.
22:         synchronized ( wordList ) {
23:             Iterator iter = wordList.iterator();
24:             while ( iter.hasNext() ) {
25:                 String s = (String) iter.next();
26:                 System.out.println("found string: " + s +
27:                     ", length=" + s.length());
28:             }
29:         }
30:     }
31: }

First, an ArrayList is wrapped in synchronization to ensure safe multithread access (lines 11–12). Next, four strings are added to the List (lines 14–17). A synchronized statement block is used to gain and hold the object-level lock for the List until the iteration is complete (lines 22–29). When the lock is safely held, an Iterator is retrieved by invoking the iterator() method (line 23) of Collection (List IS-A Collection). The hasNext() and next() methods of Iterator are used to traverse through the elements (lines 24–28). When the iteration is complete, the lock is released, and other threads (if there were any) are free to add and remove elements again.

Listing 7.28 shows the output produced when SafeCollectionIteration is run. Your output should match.

found string: Iterators, length=9
found string: require, length=7
found string: special, length=7
found string: handling, length=8

Deadlocks can be extremely difficult to track down. Generally, most of an application will continue to run, but a couple of threads will be stuck in a deadlock. To make matters worse, deadlocks can hide in code for quite a while, waiting for a rare condition to occur. An application can run fine 99 out of 100 times and only deadlock when the thread scheduler happens to run the threads in a slightly different order. Deadlock avoidance is a difficult task.

Most code is not vulnerable to deadlocks, but for the code that is, try following these guidelines to help avoid deadlocks: