RFR: 8254275: Development to revise "value-based class" & apply to wrappers [v2]

[Roger Riggs]

On Tue, 13 Oct 2020 22:59:36 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

>> Polishing the specification of "value-based class" to align with requirements of inline classes, allow classes (like
>> Integer) with deprecated constructors, and clarify expectations for clients.
>> Full docs build: http://cr.openjdk.java.net/~dlsmith/8254275/8254275-20201013/api/index.html
>
> Dan Smith has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Revise definition for more flexible ==. Apply revised boilerplate to wrappers and existing references.

In the text referring to ValueBase.html in many classes:

Is the "," misplaced.  Should it read:
"not use instances for synchronization or unpredictable behavior may occur."

If the comment in each class was a simple reference to ValueBased, it would be easier to maintain and there would be
less duplication between lots of classes and the explanation in ValueBased.html.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 43:

> 41:         <code>hashCode</code>, and <code>toString</code> which are computed
> 42:         solely from the instance's state and not from its identity or the state
> 43:         of any other object or variable;</li>

Quibble on pre-existing text:

If the instance state is a reference to another object, can its hashCode be included in the hashCode?
The " not... from the state of any object" would seem to prohibit that.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 49:

> 47:         the behavior of the class's methods;
> 48:     </li>
> 49:     <li>perform no synchronization on an instance's intrinsic lock;</li>

"Intrinsic lock": should be a more concrete reference to some term in the JLS or JVMS.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 52:

> 50:     <li>do not have (or have deprecated any) accessible constructors;</li>
> 51:     <li>may support instance creation through factory methods that do <em>not</em>
> 52:         promise a unique identity for each invocation—in particular, each factory

Since the factory method are in a value-based classes, they are not allowed to promise a unique identity.
So that statement is always true in the value-based context.

Use "," instead of "-" or start a new sentence.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 55:

> 53:         method must allow for the possibility that if two independently-produced
> 54:         instances are equal according to <code>equals()</code>, they may also be
> 55:         equal according to <code>==</code>;

Is using "may" a way to allow contradiction of the previous requirements?
Otherwise, in a spec, any statement using 'may' can be ignored or removed, it does not specify any behavior either
required or disallowed.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 70:

> 68: <p>Synchronization on instances of value-based classes is strongly discouraged,
> 69:     because the programmer cannot usually guarantee unique ownership of the
> 70:     associated lock.</p>

I don't think the phrase:
`because the programmer cannot usually guarantee unique ownership of the associated lock.`
adds anything and is obscure.  Until the semantics of object change, there is no change in the synchronization behavior.
For Valhalla value-based instances, there is explicitly no (implicitly) associated lock, so synchronization is illegal.

-------------

PR: https://git.openjdk.java.net/valhalla/pull/222