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

[roger riggs]

Hi Aleksey,

Thanks for the references.  Currently, you are correct, I don't need it.

Has it been considered that highly contended field should not be allocated
in the object itself anyway but in some pool or structure better suited
to its access characteristics?  A read-only indirection could provide
some ability to allocate contended locks elsewhere where they would
not disrupt the allocation mechanism.  For example, in a pool
of write-only or write-mostly values for the processor/core/thread.
Of course, that has an access cost too.

But given the credentials of the discussion authors I expect this has been
well vetted and I have not much to offer.
Limiting the scope of @contended groups prevents being able to
groups fields from different classes/subclasses together that might
reasonably share access patterns.

The language related to 'intrinsically worthwhile' deserves a caution label.
History is full of premature optimizations.  Since it is mentioned that
instrumentation is not available to compute the costs of contention
in a particular use case, then only macro level performance of the 
application
would be available to judge the effectiveness of a particular @Contended
usage.  But the cost in memory is immediate and measurable.

Thanks, Roger



On 5/29/2013 2:02 PM, Aleksey Shipilev wrote:
> 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.
Yep.
>
> -Aleksey.