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

[Martin Buchholz]

On Tue, May 28, 2013 at 2:26 PM, Aleksey Shipilev <
aleksey.shipilev at oracle.com> wrote:

> On 05/29/2013 12:38 AM, Martin Buchholz wrote:
>
> > 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?
>
>
Yeah, we have the same problem with javadoc issuing very verbose warnings.
 I've been ignoring/filtering them and hoping they get fixed before jdk8
ships.


> > + * 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".
>
>
I was thinking "classes, not objects, are annotated".


> > 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 :)
>
>
Hmmm... tricky ... This also then applies to pure immutable popular objects
like Boolean.TRUE. But you want those kinds of objects to all be colocated
and tightly packed with other such objects, not give each of them their own
cache line.


> > 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.
>
>
Sounds like a Quality of Implementation issue.  In general, I think you
*DO* want the subclass fields to be potentially in the same location as the
superclass padding fields.
A >: B
A layout: ppppaaaapppp
B layout: ppppaaaabbbbpppp

which is not asking too much of a jit.
I believe it is already common for VMs to allocate subclass fields in
natural padding space of superclasses.

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

Good point.

I can imagine an "unpopular field" annotation that would allow a field to
be used __as__ a pad inside an otherwise contended class.  Or unpopular
objects can be packed into the same cache line as contended objects.
 Software is hard.