RFR (S): JEP-142: Reduce Cache Contention on Specified Fields

[Doug Lea]

On 11/26/12 14:08, Doug Lea wrote:

>>
>>> I think you should re-write the javadoc ...
>
> The Contended.java file and its javadoc in Aleksey's webrev is just a
> placeholder to get things moving. We expect to solicit
> reviews in the usual way (mainly on concurrency-interest list)
> for a version that will make it into JDK8.

The initial javadoc is pasted below;
updates will appear in jsr166 CVS viewable at:
http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/main/java/util/concurrent/Contended.java?view=log

/**
  * 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. The effects of this annotation will nearly
  * always add space overhead to programs.  Its use 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 object is often accessed by a
  * different thread.
  *
  * <p>A {@code @Contended} field annotation may optionally include a
  * contention group tag. All fields with the same tag are considered
  * as a group with respect to isolation from other groups. A default
  * annotation without a tag indicates contention with all other
  * fields, including other {@code @Contended} ones.

  * <p>When the annotation is used at the class level, all unannotated
  * fields of the object are considered to be in the same default
  * group, separate from any fields that carry their own (possibly
  * tagged) {@code @Contended} annotations.
  *
  * <p><b>Sample Usages</b>. (Forthcoming.)
  *
  * @since 1.8
  */