8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics #1425

merykitty · 2025-04-09T13:18:39Z

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.

Progress

Change must not contain extraneous whitespace

Issue

JDK-8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics (Enhancement - P4)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/valhalla.git pull/1425/head:pull/1425
$ git checkout pull/1425

Update a local copy of the PR:
$ git checkout pull/1425
$ git pull https://git.openjdk.org/valhalla.git pull/1425/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 1425

View PR using the GUI difftool:
$ git pr show -t 1425

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/valhalla/pull/1425.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-04-09T13:19:22Z

👋 Welcome back qamai! A progress list of the required criteria for merging this PR into lworld will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-04-09T13:19:39Z

@merykitty This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 85 new commits pushed to the lworld branch:

603ac0e: 8353717: [lworld] Complete merge of 8350756
15a064c: 8348606: [lworld] Substitutability test may perform heap allocations
ea9789c: Merge jdk
... and 82 more: https://git.openjdk.org/valhalla/compare/b5395e82b1cce79d3139917b6d151f99ca90ee91...lworld

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

mlbridge · 2025-04-09T13:23:31Z

Webrevs

liach · 2025-04-09T14:02:42Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+ * with illegal arguments, undefined behavior may time travel. That is, if a
+ * control path may eventually reach an invocation of an {@code Unsafe} method
+ * with illegal arguments, the symptoms of undefined behavior may be present
+ * even before the invocation of the {@code Unsafe} method.


I think you can talk in a more JIT-oriented manner, that while Unsafe is mostly set up to be the hooks between core libraries and hotspot runtime, hotspot compiler may interpret the input values and perform aggressive optimizations with contracts that cannot be explicitly expressed by Java program semantics.

Done, not only the JIT, but the runtime may exhibit unpredictable behaviors in the presence of UB, too.

RogerRiggs · 2025-04-10T13:15:15Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+ * By default, usage of all methods in this class exhibits undefined behavior,
+ * unless otherwise explicitly specified.


The "by default" and "unless otherwise specified" seems to be redundant.

Suggested change

* By default, usage of all methods in this class exhibits undefined behavior,

* unless otherwise explicitly specified.

* Unless otherwise explicitly specified, all methods in this class can exhibit undefined behavior.

* .

I decide to just remove it as each method specifies its behaviours already.

RogerRiggs · 2025-04-10T13:25:38Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * value of this method. The object must also be not assigned to another
+     * local variable.


Why this restriction? What assumption is violated if there is a second assignment?

There is none, but it would be easier to specify the restriction on Unsafe::finishPrivateBuffer as the only variable referring to the larval object is the one passed into that method. Otherwise, we must say that all variables referring to the object must not be used. This, however, sounds like a runtime constraint while what we really mean is a compile-time constraint. As a result, I think this restriction is harmless but make our life easier.

