Documenting thread safety


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 excellent FindBugs 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?


5 Responses to “Documenting thread safety”
  1. The 2nd edition of Effective Java contains some really nice advice on how to document thread safety, which lines up nicely with your 4 categories here. Bloch names the categories above as: 1) Immutable, 2) Not thread-safe, 3) unconditionally thread-safe, and 4) conditionally thread-safe. It’s nice to have a common set of names for these things.

  2. Randall says:

    I agree wholeheartedly. For me, putting in those JCIP annotations while I code also helps drive home the intended behavior and keeps me thinking (and rethinking) about how to code correctly so that it’s thread-safe.

  3. Alex says:

    Many thanks for the reference, Hamlet. I did this off the top of my head, so I’m glad to be in the ballpark of someone far smarter than me. :) I see that in Item 70. Actually, there is a 5th class “Thread-hostile” mentioned on the next page that I didn’t consider. Probably good to document that too.

    Miller’s Hypothesis: “Any interesting Java question has already been thoroughly discussed and decided in either Java Concurrency in Practice or Effective Java.” Discuss.

  4. Ha, yes that might be true. This is why we (Pearson) have had several book clubs focused on Effective Java over the years. The club should just rotate between JCIP and Effective Java every year :)


Check out what others are saying about this post...
  1. […] 11, 2008 10:25 am Alex points out the difficulties of knowing whether a class can be used within a concurrent manner, and […]