public @Interface Contended

An annotation expressing that objects and/or their fields are expected to encounter memory contention, generally in the form of "false sharing". This annotation serves as a hint that such objects and fields should reside in locations isolated from those of other objects or fields. Susceptibility to memory contention is a property of the intended usages of objects and fields, not their types or qualifiers. The effects of this annotation will nearly always add significant space overhead to objects. The use of @Contended is warranted only when the performance impact of this time/space tradeoff is intrinsically worthwhile; for example, in concurrent contexts in which each instance of the annotated class is often accessed by a different thread.

A @Contended field annotation may optionally include a contention group tag. A contention group defines a set of one or more fields that collectively must be isolated from all other contention groups. The fields in the same contention group may not be pairwise isolated. With no contention group tag (or with the default empty tag: "") each @Contended field resides in its own distinct and anonymous contention group.

When the annotation is used at the class level, the effect is equivalent to grouping all the declared fields not already having the @Contended annotation into the same anonymous group. With the class level annotation, implementations may choose different isolation techniques, such as isolating the entire object, rather than isolating distinct fields. A contention group tag has no meaning in a class level @Contended annotation, and is ignored.

The class level @Contended annotation is not inherited and has no effect on the fields declared in any sub-classes. The effects of all @Contended annotations, however, remain in force for all subclass instances, providing isolation of all the defined contention groups. Contention group tags are not inherited, and the same tag used in a superclass and subclass, represent distinct contention groups.