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

[David Holmes]

Roger,

I think you may be misunderstanding the purpose of the contention 
groups. They are, as the docs state, for defining a set of fields that 
need isolation from other sets of fields. They are not for defining set 
of fields which would benefit from co-location.

David

On 30/05/2013 4:48 AM, roger riggs wrote:
> 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.
>