textbender.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. That object's own thread safety is formally indicated by its own API. However, if the object is not thread safe, and its API does not specify the particular restriction, then the field, constructor or method from which it came either confers its own restriction; or documents something else.

The opposite of ThreadRestricted is ThreadSafe. See its rules for type-level annotation, which also apply here.

A Particular Thread

The restriction may be 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();

Threads Holding a Particular Lock

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

     @ThreadRestricted( "holds this" ) // or class-name.this
     @ThreadRestricted( "holds obj" )
     @ThreadRestricted( "holds lock" )

These specify that threads must hold the object's general-purpose monitor (this); some other object's monitor (obj); or a special-purpose concurrent Lock:

As well, a test of compliance may be implemented. For an Object monitor, the test might be:

     assert Thread.holdsLock( this ); // or class-name.this
     assert Thread.holdsLock( obj );

Or, for a Lock:

     assert lock.isHeldByCurrentThread();

Unspecified

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

     @ThreadRestricted
     @ThreadRestricted("unspecified")

Generally it appears 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 in the usual way.

Optional Element Summary

String

value Details of the thread restriction.

value

public abstract String value

Details of the thread restriction.

Default:

"unspecified"