package votorola.g.lang; // Copyright 2006-2008, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Textbender Software"), to deal in the Textbender Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Textbender Software, and to permit persons to whom the Textbender 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 Textbender Software. THE TEXTBENDER 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 TEXTBENDER SOFTWARE OR THE USE OR OTHER DEALINGS IN THE TEXTBENDER SOFTWARE. import java.lang.annotation.*; /** Warns that access to a field, constructor or method is restricted * to a particular thread, or to a thread that holds a particular lock. * The restriction applies to a field, constructor or method. * It does not necessarily apply to any object read from the field, * or created by the constructor, or returned by the method. * The thread safety of the object's own fields, contructors and methods is specified * by its own API documentation. (However, by convention, * if the object is not thread safe, and no specific * restriction is documented for it, then it assumes the specific restriction * of the field, constructor or method from which it came.) *

* The opposite of ThreadRestricted is {@linkplain ThreadSafe ThreadSafe}. *

* *

Applied to Types

*

* Annotation of a type (class or interface) specifies the default * thread safety of its public methods. See the * step-by-step rules * for resolving the thread safety of public methods. Only methods * have type-specific defaults; not fields or contructors. *

* *

Restriction to a Particular Thread

*

* The restriction may be to a particular thread. * For instance, most Swing code is restricted * to the AWT event dispatch thread. An appropriate annotation would be: *

* 
  *     @ThreadRestricted( "AWT event dispatch" )
*

* As well, in the case of a constructor or method, * it might implement an internal, runtime test of compliance: *

* 
  *     assert java.awt.EventQueue.isDispatchThread();
* *

Restriction to Threads Holding a Particular Lock

*

* The restriction may specify a particular synchronization lock. * For example: *

* 
  *     @ThreadRestricted( "holds this" ) // better yet, Classname.this
  *     @ThreadRestricted( "holds obj" )
  *     @ThreadRestricted( "holds lock" )
*

* These specify that the thread must hold the monitor lock * of the containing instance (this), or of some other object (obj); * or that it must hold a particular * {@linkplain java.util.concurrent.locks.Lock concurrent Lock}: *

*

* As well, a test of compliance may be implemented within the restricted code. * For a monitor lock, the test might be: *

* 
  *     assert Thread.holdsLock( this ); // better yet, Classname.this
  *     assert Thread.holdsLock( obj );
*

* Or, for a {@linkplain java.util.concurrent.locks.ReentrantLock concurrent ReentrantLock}: *

* 
  *     assert lock.isHeldByCurrentThread();
* *

Restriction to Touch-Synchronizing Threads

*

* The restriction may specify that threads must touch-synchronize. For example: *

* 
  *     @ThreadRestricted( "touch" )
  *     @ThreadRestricted( "touch this" ) // better yet, Classname.this
  *     @ThreadRestricted( "touch obj" )
  *     @ThreadRestricted( "touch lock" )
*

* This means that access is thread-safe, but modifications to state variables are * guaranteed to be visible only among threads that touch-synchronize on a common * lock. The method of touch-synchronizing depends on whether the thread is reading * from state, or writing to it. If reading, the thread must grab the lock at some * point before reading (thus ensuring that its local memory cache is * invalidated). The thread need not continue to hold the lock while reading, but * may release it beforehand. *

*

* If writing to state, the thread must release the lock at some point after * writing (thus ensuring that its local memory cache is flushed). The thread need * not actually hold the lock at time of writing, but may grab and release it * subsequently. Only after the lock is released are the state changes guaranteed to * reach main memory, and the sight of other touch-synchronizing threads. *

*

* If the thread is both reading and writing, then it must do both: grab the lock * before reading; and release it after writing. It need not hold onto the lock in * the meantime, but may grab and release it once beforehand, and once afterwards. *

*

* If no particular lock is specified, then any lock (or locks) will suffice. * Visibility is guaranteed only among threads that touch-synchronize on the same * lock. *

* *

Restriction Unspecified

*

* The restriction may be left unspecified. * This is the default value, so these are equivalent: *

* 
  *     @ThreadRestricted
  *     @ThreadRestricted("unspecified")
*

* Generally, an unspecified restriction is annotated at the type level. * It defers the choice of restriction to the runtime code * that constructs instances of that type. * Runtime code will choose either a single threaded or locking restriction, * and its choices may vary from instance to instance. * In other words, an unpecified thread restriction * simply means "not thread safe", and is handled accordingly. *

* * @see ThreadSafe */ @Documented @Retention( RetentionPolicy.SOURCE ) // till further retention needed @Target({ ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.METHOD, ElementType.TYPE }) public @interface ThreadRestricted { /** Details of the thread restriction. */ public String value() default "unspecified"; }