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

Aleksey Shipilev aleksey.shipilev at oracle.com
Mon May 27 12:44:32 UTC 2013

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 distinct and anonymous 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 same 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() Object a1; @Contended() Object a2; @Contended() 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.

More information about the core-libs-dev mailing list