1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
// Copyright 2014 The Bazel Authors. 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.
*<p>
* The names used here are adapted from those used in Joshua Bloch's book
* "Effective Java", which are also described at
* <http://www.ibm.com/developerworks/java/library/j-jtp09263/>.
*<p>
* 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 :)
*<p>
* 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 {}
}
|
