001package votorola.g.lang; // Copyright 2005, Brian Goetz and Tim Peierls; 2006-2008, 2012, 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.
002
003import java.lang.annotation.*;
004import java.lang.reflect.*;
005
006
007/** Indicates thread safety of fields, constructors and methods.  Access to thread-safe
008  * fields and calls to thread-safe constructors and methods will never put the program
009  * into an invalid state, regardless of how the runtime interleaves those actions, and
010  * without requiring any additional synchronization or coordination on the part of the
011  * caller.
012  *
013  * <p>The indication of thread safety applies to a field, constructor or method.  It
014  * never applies to an object read from the field, or created by the constructor, or
015  * returned by the method.  (Thread-safe fields, constructors and methods are not
016  * constrained to dispense only thread-safe objects.)  Each object's own thread safety is
017  * specified by its own API documentation.</p>
018  *
019  * <p>The opposite of ThreadSafe is {@linkplain ThreadRestricted ThreadRestricted}.</p>
020  *
021  * <h3>Applied to fields</h3>
022  *
023  * <p>An unannotated field is assumed to be thread safe only if it is final.  For
024  * non-final fields, the safety of access (read or write) is specified by the rules of
025  * the language (particularly by the memory model, chapter 17).  Strictly speaking, only
026  * certain types of volatile field (and their equivalents in
027  * java.util.concurrent.{@linkplain java.util.concurrent.atomic atomic}) can be thread
028  * safe.  All others are subject to possibile read/write caching of field values, by
029  * threads (caches being flushed at synchronization points).</p>
030  *
031  * <h3>Applied to constructors</h3>
032  *
033  * <p>An unannotated constructor is assumed to be thread safe.</p>
034  *
035  * <h3 id='method-test'>Applied to methods</h3>
036  *
037  * <p>The thread safety of a call, such as object.method(), depends on the object's type
038  * (T), where T = object.getClass().  To determine the thread safety of the call:</p>
039  *
040  * <ol>
041  *
042  *     <li>Look at the API documentation (javadoc page) of type T.</li>
043  *
044  *     <li>Find the method declaration on that page.  If the method is not found on that
045  *     page (it is inherited, and not overridden), then look at the javadoc page of the
046  *     supertype (or its supertype, and so on, until you find the method).  Refer to the
047  *     thread-safety annotation of the method.  <br/>Or, if the method is
048  *     unannotated:</li>
049  *
050  *     <li>Refer to the annotation of the method's <em>declaring</em> type (top of that
051  *     same page). <br/>Or, if that type is unannotated:</li>
052  *
053  *     <li>Return to the original, javadoc page of type T (if you had left it), and refer
054  *     to the annotation of type T. <br/>Failing that, unless you know otherwise:</li>
055  *
056  *     <li>Assume the method is {@linkplain ThreadRestricted ThreadRestricted}.</li>
057  *
058  *     </ol>
059  *
060  * <p>Or use {@linkplain ThreadSafe.U ThreadSafe.U} to perform these same tests at
061  * runtime.</p>
062  *
063  * <h3>Applied to types</h3>
064  *
065  * <p>Annotation of a class or interface specifies the default thread safety for its
066  * public methods.  Only methods have such defaults, fields, constructors and static
067  * member classes do not.  See the <a href='#method-test'>rules above</a> for determining
068  * the thread safety of a method call.</p>
069  *
070  * <p>An unannotated Throwable is assumed to be thread safe.</p>
071  *
072  *     @see ThreadRestricted
073  */
074  @Documented @Retention(RetentionPolicy.RUNTIME)
075  @Target({ ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })
076public @interface ThreadSafe
077{
078
079
080   // ====================================================================================
081
082
083    /** Thread-safety utilities. Includes utility methods for accessors to test the safety
084      * of code, prior to accessing it.  For tests that code can use, after access, see
085      * {@linkplain ThreadRestricted ThreadRestricted}.
086      */
087    public @ThreadSafe static final class U
088    {
089
090        private U() {}
091
092
093        /** Returns true if thread-safety checks are actually performed (normal
094          * situation); false if they were disabled in this classloader's runtime.  This
095          * flag affects the various thread-safety tests; if checking is disabled, they
096          * will always test positive (thread safe).
097          *
098          * <p>Checking may be disabled by code that lacks permission to read
099          * annotations. For instance, an unsigned applet may disable checking to avoid
100          * having AccessControlExceptions thrown by underlying library code that makes
101          * use of these tests.</p>
102          *
103          *     @see #disableChecking()
104          */
105        public static boolean isCheckingEnabled() { return isCheckingEnabled; }
106
107
108            private static volatile boolean isCheckingEnabled = true;
109
110
111            public static void disableChecking() { isCheckingEnabled = false; }
112
113
114
115        /** Tests whether the object is annotated as beign thread safe.  Checks both
116          * {@linkplain ThreadSafe ThreadSafe} and {@linkplain ThreadRestricted
117          * ThreadRestricted}.
118          *
119          *     @return true if {@linkplain #isCheckingEnabled() checking is disabled}, or
120          *       annotated thread safe; false if annotated thread restricted; or null if
121          *       none of the above.
122          *
123          *     @throws AssertionError if assertions enabled, and two annotations
124          *       contradict.
125          */
126        private static Boolean isThreadSafe( final AnnotatedElement o )
127        {
128            if( !isCheckingEnabled ) return true;
129
130            final ThreadSafe safe = o.getAnnotation( ThreadSafe.class );
131            final ThreadRestricted restricted = o.getAnnotation( ThreadRestricted.class );
132            if( safe != null )
133            {
134                assert restricted == null : "either thread safe or restricted, not both";
135                return true;
136            }
137            else if( restricted != null ) return false;
138
139            return null;
140        }
141
142
143        /** Tests whether a method is <a href='ThreadSafe.html#method-test'>effectively
144          * annotated thread safe</a>.
145          *
146          *     @param objectType type of the object on which the method is called, per
147          *       object.getClass().
148          *     @param method of the object (declared or inherited).
149          *
150          *     @return true iff the method is effectively annotated thread safe; or if
151          *       {@linkplain #isCheckingEnabled() checking is disabled}.
152          */
153        public static boolean isThreadSafe( final Class<?> objectType, final Method method )
154        {
155         // if( !isCheckingEnabled ) return true;
156         //// redundant, per first call to isThreadSafe()
157
158            Boolean safe = isThreadSafe( method );
159            if( safe != null ) return safe;
160
161            if( !Modifier.isPublic( method.getModifiers() )) return false;
162
163            safe = isThreadSafe( method.getDeclaringClass() );
164            if( safe != null ) return safe;
165
166            safe = isThreadSafe( objectType );
167            if( safe != null ) return safe;
168
169            return false;
170
171        }
172
173
174
175        /** Tests whether a public method is <a
176          * href='ThreadSafe.html#method-test'>effectively annotated thread safe</a>.
177          *
178          *     @return true iff the method is effectively annotated thread safe; or if
179          *       {@linkplain #isCheckingEnabled() checking is disabled}.
180          *
181          *     @throws IllegalArgumentException if there is no such public method, per
182          *       Class.{@linkplain Class#getMethod getMethod}().
183          */
184        public static boolean isThreadSafe( final Object o, final String publicMethodName,
185          final Class<?>... methodParameterTypes )
186        {
187            try
188            {
189                return isThreadSafe( o.getClass(),
190                  o.getClass().getMethod( publicMethodName, methodParameterTypes ));
191            }
192            catch( NoSuchMethodException x ) { throw new IllegalArgumentException( x ); }
193        }
194
195
196    }
197
198
199
200}