votorola.g.lang
Annotation Type ThreadRestricted

@Documented
@Retention(value=SOURCE)
@Target(value={CONSTRUCTOR,FIELD,METHOD,TYPE})
public @interface ThreadRestricted

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 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 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 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 Also:

ThreadSafe

Optional Element Summary

String

value Details of the thread restriction.

value

public abstract String value

Details of the thread restriction.

Default:

"unspecified"