001package votorola.g.lang; // Copyright 2006-2009, 2013, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE. 002 003import java.lang.annotation.*; 004 005 006/** Warns that access to a field, constructor or method is restricted to a particular 007 * thread, or to a thread that holds a particular lock. The opposite of ThreadRestricted 008 * is {@linkplain ThreadSafe ThreadSafe}. 009 * 010 * <p>The restriction applies to a field, constructor or method. It does not necessarily 011 * apply to any associated object that is read from the field, or created by the 012 * constructor, or returned by the method. The associated object's thread safety is 013 * normally documented by its own type API. However, if the type API documents no 014 * specific restriction, then the object assumes the restriction of the field, 015 * constructor or method whence it came. [See also @{@linkplain Warning 016 * Warning}("thread restricted object") and @{@linkplain Warning Warning}( "thread 017 * restricted elements")].</p> 018 * 019 * <h3>Default restriction for methods</h3> 020 * 021 * <p>When applied to a type (class or interface), the ThreadRestricted annotation 022 * specifies the default restriction for all public methods. Any public method that 023 * lacks its own restriction is bound by the default. See the <a 024 * href='ThreadSafe.html#method-test'>step-by-step rules</a> for resolving the thread 025 * safety of public methods. Methods alone have such defaults, not fields or 026 * constructors.</p> 027 * 028 * <h3>Restriction to a particular thread</h3> 029 * 030 * <p>The restriction may be to a particular thread. For instance, most Swing code is 031 * restricted to the AWT event dispatch thread. An appropriate annotation would be:</p> 032 * 033 * <pre> 034 * @ThreadRestricted("AWT event dispatch")</pre> 035 * 036 * <p>As well, a constructor or method might implement an internal, runtime test of 037 * compliance:</p> 038 * 039 * <pre> 040 * assert java.awt.EventQueue.isDispatchThread();</pre> 041 * 042 * <p>The thread may be specified as the constructor. In this case, access is restricted 043 * to the construction thread <em>as though for purposes of construction</em>. This 044 * means that access is forbidden even to the construction thread if another thread has 045 * already accessed an instance member.</p> 046 * 047 * <pre> 048 * @ThreadRestricted("constructor")</pre> 049 * 050 * <h3>Restriction to threads holding a particular lock</h3> 051 * 052 * <p>The restriction may specify a particular synchronization lock. For example:</p> 053 * 054 * <pre> 055 * @ThreadRestricted("holds <em>Class</em>.this") 056 * @ThreadRestricted("holds <em>object</em>") 057 * @ThreadRestricted("holds <em>lock</em>")</pre> 058 * 059 * <p>These specify that the thread must hold the monitor lock of the containing instance 060 * (this), or of some other object; or that it must hold a particular {@linkplain 061 * java.util.concurrent.locks.ReentrantLock ReentrantLock}. As well, a runtime test of 062 * compliance may be implemented within the restricted code:</p> 063 * 064 * <pre> 065 * assert Thread.holdsLock( <em>Class</em>.this ); 066 * assert Thread.holdsLock( <em>object</em> ); 067 * assert <em>lock</em>.isHeldByCurrentThread();</pre> 068 * 069 * <h3>Restriction to touch-synchronizing threads</h3> 070 * 071 * <p>The restriction may specify that threads must touch-synchronize. For example:</p> 072 * 073 * <pre> 074 * @ThreadRestricted("touch") 075 * @ThreadRestricted("touch <em>Class</em>.this") 076 * @ThreadRestricted("touch <em>object</em>") 077 * @ThreadRestricted("touch <em>lock</em>")</pre> 078 * 079 * <p>These mean that access is thread-safe, but modifications to state variables are not 080 * guaranteed to be visible to other threads unless they touch-synchronize on a common 081 * lock. The method of touch-synchronizing depends on whether the thread is reading from 082 * state, or writing to it. If reading, the thread must grab the lock at some point 083 * <em>before</em> reading (thus ensuring that its local memory cache is invalidated). 084 * The thread need not continue to hold the lock while reading, but may release it 085 * beforehand.</p> 086 * 087 * <p>If writing to state, the thread must release the lock at some point <em>after</em> 088 * writing (thus ensuring that its local memory cache is flushed). The thread need not 089 * actually hold the lock at time of writing, but may grab it and subsequently release 090 * it. Only after the lock is released are the state changes guaranteed to reach main 091 * memory, and become readable by other threads that touch-synchronize.</p> 092 * 093 * <p>If the thread is both reading and writing, then it must do both: grab the lock 094 * before reading; and release it after writing. It need not hold onto the lock in the 095 * meantime, but may grab it and release it, once beforehand, and once afterwards.</p> 096 * 097 * <p>If no particular lock is specified, then any lock (or locks) will suffice. 098 * Visibility is guaranteed only among those threads that touch-synchronize on the same 099 * lock.</p> 100 * 101 * <h3>Restriction unspecified</h3> 102 * 103 * <p>The restriction may be left unspecified. This is the default value, so these are 104 * equivalent:</p> 105 * 106 * <pre> 107 * @ThreadRestricted 108 * @ThreadRestricted("unspecified")</pre> 109 * 110 * <p>This form of the annotation is generally applied at the type level. It defers the 111 * choice of restriction to the runtime code that constructs instances of the type. The 112 * code may choose either a single threaded or a locking restriction, and its choices may 113 * vary from instance to instance. In other words, the unpecified thread restriction 114 * simply means "not thread safe" and is handled accordingly.</p> 115 * 116 * @see ThreadSafe 117 */ 118 @Documented @Retention(RetentionPolicy.SOURCE) // till further retention needed 119 @Target({ ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE }) 120public @interface ThreadRestricted 121{ 122 123 124 /** Details of the thread restriction. 125 */ 126 public String value() default "unspecified"; 127 128 129 130}