Understanding java.lang.Thread.State: WAITING (parking)

1. Overview

In this article, we’ll go over a Java thread state — specifically, Thread.State.WAITING. We’ll look at the methods with which a thread enters this state and the differences between them. Finally, we’ll take a closer look at the LockSupport class, which offers several static utility methods for synchronization.

2. Entering Thread.State.WAITING

Java provides multiple ways to put a thread in the WAITING state.

2.1. Object.wait()

One of the most standard ways we can put a thread in the WAITING state is through the wait() method. When a thread owns an object’s monitor, we can pause its execution until another thread has completed some work and wakes it up using the notify() method. While execution is paused, the thread is in the WAITING (on object monitor) state, which is also reported in the program’s thread dump:

"WAITING-THREAD" #11 prio=5 os_prio=0 tid=0x000000001d6ff800 nid=0x544 in Object.wait() [0x000000001de4f000]
   java.lang.Thread.State: WAITING (on object monitor)

2.2. Thread.join()

Another method we can use to pause a thread’s execution is through the join() call. When our main thread needs to wait for a worker thread to finish first, we can call join() on the worker thread instance from the main thread. Execution will be paused and the main thread will enter the WAITING state, reported from jstack as WAITING (on object monitor):

"MAIN-THREAD" #12 prio=5 os_prio=0 tid=0x000000001da4f000 nid=0x25f4 in Object.wait() [0x000000001e28e000]
   java.lang.Thread.State: WAITING (on object monitor)

2.3. LockSupport.park()

Finally, we can also set a thread to the WAITING state with the park() static method of the LockSupport class. Calling park() will stop execution for the current thread and put it into the WAITING state — and more specifically, the WAITING (parking) state as the jstack report will show:

"PARKED-THREAD" #11 prio=5 os_prio=0 tid=0x000000001e226800 nid=0x43cc waiting on condition [0x000000001e95f000]
   java.lang.Thread.State: WAITING (parking)

Since we want to better understand thread parking and unparking, let’s take a closer look at how this works.

3. Parking and Unparking Threads

As we previously saw, we can park and unpark threads by using the facilities provided by the LockSupport class. This class is a wrapper of the Unsafe class, and most of its methods immediately delegate to it. However, since Unsafe is considered an internal Java API and shouldn’t be used, LockSupport is the official way we can get access to the parking utilities.

3.1. How to Use LockSupport

Using LockSupport is straightforward. If we want to stop a thread’s execution, we call the park() method. We don’t have to provide a reference to the thread object itself — the code stops the thread that calls it.

Let’s look at a simple parking example:

public class Application {
    public static void main(String[] args) {
        Thread t = new Thread(() -> {
            int acc = 0;
            for (int i = 1; i <= 100; i++) {
                acc += i;
            }
            System.out.println("Work finished");
            LockSupport.park();
            System.out.println(acc);
        });
        t.setName("PARK-THREAD");
        t.start();
    }
}

We created a minimal console application that accumulates the numbers from 1 to 100 and prints them out. If we run it, we’ll see that it prints Work finished but not the result. This is, of course, because we call park() right before.

To let the PARK-THREAD finish, we must unpark it. To do this, we have to use a different thread. We can use the main thread (the thread running the main() method) or create a new one.

For simplicity, let’s use the main thread:

t.setName("PARK-THREAD");
t.start();

Thread.sleep(1000);
LockSupport.unpark(t);

We add a one-second sleep in the main thread to let the PARK-THREAD finish the accumulation and park itself. After that, we unpark it by calling unpark(Thread). As expected, during unparking, we must provide a reference to the thread object that we want to start.

With our changes, the program now properly terminates and prints the result, 5050.

3.2. Unpark Permits

The internals of the parking API work by using a permit. This, in practice, works like a single permit Semaphore. The park permit is used internally to manage the thread’s state with the park() method consuming it, while unpark() makes it available.

Since we can only have one permit available per thread, calling the unpark() method multiple times has no effect. A single park() call will disable the thread.

What is interesting, however, is that the parked thread waits for a permit to become available to enable itself again. If a permit is already available when calling park(), then the thread is never disabled. The permit is consumed, the park() call returns immediately, and the thread continues execution.

We can see this effect by removing the call to sleep() in the previous code snippet:

//Thread.sleep(1000);
LockSupport.unpark(t);

If we run our program again, we’ll see that there’s no delay in the PARK-THREAD execution. This is because we call unpark() immediately, which makes the permit available for park().

3.3. Park Overloads

The LockSupport class contains the park(Object blocker) overload method. The blocker argument is the synchronization object that is responsible for thread parking. The object we provide doesn’t affect that parking process, but it’s reported in the thread dump, which could help us diagnose concurrency issues.

Let’s change our code to contain a synchronizer object:

Object syncObj = new Object();
LockSupport.park(syncObj);

If we remove the call to unpark() and run the application again, it will hang. If we use jstack to see what the PARK-THREAD is doing, we’ll get:

"PARK-THREAD" #11 prio=5 os_prio=0 tid=0x000000001e401000 nid=0xfb0 waiting on condition [0x000000001eb4f000]
   java.lang.Thread.State: WAITING (parking)
        at sun.misc.Unsafe.park(Native Method)
        - parking to wait for  <0x000000076b4a8690> (a java.lang.Object)

As we can see, the last line contains which object the PARK-THREAD is waiting for. This is helpful for debugging purposes, which is why we should prefer the park(Object) overload.

4. Parking vs. Waiting

Since both of these APIs give us similar functionality, which should we prefer? In general, the LockSupport class and its facilities are considered low-level API. Additionally, the API can be easily misused, leading to obscure deadlocks. For most cases, we should use the Thread class’s wait() and join().

The benefit of using parking is that we don’t need to enter a synchronized block to disable the thread. This is important because synchronized blocks establish a happens-before relationship in the code, which forces a refresh of all the variables and can potentially lower performance if it’s not needed. This optimization, however, should rarely come into play.

5. Conclusion

In this article, we explored the LockSupport class and its parking API. We looked at how we can use it to disable threads and explained how it works, internally. Finally, we compared it to the more common wait()/join() API and showcased their differences.