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

[Aleksey Shipilev]

Hi Roger,

On 05/29/2013 09:12 PM, roger riggs wrote:
> I'm not sure I quite understand the purpose or semantics of this 
> annotation.

That's the early sign you don't need it! :) I'm actually envious.

> 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.

See:
  http://openjdk.java.net/jeps/142
  https://blogs.oracle.com/dave/entry/java_contented_annotation_to_help

http://mail.openjdk.java.net/pipermail/hotspot-dev/2012-November/007309.html

...for more rationale.

> The description of the annotation is an odd mix of hints about the 
> usage of fields and specification of required behavior of an 
> implementation.

Hm. If there is the issue with the javadoc, I'm failing to see it; maybe
because I am exposed to false sharing enough to immediately understand
what @C is about.

Even though this is an internal API, and we just want to specify @C
barely enough to be useful for those who need it, specific examples what
is broken with the docs are welcome.

> 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.

Yes, hints are by definition ignorable. Should the runtime be able to
figure out the memory contention issues on its own, we will just "noop"
@C, and be done. But, that Holy Grail is not here.

> 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.

I guess the valid concern is the use of "must"? Implementations may
choose to protect the grouped fields on their own if it chooses to do so.

-Aleksey.