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}