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

[David Holmes]

On 24/05/2013 2:48 AM, Aleksey Shipilev wrote:
> Also, let's wait for David Holmes to glance over it. He has the immense
> capability to spot the weaknesses in the specifications.

Wow talk about pressure! Now I'm obligated to find a weakness. ;-)

Luckily Mike and Peter already touched on a few things so ...

1. I prefer the rephrasing below to make it clear that @Contended on a 
field-less class need not be a no-op.

2. I think something needs to be said about this property and inheritance.

3. I think this:

     The (optional) contention group tag

should be

     The (optional) field contention group tag

and we should also say in the main paragraph that a tag at the class 
level is ignored.

4. I'm a little unclear about the group tags. It states:

"A default annotation without a tag indicates contention with all other
fields, including other {@code @Contended} ones."

That seems to imply that given:

class A {
   @Contended Object a1;
   @Contended Object a2;
}

then a1 and a2 are in different contention groups. ??? Yet I would 
expect the default annotation value to simply imply a single un-named 
contention group. Just as the annotation at the class level implies a 
single un-named group for all unannotated fields. But does that also 
imply that given:

@Contended
class A {
   @Contended Object a1;
   Object a2;
}

there are two un-named contention groups?


I'm not sure that anyone without knowledge of the implementation will be 
able to use contention groups effectively.

David
-----

> -Aleksey.
>
> On 05/23/2013 08:47 PM, Aleksey Shipilev wrote:
>> Ummm... I think that's exactly what the last paragraph says. What if we
>> rephrase it as follows?
>>
>> ------------- 8< -----------------------------------------------
>> When the annotation is used at the class level, the effect is
>> roughly equivalent to placing the {@code @Contended} annotation
>> with the anonymous tag over all the unannotated fields of the
>> object. With the class level annotation, the implementations may
>> choose different approach to protect the entire object, rather
>> than protecting only the distinct fields.
>> ------------- 8< -----------------------------------------------
>>
>> -Aleksey.
>>
>> On 05/23/2013 08:20 PM, Mike Duigou wrote:
>>> You could add one more sentence to cover the effect of @C on class
>>> with no @C on any field. The response to Peter is great info (but too
>>> much detail for JavaDoc).
>>>
>>> Mike
>>>
>>> On May 23 2013, at 09:17 , Aleksey Shipilev wrote:
>>>
>>>> On 05/23/2013 06:33 PM, Mike Duigou wrote:
>>>>> A class level annotation on a class containing no annotated
>>>>> fields has no effect, correct?
>>>>
>>>> It does have the effect, see the last paragraph in the Javadoc.
>>>> Should we refine this a bit?
>>>>
>>>> -Aleksey.
>>>
>>
>