RogerRiggs · 2025-04-10T13:26:50Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * {@code Unsafe::putXXX} or to {@link #finishPrivateBuffer(Object)}, any
+     * other usage, such as loading from or returning it, is illegal. The only
+     * exception is the implicit check cast inserted by the compiler on the
+     * return value of this method. Explicit check casts are not allowed.


"not allowed"? But there is no enforcement; unpredictable behavior yes.

Not allowed here in the sense that failure to do so will result in undefined behavior.

RogerRiggs · 2025-04-10T13:27:42Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * exception is the implicit check cast inserted by the compiler on the
+     * return value of this method. Explicit check casts are not allowed.
+     * </ul>
+     * Illegal usage of this method exhibits undefined behavior even if the


may or can; but not always.

Illegal usage ALWAYS exhibits undefined behavior, the uncertainty here is that whether this undefined behavior manifests itself as an unexpected operation.

RogerRiggs · 2025-04-10T13:29:10Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * Illegal usage of this method exhibits undefined behavior even if the
+     * illegal statements are never actually reached at runtime.


Another can/may exhibit case; improve the phrase everywhere.

RogerRiggs · 2025-04-10T13:30:15Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * {@link #makePrivateBuffer(Object)}.
+     * <li>After the invocation of this method, the variable that holds the
+     * argument passed into this method must not be used.
+     * </ul>


I would add the exhortation that every field of the value object must have a value.

Unsafe::makePrivateBuffer takes a non-larval value object so all of its fields always have a value.

bridgekeeper · 2025-05-08T16:08:28Z

@merykitty This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply issue a /touch or /keepalive command to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

merykitty · 2025-05-14T13:07:59Z

Can I have this PR reviewed, please?

jatin-bhateja · 2025-05-16T12:10:27Z

Hi @merykitty ,

Just to complement your documentation update, I have created test scenarios for various verification errors around implicit larval objects, i.e. the ones created using new operator but are still pending initialization, explicit larvals generated using Unsafe.makePrivateBuffer should adhere to the same semantics.

Implicit larval objects verification.docx

Overall, your changes look good to me; finer refinements can be done in due course, but specs are much clear now, thank you so much!

jatin-bhateja · 2025-05-16T07:39:33Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

@@ -381,8 +422,30 @@ public native Object[] newSpecialArray(Class<?> componentType,

    /**
     * Returns an object instance with a private buffered value whose layout


Suggested change

* Returns an object instance with a private buffered value whose layout

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

jatin-bhateja · 2025-05-16T07:43:45Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

-     * and contents is exactly the given value instance.  The return object
-     * is in the larval state that can be updated using the unsafe put operation.
+     * and contents is exactly the given value instance. The return object is
+     * in the larval state that can be updated using the unsafe put operation.


Suggested change

* in the larval state that can be updated using the unsafe put operation.

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

jatin-bhateja · 2025-05-16T08:50:59Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+     * the creation of a value object without the conventional Java procedure
+     * and bypassing the bytecode verifier regarding larval objects. As a


Suggested change

* the creation of a value object without the conventional Java procedure

* and bypassing the bytecode verifier regarding larval objects. As a

* the creation of a value object without the conventional Java procedure

* and bypassing usual verification applicable to @{code new} bytecode. As a

jatin-bhateja · 2025-05-16T08:56:03Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

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


Suggested change

* other usage, such as loading from or returning it, is illegal. The only

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

liach · 2025-05-16T12:25:54Z

src/java.base/share/classes/jdk/internal/misc/Unsafe.java

+ * simultaneously 0 and 1.
+ * <li>Impossible code execution. E.g. the branches of an {@code if} are
+ * both executed or both not executed.
+ * <li>Wiping out the hard drive.


I think these are just for alerting people; this is not that valuable to create a huge list to specifically highlight. I think what we should highlight instead is the best practices.

bridgekeeper · 2025-06-13T13:14:46Z

@merykitty This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply issue a /touch or /keepalive command to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

liach · 2025-06-13T19:54:36Z

Should we change these long paragraphs to a design document, as suggested in openjdk/jdk#24777 (review)?

specify undefined behavior and Valhalla intrinsics

ebfbd7b

openjdk bot added ready rfr labels Apr 9, 2025

liach reviewed Apr 9, 2025

View reviewed changes

more explanation

b869e10

RogerRiggs reviewed Apr 10, 2025

View reviewed changes

remove unnecessary statements

130f897

jatin-bhateja reviewed May 16, 2025

View reviewed changes

liach reviewed May 16, 2025

View reviewed changes

		* By default, usage of all methods in this class exhibits undefined behavior,
		* unless otherwise explicitly specified.

		* value of this method. The object must also be not assigned to another
		* local variable.

		* Illegal usage of this method exhibits undefined behavior even if the
		* illegal statements are never actually reached at runtime.

		@@ -381,8 +422,30 @@ public native Object[] newSpecialArray(Class<?> componentType,

		/**
		* Returns an object instance with a private buffered value whose layout

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

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

		* the creation of a value object without the conventional Java procedure
		* and bypassing the bytecode verifier regarding larval objects. As a

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

8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics #1425

Are you sure you want to change the base?

8353236: [lworld] Better documentation for Valhalla Unsafe intrinsics #1425

Uh oh!

Conversation

merykitty commented Apr 9, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewing

Uh oh!

bridgekeeper bot commented Apr 9, 2025

Uh oh!

openjdk bot commented Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mlbridge bot commented Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bridgekeeper bot commented May 8, 2025

Uh oh!

merykitty commented May 14, 2025

Uh oh!

jatin-bhateja commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bridgekeeper bot commented Jun 13, 2025

Uh oh!

liach commented Jun 13, 2025

Uh oh!

Uh oh!

merykitty commented Apr 9, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Apr 9, 2025 •

edited

Loading

mlbridge bot commented Apr 9, 2025 •

edited

Loading

jatin-bhateja commented May 16, 2025 •

edited

Loading