// Copyright 2014 Google Inc. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. package com.google.devtools.build.lib.concurrent; import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Define some standard attributes for documenting thread safety properties. *
* The names used here are adapted from those used in Joshua Bloch's book
* "Effective Java", which are also described at
*
* These attributes are just documentation. They don't have any run-time
* effect. The main aim is mainly just to standardize the terminology.
* (However, if this catches on, I can also imagine in the future having
* a presubmit check that checks that all new classes have thread safety
* annotations :)
*
* See ThreadSafetyTest for examples of how these attributes should be used.
*/
public class ThreadSafety {
/**
* The Immutable attribute indicates that instances of the class are
* immutable, or at least appear that way are far as their external API
* is concerned. Immutable classes are usually also ThreadSafe,
* but can be ThreadHostile if they perform unsynchronized access to
* mutable static data. (We deviate from Bloch's nomenclature by
* not assuming that Immutable implies ThreadSafe; developers should
* explicitly annotate classes as both Immutable and ThreadSafe when
* appropriate.)
*/
@Documented
@Target(value = {ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface Immutable {}
/**
* The ThreadSafe attribute marks a class or method which can safely be used
* from multiple threads without any need for external synchronization.
*
* When applied to a class, this attribute indicates that instances
* of the class can safely be used concurrently from multiple threads
* without any need for external synchronization, i.e. that all non-static methods
* are thread-safe (except any private methods that are explicitly
* annotated with a different thread safety annotation). In addition it
* also indicates that all non-static nested classes are thread-safe (except any private
* nested classes that are explicitly annotated with a different thread
* safety annotation). Note that no guarantees are made about static class methods or static
* nested classes - they should be annotated separately.
*
* When applied to a method, this attribute indicates that the
* method can safely be called concurrently from multiple threads.
* The implementation must synchronize any accesses to mutable data.
*/
@Documented
@Target(value = {ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface ThreadSafe {}
/**
* The ThreadCompatible attribute marks a class or method that
* is thread-safe provided that only one thread attempts to
* access each object at a time.
*
* The implementation of such a class must synchronize accesses
* to mutable static data, but can assume that each instance will
* only be accessed from one thread at a time.
*
* The client must obtain an appropriate lock before calling ThreadCompatible
* methods, or must otherwise ensure that only one thread calls such methods.
* Unless otherwise specified, an appropriate lock means synchronizing on the
* instance.
*
* A ThreadCompatible class may contain private methods or private nested
* classes that are not ThreadCompatible provided that they are explicitly
* annotated with a different thread safety annotation.
*/
@Documented
@Target(value = {ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface ThreadCompatible {}
/**
* The ThreadHostile attribute marks a class or method that
* can't safely be used by multiple threads, for example because
* it performs unsynchronized access to mutable static objects.
*/
@Documented
@Target(value = {ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface ThreadHostile {}
/**
* The ConditionallyThreadSafe attribute marks a class that contains
* some methods (or nested classes) which are ThreadSafe but others which are
* only ThreadCompatible or ThreadHostile.
*
* The methods (and nested classes) of a ConditionallyThreadSafe class should
* each have their thread safety marked.
*/
@Documented
@Target(value = {ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface ConditionallyThreadSafe {}
/**
* The ConditionallyThreadCompatible attribute marks a class that contains
* some methods (or nested classes) which are ThreadCompatible but others
* which are ThreadHostile.
*
* The methods (and nested classes) of a ConditionallyThreadCompatible class
* should each have their thread safety marked.
*/
@Documented
@Target(value = {ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.SOURCE)
public @interface ConditionallyThreadCompatible {}
}