package waymaker.gen; // Copyright © 2005 Brian Goetz and Tim Peierls. Copyright © 2006 Michael Allan. Released under the Creative Commons Attribution License (http://creativecommons.org/licenses/by/2.5). Official home: http://www.jcip.net. Any republication or derived work distributed in source code form must include this copyright and license notice.
import java.lang.annotation.*;
/** 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 member only, such as a field, constructor or method.
* It never applies to any actual object read from the field, or created by the constructor, or
* returned by the method. (Thread-safe members are not constrained to dispense only thread-safe
* objects.) Each object’s own thread safety is specified by the API documentation of its type.
*
* Nor does it guarantee the integrity of the parameters passed into the constructor or method.
* Unless the API states otherwise, each actual parameter is expected to be ready for normal access
* within the constructor or method body. Any preliminary locking or thread restriction is the
* responsibility of the caller.
*
* The opposite of ThreadSafe is {@linkplain ThreadRestricted ThreadRestricted}.
*
* Applied to a field
*
* A final field must be thread safe. A volatile or {@linkplain
* java.util.concurrent.atomic atomic} field might be. Any other field cannot be.
* Use annotation to clarify any particular field whose thread safety is not obvious.
*
* Applied to a constructor or method
*
* The thread safety of a call to a non-private constructor or method of an object o depends on type
* T = o.getClass(). To determine the thread safety of the call:
*
*
*
* - Look at the API documentation (javadoc) page for type T.
*
* - Find the declaration of the constructor or method on that page. If it is not
* declared on that page (in other words it is inherited and not overridden), then
* look at the javadoc page of the supertype, thence through all ancestor types
* till you find the declaration. Refer to the annotation of thread safety in that
* declaration.
Or, if the declaration is unannotated:
*
* - Using the link at the top of that page, refer to the declaration of the same
* constructor or method in the declaring type.
Or, if that declaration
* too is unannotated:
*
* - On the original javadoc page of type T, refer to the annotation of T itself.
*
Failing that, unless you know otherwise:
*
* - Assume the call is {@linkplain ThreadRestricted ThreadRestricted}.
*
*
*
* Applied to a type
*
* Annotation of a class, interface or other type specifies the default thread safety
* of all non-private constructors and methods of that type. This default specification
* applies only to constructors and methods, not to fields or static member classes.
*
*
Some types are assumed to be thread safe. These include:
*
* - Basic immutable types in the Java library, such as java.lang.String
* - Class java.lang.Throwable and its subclasses
*
*
*
* @see ThreadRestricted
*/
@Documented @Retention(RetentionPolicy.SOURCE)
@Target({ ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })
public @interface ThreadSafe {}