RFR (S) CR 8014966: Add the proper Javadoc to @Contended
aleksey.shipilev at oracle.com
Tue May 28 21:26:28 UTC 2013
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
> 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.
More information about the core-libs-dev