Synchronization

    class SpeechSynthesizer {
        synchronized void say( String words ) {
            // speak
        }
    }

Because say() is an instance method, a thread must acquire the lock on the SpeechSynthesizer instance it’s using before it can invoke the say() method. When say() has completed, it gives up the lock, which allows the next waiting thread to acquire the lock and run the method. It doesn’t matter whether the thread is owned by the SpeechSynthesizer itself or some other object; every thread must acquire the same lock, that of the SpeechSynthesizer instance. If say() were a class (static) method instead of an instance method, we could still mark it as synchronized. In this case, because no instance object is involved, the lock is on the class object itself.

Often, you want to synchronize multiple methods of the same class so that only one method modifies or examines parts of the class at a time. All static synchronized methods in a class use the same class object lock. By the same token, all instance methods in a class use the same instance object lock. In this way, Java can guarantee that only one of a set of synchronized methods is running at a time. For example, a SpreadSheet class might contain a number of instance variables that represent cell values as well as some methods that manipulate the cells in a row:

    class SpreadSheet {
        int cellA1, cellA2, cellA3;

        synchronized int sumRow() {
            return cellA1 + cellA2 + cellA3;
        }

        synchronized void setRow( int a1, int a2, int a3 ) {
            cellA1 = a1;
            cellA2 = a2;
            cellA3 = a3;
        }
        ...
    }

In this example, methods setRow() and sumRow() both access the cell values. You can see that problems might arise if one thread were changing the values of the variables in setRow() at the same moment another thread was reading the values in sumRow(). To prevent this, we have marked both methods as synchronized. When threads are synchronized, only one runs at a time. If a thread is in the middle of executing setRow() when another thread calls sumRow(), the second thread waits until the first one finishes executing setRow() before it runs sumRow(). This synchronization allows us to preserve the consistency of the SpreadSheet. The best part is that all this locking and waiting is handled by Java; it’s invisible to the programmer.

    synchronized ( myObject ) {
        // Functionality that needs exclusive access to resources
    }

This code block can appear in any method. When it is reached, the thread has to acquire the lock on myObject before proceeding. In this way, we can synchronize methods (or parts of methods) in different classes in the same way as methods in the same class.

A synchronized instance method is, therefore, equivalent to a method with its statements synchronized on the current object. Thus:

    synchronized void myMethod () {
        ...
}

    void myMethod () {
        synchronized ( this ) {
            ...
        }
    }

    class MyThing {
        synchronized void waiterMethod() {
            // do some stuff
            wait();   // now wait for notifier to do something
            // continue where we left off
        }
        synchronized void notifierMethod() {
            // do some stuff
            notify();  // notify waiter that we've done it
            // continue doing stuff
        }
        synchronized void relatedMethod() {
            // do some related stuff
        }
        ...
    }

Let’s assume that a thread named waiter gets through the gate first and begins executing waiterMethod(). The two other threads are initially blocked when trying to acquire the lock for the MyThing object. When waiter executes the wait() method, it relinquishes its hold on the lock and goes to sleep. Now two viable threads are waiting for the lock. Which thread gets it depends on several factors, including chance and the priorities of the threads. (We’ll discuss thread scheduling in the next section.)

Let’s suppose that notifier is the next thread to acquire the lock, so it begins to run notifierMethod(). waiter continues to sleep, and related languishes, waiting for its turn. When notifier executes the call to notify(), the runtime system prods the waiter thread, effectively telling it something has changed. waiter wakes up and rejoins related in vying for the MyThing lock. It doesn’t receive the lock automatically; it just changes its state from “Leave me alone” to “I want the lock.”

