Thanks Mike!
The updated webrev is here:
http://cr.openjdk.java.net/~shade/8014966/webrev.04/
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!
-Aleksey.
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."
Moved.
> 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!
