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

[Aleksey Shipilev]

On 05/29/2013 12:38 AM, Martin Buchholz wrote:
> Tricky stuff!

You bet! Thanks for the review! I'll wait for more reviews, and update
the webrev.

> We don't use closing html tags for things like <p> in javadoc.

Ok, JDK 8 doclint does not like self-closing entities, and leaving
unterminated <p> seems dodgy. Should I revert to <p> to demarcate the
start of paragraph?

> + * in concurrent contexts in which each instance of the annotated
> + * object is often accessed by a different thread.</p>
> 
> Hmmm...  makes it sound like it applies even if each instance is
> thread-confined (in a different thread) or is immutable.  

I think all the magic of ignoring @C when VM can prove the
instance/fields would not experience contention, should be omitted from
the documentation. The practical considerations also apply: since we can
not at the moment retransform the class after the publication, it seems
a good idea to treat all instances as potentially shared. This eases the
reasoning (and documentation) significantly.

> "objects" are not annotated.

Yes, should be "instances".

> Maybe "instances of the annotated class are frequently accessed by
> multiple threads and have fields that are frequently written".

"Accessed" matters there. False sharing also happens on reads. Also, the
innocent read-only classes sometimes also need the protection from the
adjacent writers' racket :)

> Subclassing makes things tricky.  I think it would be pretty common to
> want a subclass field to be in the same contention group as a superclass
> contention group.

Unfortunately, this falls out from being practical. When the superclass
fields are already laid out, it is generally too late to squeeze the
subclass fields in there.

> however, remain in force for all
> + * superclass and subclass instances
> 
> 
> "remain in force for superclass instances" doesn't make sense to me.  Do
> you mean "remain in force when fields are inherited in subclasses"

Yes, that sounds better!

> Do we want final fields to be explicitly exempt from being treated as
> contended?  Or is that Quality of Implementation?  Do we want to insert
> the word "non-final" in "all the unannotated fields"

"final" does not sound to be eligible for any exemption. It is totally
fine for the final field to be @Contended, if we want to protect it from
being disturbed by the adjacent writes. Although users would probably
mark the writable fields in most of the cases, think about the case
where I should not absolutely-under-no-curcumstances have the false
shared read of the final field.

-Aleksey.