Alex Miller lives in St. Louis. He writes code for a living and currently work for Terracotta Tech on the Terracotta open-source Java clustering product. Prior to Terracotta he worked at BEA Systems and was Chief Architect at MetaMatrix. His main language for the last decade has been Java, although Alex have been paid to program in several languages over the years (C++, Python, Pascal, etc). Alex has posted 43 posts at DZone. You can read more from them at their website. View Full User Profile

Documenting Thread Safety

  • submit to reddit

Along with the problem of actually making code thread-safe, there is also the problem of documenting it so other programmers know how to use your code. In general, it’s wise when designing a class to consider the state in the class and determine if each piece needs to be protected and how.

  1. You might decide to make your class immutable and thus avoid needing synchronization at all. (An excellent choice.)
  2. You may decide that either a class is intended to be used in a single-threaded scenario only or that it’s state will protected by locks completely external to the class. The Java collections classes like ArrayList, HashMap, etc are completely unsynchronized allowing you to use this in a single-threaded scenario without synchronization OR to apply synchronization at a granularity appropriate to your application.
  3. Or you may decide to make your class thread-safe and completely encapsulate the protection of the state with internal locks. Sometimes those locks can be done on the internal state variables themselves (highly recommended to make that state final in that case). For example, you might create your own Rolodex class, store state in local collections, and protect access with a lock on the internal collection(s). Note that if you have multiple pieces of internal state, you also need to decide whether they are protected by a single lock or multiple locks. If some methods on the class touch both, you need to be careful in how those locks combine. [Note: if no methods touch both locks, this is probably a design smell that this class is doing more than one thing.]
  4. Or you may be slightly trickier and protect the internal state, but allow external users to participate in your locks. This is done by locking on the instance (this) itself. Users of your class can then also lock on the instance and participate. You can see this in some of the java.util collections classes.

In any of these cases, it’s fairly crucial to document what safety you are providing both internally (for future maintainers of your code) and externally (for users of your class). Java Concurrency in Practice recommends a set of annotations to indicate the thread-safety of a class and what lock guards an attribute.

The nice thing about annotations is that they can be checked by a tool. In fact, the excellentFindBugs supports the JCIP threading annotations and can check that your code actually follows what you document.

Just recently, I saw a java.util.Random being used in a multi-threaded scenario while reviewing some code. I wondered to myself whether obtaining numbers from Random was actually thread-safe. I checked the javadoc and it doesn’t mention it in any way. Then I checked the source and after some minutes of review concluded that it was indeed thread-safe (in more modern versions, an AtomicLong stores the seed value). But if Random had been annotated @ThreadSafe I wouldn’t have had so much trouble.

Now I wonder where (if anywhere) this sort of concurrency information for the JDK is documented. Javadoc documents it (sometimes as we see). I presume the TCK verifies it (but who knows since that’s not exactly easy to get). And of course the implementation source tells you what it does now but not what it’s guaranteed to do in the future. Am I missing something?

Published at DZone with permission of its author, Alex Miller. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Fabrizio Giudici replied on Tue, 2008/08/12 - 3:54am

Excellent suggestion Alex, I like the idea of annotations to declare concrete properties of classes, and definitely FindBugs is a plus.

I'm just wondering why the granularity of the annotations is at class level. For instance, I could think of a class which is not thread-safe, but some of its methods are (even though I can't remember any part of my code being like this). Would that be considered a bad practice?

Talip Ozturk replied on Tue, 2008/08/12 - 8:12am

How about Factory classes and factoried instances?


Methods of Factory classes, for examples,  are good candidates to be annotated so that we will know if factoried instance, implementation that Factory returns, is thread-safe or not. @ReturnsThreadSafe

Note that in some cases, third-party APIs for example, most of the implementations are hidden, not even javadoc'ed. They are supposed to be hidden anyways so API Javadoc is full of Interfaces and couple of simple classes. It is clear that Thread-safety should be annotated at Interface level.  Then Factory methods can be annotated to tell us thread-safety of the implementation it returns.



Hazelcast-Distributed Data Structures for Java

Doug McCreary replied on Tue, 2008/08/12 - 5:37pm

Unless you have an instance of Random per thread, using Random in a threaded context means irreproducible results.  No, it won't explode in any way, but that's a really dangerous usage pattern.


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.