RFR (S) CR 8014966: Add the proper Javadoc to @Contended

Aleksey Shipilev aleksey.shipilev at oracle.com
Fri May 31 15:06:43 UTC 2013

Thanks Mike!

The updated webrev is here:

I think the changes we are doing now are converging. I would like to
hear formal OKs from Martin B, Mike D, David H, so we can proceed with
pushing this. Last-minute grammar corrections welcome!


Summary of changes below:

On 05/31/2013 03:04 AM, Mike Duigou wrote:
> Since the statements are grouped by fields and classes, move this to
> the classes paragraph:
> "A contention + * group tag has no meaning in a class level {@code
> @Contended} annotation, + * and is ignored."


> Describing the behaviour of the class annotation by referencing
> unavailable functionality seems strange:
> "the effect is + * roughly equivalent to placing the {@code
> @Contended} annotation + * with the <i>same</i> anonymous tag over
> all the unannotated fields of + * the object."
> The reader is left wondering "how would I annotate multiple fields
> with the same anonymous tag?" Perhaps a statement in the fields
> paragraph that "To put multiple fields into the same anonymous group
> use the class level @C annotation".

Good point, rephrased to:
 * When the annotation is used at the class level, the effect is
 * equivalent to grouping all the fields not already having the
 * {@code @Contended} annotation into the same anonymous group.

> "over all the unannotated fields of + * the object."
> This refers, of course, to fields without their own @C annotation not
> fields without annotations.

Yes, that is fixed as the side-effect of the change above.

> Addition:
> <p>The class level {@code @Contended} annotation is not inherited and
> has + * no effect on the fields [defined] in any sub-classes.

Done. I think "declared" is the more applicable in Java world.

> Addition:
> "The effects of all + * {@code @Contended} annotations [upon layout
> of object fields] remain in force for all"

I am reluctant to add this, because mentioning field layout seems to
mean the particular implementation choice (which limits us from, say,
aligning the objects for the cache line).

> As I told Brian during the lambda javadoc efforts, writing 
> specification is the best kind of task--demanding, exacting and 
> tedious! :-)

Yeah. There is still some time before release, and lots of space on
cr.openjdk.java.net for the webrevs!

More information about the core-libs-dev mailing list