Merge to tag jdk-28+10

doc/testing.html

@@ -465,6 +465,44 @@ <h4 id="test_thread_factory">TEST_THREAD_FACTORY</h4>
 <code>test/jtreg_test_thread_factory/</code> directory. This class gets
 compiled during the test image build. The implementation of the Virtual
 class creates a new virtual thread for executing each test class.</p>
+<h4 id="value_class_plugin">VALUE_CLASS_PLUGIN</h4>
+<p>Enables the <code>ValueClassPlugin</code> javac plugin when compiling
+and running JTReg tests. This is a <strong>temporary mode</strong>
+intended for use while value classes (JEP 401) are a preview feature.
+The long-term plan is to replace classes annotated with
+<code>@jdk.test.lib.valueclass.AsValueClass</code> with plain
+<code>value class</code> declarations once value classes are
+finalized.</p>
+<p>In the meantime, this mode allows test sources to compile and run as
+either value classes or regular identity classes without source-level
+changes.</p>
+<p>When set to any non-empty value, the following options are appended to
+every JTReg invocation:</p>
+<ul>
+<li><code>-cpa:&lt;valueClassPlugin.jar&gt;</code> — appends the plugin
+JAR to the compile-time classpath (only when the JAR is present in the
+test image under
+<code>jtreg_value_class_plugin/valueClassPlugin.jar</code>).</li>
+<li><code>-vmoption:--enable-preview</code> — enables JVM preview
+features at runtime.</li>
+<li><code>-javacoption:-XDaccessInternalAPI</code> — grants the compiler
+access to internal APIs required by the plugin.</li>
+<li><code>-javacoption:--source &lt;version&gt; --enable-preview</code>
+— enables preview language features at compile time.</li>
+<li><code>-javacoption:-Xplugin:ValueClassPlugin</code> — activates the
+plugin.</li>
+</ul>
+<p>The plugin scans each compilation unit after parsing and converts any
+class annotated with
+<code>@jdk.test.lib.valueclass.AsValueClass</code> into a value class by
+setting the internal <code>VALUE_CLASS</code> modifier flag and clearing
+the <code>IDENTITY_TYPE</code> flag. This transformation only takes
+effect when <code>--enable-preview</code> is active; without it the
+annotation is a no-op and the class compiles as an ordinary identity
+class, so the same test source can exercise both code paths.</p>
+<p>Example:</p>
+<pre><code>$ make test TEST=jdk_lang JTREG="VALUE_CLASS_PLUGIN=true"
+</code></pre>
 <h4 id="jvmti_stress_agent">JVMTI_STRESS_AGENT</h4>
 <p>Executes JTReg tests with JVM TI stress agent. The stress agent is
 the part of test library and located in

doc/testing.md

@@ -403,6 +403,42 @@ the `test/jtreg_test_thread_factory/` directory. This class gets compiled
 during the test image build. The implementation of the Virtual class creates a
 new virtual thread for executing each test class.
 
+#### VALUE_CLASS_PLUGIN
+
+Enables the `ValueClassPlugin` javac plugin when compiling and running JTReg
+tests. This is a **temporary mode** intended for use while value classes
+(JEP 401) are a preview feature. The long-term plan is to replace classes
+annotated with `@jdk.test.lib.valueclass.AsValueClass` with plain
+`value class` declarations once value classes are finalized.
+
+In the meantime, this mode allows test sources to compile and run as either
+value classes or regular identity classes without source-level changes.
+
+When set to any non-empty value, the following options are appended to every
+JTReg invocation:
+
+* `-cpa:<valueClassPlugin.jar>` — appends the plugin JAR to the compile-time
+  classpath (only when the JAR is present in the test image under
+  `jtreg_value_class_plugin/valueClassPlugin.jar`).
+* `-vmoption:--enable-preview` — enables JVM preview features at runtime.
+* `-javacoption:-XDaccessInternalAPI` — grants the compiler access to internal
+  APIs required by the plugin.
+* `-javacoption:--source <version> --enable-preview` — enables preview language
+  features at compile time.
+* `-javacoption:-Xplugin:ValueClassPlugin` — activates the plugin.
+
+The plugin scans each compilation unit after parsing and converts any class
+annotated with `@jdk.test.lib.valueclass.AsValueClass` into a value class by
+setting the internal `VALUE_CLASS` modifier flag and clearing the
+`IDENTITY_TYPE` flag. This transformation only takes effect when
+`--enable-preview` is active; without it the annotation is a no-op and the
+class compiles as an ordinary identity class, so the same test source can
+exercise both code paths.
+
+Example:
+
+    $ make test TEST=jdk_lang JTREG="VALUE_CLASS_PLUGIN=true"
+
 #### JVMTI_STRESS_AGENT
 
 Executes JTReg tests with JVM TI stress agent. The stress agent is the part of

