Thread Safety Levels Explained

Many classes in the TFS SDK for Java document their thread-safey level. This document describes the different degrees of thread-safety. Consider classes which do not document thread-safety to be thread-compatible.

Class Thread-Safety

The thread-safety level advertised for a non-abstract class is the degree of safety users can expect from that class. Abstract classes may document the safety of their implementation, but subclasses may declare a safer or less safe level of safety.

If a class does not specify a required level of thread-safety, assume thread-compatible.

Interface Thread-Safety

A thread-safety requirement for an interface is different than for a class. The level specified for an interface is the minimum level of thread-safety required for all implementations of that interface. Interfaces will rarely require immutable, conditionally thread-safe, or thread-hostile implementations because of the design constraints they would impose. Interfaces will occasionally require thread-safe or thread-compatible implementations.

If an interface does not specify a required level of thread-safety, assume thread-compatible.

Levels Defined

Below are the levels of thread-safety the TFS SDK for Java documentation declares. The safest levels (most concurrency-friendly) are described first, and the least safe (least concurrency-friendly) are last. Find more detailed information about these degrees of safety in the article Java theory and practice: Characterizing thread safety by Brian Goetz.

Immutable
Immutable objects are always thread-safe and require no external synchronization.
Thread-safe
Thread-safe objects operate according to their specifications when accessed by multiple threads without requiring external synchronization
Conditionally thread-safe
Conditionally thread-safe objects have operations which are individually thread-safe, but may require external synchronization if they are used together in certain sequences. An example is the iterator object returned by some Java collections: if the collection is modified during iteration, the iterator may throw an exception. The caller is required to prevent modification to the object (external synchronization) while the iterator is in use.
Thread-compatible
Thread-compatible objects are not thread-safe but can be made safe for use by multiple threads if external synchronization is used. Most classes are at least this thread-safe, even if they perform no internal synchronization.
Thread-hostile
Thread-hostile objects can't be made safe for concurrent use, even if external synchronization is used. These kinds of objects are rare, and include classes that modify static data in a way that affects other threads. An example is a class that calls System.setOut(), which uses native code to reassign a static final field, System.out.