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

[Aleksey Shipilev]

Hi Peter,

On 05/31/2013 11:33 AM, Peter Levart wrote:
> Implementation issues aside, the name of the tag specified in the 
> @Contended annotation could be evaluated in the context of the fully
>  qualified class name in which the annotation is used. For example:

I thought about implying the fully-qualified names for the tags; but
that only makes sense if we allow tag inheritance, and we don't.

> When the tag contained at least one dot, it would be interpreted as 
> fully qualified, otherwise as a simple name.

Ugh. Messy... :)

> Implementation could allow one of the contention groups to be used
> in a "global" context on the boundary of superclass/subclass, but
> which one is the one, would have to be anticipated and explicitly or 
> implicitly noted on the superclass, so that the layout logic could 
> group those fields at the end of object as soon as the superclass is 
> loaded.

We do something like that for normal oops layout, so that we have the
contiguous oops region on the superclass/subclass boundary. This is the
corner case though, which does not scale beyond just two classes. I
think this case is superficial corner case, and does not deserve the
treatment.

Anyhow, the contended tags are just the hints within the hint: we
communicate that particular fields *can* be grouped together if
implementation thinks that is a good idea. The way @C is spec'ed now, we
might even ignore the tags at all and pad the fields distinctively, i.e.
we say those fields are not required to be isolated pair-wise with any
field in the group, but only with all other contended groups and fields.

Having said that, I should probably add the sentence in the docs, like this:

 "A contention group defines a set of one or more fields that
collectively must be isolated from all other contention groups. [The
fields in the same contention group may not be pair-wise isolated]".


> I don't know if this is useful anyway. Could a superclass correctly 
> anticipate the "global" group in some situations?

I think what is being proposed for @C to work across the hierarchy is
the overkill, handles no useful cases, but bears the significant
development cost to do. That's the recipe for saying "nope!" :) Don't
try to turn @Contended into the swiss army knife field layout hint. It
is not.


-Aleksey.