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