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

[roger riggs]

Hi Alexey,

I'm not sure I quite understand the purpose or semantics of this annotation.
Since it is in sun.misc, it may not be so important and is just an 
implementation
artifact but does not have enough of a standalone description nor connection
to the other elements.

The description of the annotation is an odd mix of hints about the
usage of fields and specification of required behavior of an implementation.
I would expect an implementation to be able to ignore the annotation
or perhaps to improve on the performance by utilizing runtime available
information.  It is more useful to say what the annotation does mean
than to say what it does not mean.

Contention groups are a useful semantic but to say that a contention
group " must be isolated from all other contention groups." is something
for the implementation to determine.  It would be more productive to say 
that
fields in the contention group benefit from being grouped together and
have similar access patterns.

Thanks for any clarifications or connections to the rest of the 
functionality,

Roger


On 5/29/2013 7:20 AM, Aleksey Shipilev wrote:
>
> The new webrev is here:
>    http://cr.openjdk.java.net/~shade/8014966/webrev.03/
>
> Thanks everyone, writing specs is fun!
>
> -Aleksey.