[lworld] RFR: 8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics [v3]

[Jatin Bhateja]

On Thu, 10 Apr 2025 15:29:40 GMT, Quan Anh Mai <qamai at openjdk.org> wrote:

>> Hi,
>> 
>> This patch clarifies the meaning of undefined behavior when working with `Unsafe` and specifies the requirements when working with `Unsafe::makePrivateBuffer` and `Unsafe::finishPrivateBuffer`.
>> 
>> Please take a look and leave your suggestions, thanks a lot.
>
> Quan Anh Mai has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove unnecessary statements

src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 424:

> 422: 
> 423:     /**
> 424:      * Returns an object instance with a private buffered value whose layout

Suggestion:

     * Returns a value type instance with a private buffered value whose layout

src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 426:

> 424:      * Returns an object instance with a private buffered value whose layout
> 425:      * and contents is exactly the given value instance. The return object is
> 426:      * in the larval state that can be updated using the unsafe put operation.

Suggestion:

     * in the larval state that can be modified through an unsafe put operation.

src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 430:

> 428:      * This method mimics the operation of the bytecode {@code new}, allowing
> 429:      * the creation of a value object without the conventional Java procedure
> 430:      * and bypassing the bytecode verifier regarding larval objects. As a

Suggestion:

     * the creation of a value object without the conventional Java procedure
     * and bypassing usual verification applicable to @{code new} bytecode. As a

src/java.base/share/classes/jdk/internal/misc/Unsafe.java line 443:

> 441:      * <li>The return object can only be used as the first argument passed to
> 442:      * {@code Unsafe::putXXX} or to {@link #finishPrivateBuffer(Object)}, any
> 443:      * other usage, such as loading from or returning it, is illegal. The only

Suggestion:

     * other usage, such as reading any of its fields or returning it, is illegal. The only

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

PR Review Comment: https://git.openjdk.org/valhalla/pull/1425#discussion_r2092510279
PR Review Comment: https://git.openjdk.org/valhalla/pull/1425#discussion_r2092516930
PR Review Comment: https://git.openjdk.org/valhalla/pull/1425#discussion_r2092626215
PR Review Comment: https://git.openjdk.org/valhalla/pull/1425#discussion_r2092635101