doc/value-class-preview.html

@@ -0,0 +1,188 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>Migration of JDK Classes to Value Classes</title>
+  <style>
+    code{white-space: pre-wrap;}
+    span.smallcaps{font-variant: small-caps;}
+    div.columns{display: flex; gap: min(4vw, 1.5em);}
+    div.column{flex: auto; overflow-x: auto;}
+    div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
+    ul.task-list{list-style: none;}
+    ul.task-list li input[type="checkbox"] {
+      width: 0.8em;
+      margin: 0 0.8em 0.2em -1.6em;
+      vertical-align: middle;
+    }
+    .display.math{display: block; text-align: center; margin: 0.5rem auto;}
+  </style>
+  <link rel="stylesheet" href="../make/data/docs-resources/resources/jdk-default.css" />
+  <style type="text/css">pre, code, tt { color: #1d6ae5; }</style>
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+</head>
+<body>
+<header id="title-block-header">
+<h1 class="title">Migration of JDK Classes to Value Classes</h1>
+</header>
+<nav id="TOC" role="doc-toc">
+<ul>
+<li><a href="#introduction" id="toc-introduction">Introduction</a></li>
+<li><a href="#the-build-process" id="toc-the-build-process">The Build
+Process</a>
+<ul>
+<li><a href="#the-custom-handling-for-the-value-objects-jep"
+id="toc-the-custom-handling-for-the-value-objects-jep">The Custom
+Handling for the Value Objects JEP</a></li>
+<li><a href="#the-general-preview-source-to-binary-pipeline"
+id="toc-the-general-preview-source-to-binary-pipeline">The General
+Preview Source to Binary Pipeline</a></li>
+<li><a href="#non-goals" id="toc-non-goals">Non-Goals</a></li>
+</ul></li>
+<li><a href="#testing" id="toc-testing">Testing</a></li>
+<li><a href="#wrapper-class-caches"
+id="toc-wrapper-class-caches">Wrapper Class Caches</a></li>
+<li><a href="#editing-this-document"
+id="toc-editing-this-document">Editing This Document</a></li>
+</ul>
+</nav>
+<h2 id="introduction">Introduction</h2>
+<p>The Value Objects feature introduces value objects and migrates
+suitable classes to value classes. This means that when preview features
+are enabled, different class files are used for the migrated classes in
+the Java class library.</p>
+<p>To accomplish this, a built JDK uses <em>preview-specific</em> files
+in <code>META-INF/preview</code>, which overrides the regular files of
+the same name. For example,
+<code>META-INF/preview/java/lang/Integer.class</code> overrides
+<code>java/lang/Integer.class</code>.</p>
+<p>The JDK generates preview-specific source files (they may use preview
+language features), compiles class files from them, and distributes
+these class files in <code>META-INF/preview</code>.</p>
+<h2 id="the-build-process">The Build Process</h2>
+<h3 id="the-custom-handling-for-the-value-objects-jep">The Custom
+Handling for the Value Objects JEP</h3>
+<p>The Value Objects JEP requires a few select classes in the
+<code>java.base</code> module to become value classes when preview
+features are enabled.</p>
+<p>The build of <code>java.base</code> module first creates the source
+code of those value classes, done in <a
+href="../make/modules/java.base/gensrc/GensrcValueClasses.gmk"><code>GensrcValueClasses.gmk</code></a>.</p>
+<ol type="1">
+<li><p>A hardcoded list of regular source files are selected for
+preview-specific generation.</p></li>
+<li><p>Extract the content of each regular source file, search for any
+occurrences of <code>/*value*/ class</code> or
+<code>/*value*/ record</code>, and replace with <code>value class</code>
+or <code>value record</code>.</p></li>
+<li><p>The replaced contents are written to the preview-specific
+generated files, located in
+<code>support/gensrc-valueclasses/java.base/</code>. The regular source
+files remain unchanged in their original locations.</p></li>
+<li><p>The general preview source to binary build pipeline recognizes
+the <code>support/gensrc-valueclasses/java.base/</code> directory as
+where the <code>java.base</code> module places its preview-specific
+source files.</p></li>
+</ol>
+<h3 id="the-general-preview-source-to-binary-pipeline">The General
+Preview Source to Binary Pipeline</h3>
+<p>Once the preview-specific source files are ready, they are picked up
+by the build system into a fully automated pipeline handling all modules
+and all outcome images.</p>
+<ol type="1">
+<li><p>The <code>GENERATED_PREVIEW_SUBDIRS</code> variable in <a
+href="../make/common/Modules.gmk"><code>make/common/Modules.gmk</code></a>
+indicates where the source files are found.</p></li>
+<li><p>For each module that has preview-specific source files, a goal is
+created to compile these source files into class files.</p></li>
+<li><p>The class files from each of these tasks reside in
+<code>support/preview/&lt;module&gt;</code> for each module.</p></li>
+<li><p>These preview-specific class files and other resources are copied
+to the <code>META-INF/preview</code> directory of the regular output
+directory.</p></li>
+<li><p>At run-time, jimage will pick up the preview-specific overrides
+from <code>META-INF/preview</code> only when preview features are
+enabled.</p></li>
+<li><p>The interim javac used by the build system cannot pick up the
+preview-specific overrides; they must be supplied explicitly with the
+following javac flag for every single module where overrides are
+significant:</p>
+<pre><code>--patch-module &lt;module&gt;=$(SUPPORT_OUTPUTDIR)/preview/&lt;module&gt;</code></pre>
+<p>See <a
+href="../make/test/BuildMicrobenchmark.gmk"><code>BuildMicroBenchmarks.gmk</code></a>
+for an example.</p></li>
+</ol>
+<h3 id="non-goals">Non-Goals</h3>
+<p>The Value Objects JEP only plans to introduce value classes that
+are:</p>
+<ol type="1">
+<li><p>In the <code>java.base</code> module.</p>
+<p>There's no plan to migrate other classes in other modules.</p></li>
+<li><p>Migrated from existing classes.</p>
+<p>These classes are available as identity classes when preview features
+are disabled. There's no plan to introduce completely new value
+classes.</p></li>
+</ol>
+<p>Support for other value classes would require significant changes to
+the build system.</p>
+<h2 id="testing">Testing</h2>
+<p>In addition to tests that require preview features to be enabled,
+tests that do not depend on preview features wish to run with preview
+features enabled to ensure compatibility:</p>
+<ol type="1">
+<li><p>Some tests wish to run against the Java SE class library with
+value classes.</p>
+<p>The jtreg tests may be run with
+<code>JTREG=VM_OPTIONS=--enable-preview</code>.</p></li>
+<li><p>Some tests wish to run against their own classes migrated to
+value classes.</p>
+<p>The jtreg <a
+href="testing.html#VALUE_CLASS_PLUGIN">VALUE_CLASS_PLUGIN</a> allows
+tests to migrate their own classes to value classes when running with
+the plugin.</p></li>
+</ol>
+<h2 id="wrapper-class-caches">Wrapper Class Caches</h2>
+<p>Currently, wrapper class caches are retained even when preview
+features are enabled to address performance losses. They have no
+semantic impact to value objects.</p>
+<p>In interpreter or C1 execution in Hotspot, allocations of a value
+object to the heap as a full object with header happen when a value
+object is:</p>
+<ol type="1">
+<li>Loaded from a flat storage (field or array)</li>
+<li>Created by a constructor</li>
+<li>If C2 uses scalarized calling convention, at C2 to C1/interpreter
+calls and returns</li>
+</ol>
+<p>Ideally, C2 can eliminate such allocations, but this does not work if
+the resulting object is stored into references. Unfortunately, many uses
+of boxing conversions store the resulting wrapper objects as
+references.</p>
+<p>For the uses that store wrapper objects to references, if the boxing
+conversion is:</p>
+<ol type="1">
+<li>Returning a value object from a flat cache array</li>
+<li>Calling the value class constructor</li>
+</ol>
+<p>Then we would have heap allocation on every single use.</p>
+<p>To avoid the allocations, we fall back to returning a value object
+from a reference cache array, from which the loaded reference is
+directly storable into a destination that wants a reference without any
+allocation.</p>
+<p>Since Hotspot may create flat arrays if an array of value objects is
+requested by regular Java array creation mechanisms, we use
+<code>ValueClass.newReferenceArray</code> to ensure we always create a
+reference cache array.</p>
+<p>The cache array for value objects may be removed without notice if
+the performance losses from allocations are no longer significant.</p>
+<h2 id="editing-this-document">Editing This Document</h2>
+<p>If you want to contribute changes to this document, edit
+<code>doc/value-class-preview.md</code> and then run
+<code>make update-build-docs</code> to generate the same changes in
+<code>doc/value-class-preview.html</code>.</p>
+</body>
+</html>