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

[Aleksey Shipilev]

Thanks!

Let's try to re-phrase this as follows (don't mind Javadoc formatting
glitches, I'll fix them in the upcoming webrev):

--------- 8< ----------------------------------------------------------

/*
An annotation expressing that objects and/or their fields are
expected to encounter memory contention, generally in the form of
"false sharing". This annotation serves as a hint that such objects
and fields should reside in locations isolated from those of other
objects or fields. Susceptibility to memory contention is a
property of the intended usages of objects and fields, not their
types or qualifiers. The effects of this annotation will nearly
always add significant space overhead to objects. The use of
{@code @Contended} is warranted only when the performance impact of
this time/space tradeoff is intrinsically worthwhile; for example,
in concurrent contexts in which each instance of the annotated
object is often accessed by a different thread.

A {@code @Contended} field annotation may optionally include a
contention group tag. All fields with the same tag are considered as a
group with respect to isolation from other groups. A default tag
indicates the <i>distinct</i> and <i>anonymous</i> contention group,
which implies the contention with all other fields, including all other
{@code @Contended} ones. The tag at a class level is meaningless, and
ignored.

When the annotation is used at the class level, the effect is
roughly equivalent to placing the {@code @Contended} annotation
with the <i>same</i> 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.

The {@code @Contended} annotation is not inherited, and acts only
within the class it was used on. The effects, however, should be
enforced across the inheritance, e.g. the {@code @Contended} fields
should be isolated from all the fields in super- and sub-classes. The
contention group tags are not inherited as well: the similar tags in two
subclasses mean different groups.

@since 1.8
*/
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.TYPE})
public @interface Contended {

    /**
     * The (optional) contention group tag.
     * This tag is only meaningful for the field-level annotations.
     */
    String value() default "";
}

--------- 8< ----------------------------------------------------------



On 05/24/2013 03:58 AM, David Holmes wrote:
> 2. I think something needs to be said about this property and inheritance.

Added.

> 3. I think this:
> 
>     The (optional) contention group tag
> 
> should be
> 
>     The (optional) field contention group tag

This sounds awkward? Would it be better to note it is only meaningful on
the fields?

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

Added.

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

I think this is would be easier to digest if we introduce the concept of
anonymous group, see the new text.

> That seems to imply that given:
> 
> class A {
>   @Contended Object a1;
>   @Contended Object a2;
> }
> 
> then a1 and a2 are in different contention groups. ??? 

Yes, these are different contention groups.

> Yet I would expect the default annotation value to simply imply a
> single un-named contention group.

That's an interesting interpretation. I guess we should stress it is the
other way around: the tag-less @C always creates distinct anonymous
group, and you can merge two @C with supplying the tag.

> 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?

Yes, that follows from the definition of class-level @C; your example
effectively means putting all the _unannotated_ fields in the same
anonymous group, i.e.:

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

...means:

class A {
  @Contended(<anonymousA>) Object a1;
  @Contended(<anonymousB>) Object a2;
  @Contended(<anonymousB>) Object a3;
}

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

Even though this is an internal API, we would like to churn all the
major things with the understandable Javadoc, hence this thread.

-Aleksey.