votorola.g.lang
Annotation Type ThreadSafe

@Documented
@Retention(value=RUNTIME)
@Target(value={CONSTRUCTOR,FIELD,METHOD,TYPE})
public @interface ThreadSafe

Indicates thread safety of fields, constructors and methods. Access to thread-safe fields, and calls to thread-safe constructors and methods, will never put the program into an invalid state, regardless of how the runtime interleaves those actions, and without requiring any additional synchronization or coordination on the part of the caller.

The indication of thread safety applies to a field, constructor or method. It never applies to an object read from the field, or created by the constructor, or returned by the method. (Thread-safe fields, constructors and methods are not constrained to dispense only thread-safe objects.) Each object's own thread safety is specified by its own API documentation.

The opposite of ThreadSafe is ThreadRestricted.

Applied to Fields

An unannotated field is assumed to be thread safe only if it is final. For non-final fields, the safety of access (read or write) is specified by the rules of the language (particularly by the memory model, chapter 17). Strictly speaking, only certain types of volatile field (and their equivalents in java.util.concurrent.atomic) can be thread safe. All others are subject to possibile read/write caching of field values, by threads (caches being flushed at synchronization points).

Applied to Constructors

An unannotated constructor is assumed to be thread safe.

Applied to Methods

The thread safety of a call, such as object.method(), depends on the object's type (T), where T = object.getClass(). To determine the thread safety of the call:

1. Look at the API documentation (javadoc page) of type T.
2. Find the method declaration on that page. If the method is not found on that page (it is inherited, and not overridden), then look at the javadoc page of the supertype (or its supertype, and so on, until you find the method). Refer to the thread-safety annotation of the method.
   Or, if the method is unannotated:
3. Refer to the annotation of the method's declaring type (top of that same page).
   Or, if that type is unannotated:
4. Return to the original, javadoc page of type T (if you had left it), and refer to the annotation of type T.
   Failing that, unless you know otherwise:
5. Assume the method is not thread safe.

Or use ThreadSafe.U to perform these same tests at runtime.

Applied to Types

Annotation of a type (class or interface) specifies the default thread safety of its public methods. Only methods have such defaults; not fields or contructors. See the step-by-step rules for methods, above.

An unannotated Throwable is assumed to be thread safe.

See Also:

ThreadRestricted