At this point, notifier still owns the lock and continues to hold it until the synchronized notifierMethod() returns, or perhaps executes a wait() itself. At that point, the other two methods get to fight over the lock. waiter would like to continue executing waiterMethod() from the point where it left off, while related, which has been patient, would like to get started. We’ll let you choose your own ending for the story.

    import java.util.*;

    public class Consumer implements Runnable {
        Producer producer;

        Consumer( Producer producer ) {
            this.producer = producer;
        }

        public void run() {
            while ( true ) {
                String message = producer.getMessage();
                System.out.println("Got message: " + message);
                try {
                    Thread.sleep( 2000 );
                } catch ( InterruptedException e ) { }
            }
        }

        public static void main(String args[]) {
            Producer producer = new Producer();
            new Thread( producer ).start();
            Consumer consumer = new Consumer( producer );
            new Thread( consumer ).start();
        }
    }

    public class Producer implements Runnable{
        static final int MAXQUEUE = 5;
        private List messages = new ArrayList();

        public void run() {
            while ( true ) {
                putMessage();
                try {
                    Thread.sleep( 1000 );
                } catch ( InterruptedException e ) { }
            }
        }

        // called by Producer internally
        private synchronized void putMessage()
        {
            while ( messages.size() >= MAXQUEUE )
                try {
                    wait();
                } catch( InterruptedException e ) { }

            messages.add( new java.util.Date().toString() );
            notify();
        }

        // called by Consumer externally
        public synchronized String getMessage()
        {
            while ( messages.size() == 0 )
                try {
                    notify();
                    wait();
                } catch( InterruptedException e ) { }
            String message = (String)messages.remove(0);
            notify();
            return message;
        }
    }

For convenience, we have included a main() method in the Consumer class that runs the complete example. It creates a Consumer that is tied to a Producer and starts the two classes. You can run the example as follows:

    % java Consumer

This produces the timestamp messages created by the Producer:

    Got message: Sun Dec 19 03:35:55 CST 2006
    Got message: Sun Dec 19 03:35:56 CST 2006
    Got message: Sun Dec 19 03:35:57 CST 2006
    ...

The timestamps initially show a spacing of one second even though they appear every two seconds. Our Producer runs faster than our Consumer. Producer would like to generate a new message every second, while Consumer gets around to reading and displaying a message only every two seconds. Can you see how long it will take the message queue to fill up? What happens when it does?

Let’s look at the code. We are using a few new tools here. Producer and Consumer implement the Runnable interface, and each has a thread associated with it. The Producer and Consumer classes pass messages through an instance of a java.util.List object. We haven’t discussed the List class yet, but it is essentially a dynamic array of elements. We use this one as a queue by simply adding and removing elements in first-in, first-out order. The List has no maximum capacity of its own, but we impose one with our own check.

    public class NamedConsumer implements Runnable
    {
        Producer producer;
        String name;

        NamedConsumer(String name, Producer producer) {
            this.producer = producer;
            this.name = name;
        }

        public void run() {
            while ( true ) {
                String message = producer.getMessage();
                System.out.println(name + " got message: " + message);
                try {
                    Thread.sleep( 2000 );
                } catch ( InterruptedException e ) { }
            }
        }

        public static void main(String args[]) {
            Producer producer = new Producer();
            new Thread( producer ).start();

            NamedConsumer consumer = new NamedConsumer( "One", producer );
            new Thread( consumer ).start();
            consumer = new NamedConsumer( "Two", producer );
            new Thread( consumer ).start();
        }
    }

    One got message: Sat Mar 18 20:00:01 CST 2006
    Two got message: Sat Mar 18 20:00:02 CST 2006
    One got message: Sat Mar 18 20:00:03 CST 2006
    Two got message: Sat Mar 18 20:00:04 CST 2006
    One got message: Sat Mar 18 20:00:05 CST 2006
    Two got message: Sat Mar 18 20:00:06 CST 2006
    One got message: Sat Mar 18 20:00:07 CST 2006
    Two got message: Sat Mar 18 20:00:08 CST 2006
    ...

    ThreadLocal userID = new ThreadLocal();
    userID.set("Pat");  // called by thread 1
    userID.set("Bob"); // called by thread 2
    userID.get(); // thread 1 gets "Pat"
    userID.get(); // thread 2 gets "Bob"

You can use an instance of ThreadLocal anywhere you might use a static or instance variable to automatically maintain separate values for each thread. You can also extend ThreadLocal and override its initialValue() method. The ThreadLocal will then use this method to initialize its value once, the first time get() is called:

    class MyThreadLocalFactory extends ThreadLocal<Factory> {
        protected Factory initialValue() { return new MyFactory(); }
    }

ThreadLocals are implemented using a Map attached to each Thread instance, so their values will disappear when the Thread is no longer used and garbage is collected.