Simple Thread Control With Java's CountDownLatch

November 27, 2007

The CountDownLatch is a simplified mechanism that allows waiting on a fixed number of threads to complete. It was introduced as part of the Java 5 concurrency API as one of a number of constructs designed to make multithreading code simpler and safer.

I test drove the development of a LineCounter class, as an example class to be used in the context of a multithreaded server. The purpose of this class is to calculate the number of source lines within a file. It's reasonably trivial code. The tests are shown in Listing 1; the source for LineCounter is in Listing 2. LineCounter supports threading via implementing the Runnable interface, but most of the tests have nothing to do with threading. They instead directly interact with the run method.

To demonstrate the CountDownLatch class, I implemented a simple server that processes a number of LineCounter requests in a threaded manner. The definition I chose for the server's interface is simple: It accepts a queue of requests, after which the server can be started.

The CountDownLatch is initialized with a number that represents how many times the latch can be counted down. In a typical use, an application creates a CountDownLatch initialized to a number x, and then creates x threads. The application immediately blocks by calling the await method on the CountDownLatch. When each of the spawned threads completes, it tells the latch to count down. When the latch count reaches zero, any code blocking on await now restarts.

The CountDownLatch can only count down, not up. As such, it's most applicable when the number of threads to create is known beforehand. A different design of the LineCountServer would process individual incoming requests as they were received; this would no longer represent a design for which CountDownLatch was applicable.

The test, shown in Listing 3, demonstrates the protocol for client applications interacting with a LineCountServer.

The LineCountServer code is shown in Listing 4. The waitOnLatch method encapsulates a loop that handles any spurious wakeups from the await function.

The run method in the server controls processing of the counting thread. First, the latch field is initialized to a CountDownLatch with a count that matches the queue size. The while loop iterates until the queue is empty; an element is removed and processed with each iteration of the loop. For each LineCounter object removed from the queue, a new processing thread is created and started. This allows the loop to quickly iterate through the queue and initiate threads for each LineCounter.

Once the queue is emptied and all LineCounter execution threads have been spawned, the run method blocks by calling a method whose job is to wait on the CountDownLatch. As each spawned LineCounter thread completes, it triggers a countdown on the latch. Once the countdown reaches zero, the call to await unblocks.

The CountDownLatch is a simple class to understand and use, one that you should take advantage of in your multithreaded applications!

About the Author

Jeff Langr is a veteran software developer with over a quarter century of professional software development experience. He's authored two books and over 50 published articles on software development, including Agile Java: Crafting Code With Test-Driven Development (Prentice Hall) in 2005. You can find out more about Jeff at his site, http://langrsoft.com, or you can contact him via email at jeff at langrsoft dot com.