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

David Holmes david.holmes at oracle.com
Thu May 23 23:58:52 UTC 2013

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.

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

More information about the core-libs-dev mailing list