add more method-level options for -XX:CompileCommand
eg. -XX:CompileCommand=option,java.lang.String::startsWith,BreakAtCompile directs JIT compilers to hit BREAKPOINT when they compile the method java.lang.String::startsWith.
Reviewed-by: neliasso, azeemj, phh
Use the code motion trace produced by TraceOptoPipelining (excluding traces of
stubs) to assert that two compilations with the same seed cause StressLCM and
StressGCM to take the same randomized decisions. Previously, the entire output
produced by PrintOptoStatistics was used instead, which has shown to be too
fragile. Also, disable inlining in both TestStressCM.java and the similar
TestStressIGVN.java to prevent flaky behavior, and run both tests for ten
different seeds to improve coverage.
Reviewed-by: kvn, thartmann
disconnect_inputs() needs to iterate precedences edges in reverse order because rm_prec(i) may backfill _in[i] with a value afterward.
also remove the predicate if (n != NULL) in set_prec because it's always true.
Reviewed-by: kvn, redestad
Remove test assertion checking that different random seeds lead to different
code motion decisions. This was the case for the specific pair of random seeds,
IR fed to code motion, and target platforms tested originally; but does not need
to hold in general. Remove similar test assertion in IGVN randomization test
case. Re-enable the test case.
Reviewed-by: shade, kvn
Use the compilation-local seed in 'StressLCM' and 'StressGCM' rather than the
global one. As a consequence, these options use by default a fresh seed in every
compilation, unless 'StressSeed=N' is specified, in which case they behave
deterministically. Annotate tests that use 'StressLCM' and 'StressGCM' with the
'stress' and 'randomness' keys to reflect this change in default behavior.
Reviewed-by: kvn, thartmann
Record nodes as dead in Node::destruct() if their index cannot be directly
reclaimed. This prevents the "Live Node limit exceeded limit" assertion failure
by improving the accuracy of Compile::live_nodes() when "hook" nodes in
ConvI2LNode::Ideal() are created and deleted non-consecutively.
This addition might result in multiple calls to compile::record_dead_node() for
the same node (e.g. from PhaseIdealLoop::spinup()), but this is safe, as
compile::record_dead_node() is idempotent.
Reviewed-by: neliasso, thartmann
Account for interface files for swap and memory being reported independently.
The cgroup v1-like value is now reported by adding the memory.max value to
the memory.swap.max value, and memory.current and memory.swap.current
respectively.
Reviewed-by: bobv, shade
Update NodeClasses::_max_classes to the max class id within the
enumeration. Update comment and assertion to reflect that NodeClasses uses now
32 bits after the addition of Opaque1 in JDK-8229495.
Reviewed-by: neliasso, kvn
Replace double array with short array in AdapterHandlerLibrary::create_native_wrapper, add parens around ?: in CSystemColors:getColor
Reviewed-by: prr, kbarrett, lucy
The early implementation of cgroups v2 support was done with
crun 0.8 and it contained a bug which set memory.high over
memory.low when --memory-reservation was being used as a CLI
option.
This bug has been fixed in later crun versions, starting with
crun 0.11. Use memory.low in OpenJDK as well.
Reviewed-by: bobv, adinn
Add 'StressIGVN' option to let C2 randomize IGVN worklist order. When enabled,
the worklist is shuffled before each main run of the IGVN loop. Also add
'StressSeed=N' option to specify the seed. If the seed is not specified, a
random one is generated. In either case, the seed is logged if 'LogCompilation'
is enabled. The new options are declared as production+diagnostic for
consistency with the existing 'StressLCM' and 'StressGCM' options.
Reviewed-by: kvn, chagedorn, thartmann
Remove unused notion of 'PhiNode-to-copy degradation', where PhiNodes can be
degraded to copies by setting their RegionNode to NULL. Remove corresponding
PhiNode::is_copy() test, which always returned NULL (false). Assert that
PhiNodes have an associated RegionNode in PhiNode::Ideal().
Reviewed-by: thartmann, kvn
8253238: [REDO] Improve object array chunking test in G1's copy_to_survivor_space
8253236: [REDO] Investigate fast-path for scanning only objects with references during gc
Generate multiple partial array tasks for large objArrays.
Reviewed-by: sjohanss, ayang, tschatzl
Add release fence to ClassValueMap constructor.
* Release fence guarantees that cacheArray field will published
with a non-null value.
* Without this fix, CacheValueMap.cacheArray can sometimes be
seen as null.
Reviewed-by: shade, psandoz
Remove the KILL_COMPILE_ON_FATAL_ and KILL_COMPILE_ON_ANY macros, replacing uses
of KILL_COMPILE_ON_FATAL_ with CHECK_AND_CLEAR_. Unlike KILL_COMPILE_ON_FATAL_,
CHECK_AND_CLEAR_ ignores ThreadDeath exceptions, which compiler threads should
not receive anyway.
Reviewed-by: vlivanov, neliasso
Revert "8027545: Improve object array chunking test in G1's copy_to_survivor_space"
Revert "8158045: Improve large object handling during evacuation"
Revert "8027761: Investigate fast-path for scanning only objects with references during gc"
Reviewed-by: tschatzl, sjohanss
8158045: Improve large object handling during evacuation
8027761: Investigate fast-path for scanning only objects with references during gc
Generate multiple partial array tasks for large objArrays.
Reviewed-by: sjohanss, ayang, tschatzl
Reimpliment PrimitiveConversions::cast, with some cases now constexpr.
<!-- Anything below this marker will be automatically updated, please do not edit manually! -->
---------
### Progress
- [x] Change must not contain extraneous whitespace
- [x] Commit message must refer to an issue
- [ ] Change must be properly reviewed
### Issue
* [JDK-8247909](https://bugs.openjdk.java.net/browse/JDK-8247909): Improve PrimitiveConversions::cast using C++14
### Download
`$ git fetch https://git.openjdk.java.net/jdk pull/143/head:pull/143`
`$ git checkout pull/143`
Reviewed-by: dholmes, stefank
Remove dead definition of ptr_type in TypeAryPtr::cast_to_autobox_cache. Also remove
unnecessary cache parameter (always true) for simplicity.
Reviewed-by: shade, vlivanov, thartmann
The comment is wrong. The 'us' in 'cpu.cfs_quota_us' stands for
microseconds, which is read verbatim. Similarly for cgroups v2
all units in 'cpu.max' are in microseconds.
Reviewed-by: shade, hseigel
Some CPUs (like ARM32) does not support unaligned memory accesses. To avoid JVM crashes tests that perform such accesses should be skipped on corresponding platforms.
Reviewed-by: iignatyev, clanger
Cleanup code for jlink classes generation, move parsing file work to java.lang.invoke and add a new API in interface JavaLangInvokeAccess to generate holder classes, remove old APIs. The new API is used both by JLI and CDS.
Reviewed-by: mchung, sundar
Remove @ignore since @requires os.maxMemory is enough to ensure tests will not be executed if memory requirements are not satisfied
Reviewed-by: coffeys
This patch adds a new flatmap-like operation called mapMulti to the java.util.Stream class as well as the primitive variations of this operation i.e. mapMultiToInt, IntStream mapMulti, etc.
Reviewed-by: psandoz, smarks
Call ClassLoaderDataGraph::loaded_cld_do to collect ClassLoaderData in a GrowableArray and then walk through them to link the classes in each ClassLoaderData.
Reviewed-by: coleenp, iklam
The JDK-specific API `jdk.net.Sockets` has been redundant since Java SE 9 added standard methods to get/set socket options and retrieve per-Socket supported options. This fix deprecates the class and its public methods.
Reviewed-by: chegar, dfuchs
Fix wrong replacement of loads by zero for non-completed InitializationNodes belonging to a clone when ReduceBulkZeroing is disabled.
Reviewed-by: kvn, thartmann
OOME seems to have happened in older version and does not show up in modern VM, hence the test OverloadCompileQueueTest.java gets un-quarantined.
Reviewed-by: iignatyev
Avoid inserting InstanceKlass into the DumpTimeSharedClassTable after dynamic CDS dumping has started. Acquire the DumpTimeTable_lock before iterations on _dumptime_table to ensure memory order correctness.
Reviewed-by: iklam, minqi
This fix changes the test to run with the new impl of DatagramSocket, which remedies the issue that caused the test to fail with a wrong expection and can now be taken off the ProblemList.
Reviewed-by: dfuchs
This fix updates `java/net/DatagramSocket/SendReceiveMaxSize.java` and `java/net/DatagramSocket/SendReceiveMaxSize.java` to check (on all platforms) that the sending/receiving of large datagrams across a network are sent, fragmented, and re-assembled correctly
Reviewed-by: alanb, dfuchs
The original change missed to update an assert.
Co-authored-by: Ludovic Henry <luhenry@microsoft.com>
Co-authored-by: Bernhard Urban-Forster <beurba@microsoft.com>
Reviewed-by: dholmes
The `test java/net/DatagramSocket/SendReceiveMaxSize` is currently failing when run with `-Djdk.net.usePlainDatagramSocketImpl` and `-Djava.net.preferIPv4Stack=true`. This fix removes these run settings from the test until a more permanent solution can be found.
Reviewed-by: dfuchs
This fix changes the current max size for IPv6 datagrams on macOS from it's current size of 65507, which is the IPv4 limit, to 65527, the actual limit for IPv6 on macOS
Reviewed-by: alanb, dfuchs, vtewari
This fix updates these tests to explicitly run with `-Djdk.net.usePlainDatagramSocketImpl=false` to avoid false failures when running all tests with a global jtreg -Djdk.net.usePlainDatagramSocketImpl switch.
Reviewed-by: vtewari
Release OopStorage oops for threadObj for exiting threads outside the service lock region that is marked as safe for safepoint.
Reviewed-by: zgu, dholmes, kbarrett
This fix addresses an issue where an AsynchronousCloseException was being thrown instead of a ChannelClosedException when SocketChannel.write() is called on a closed SocketChannel.
Reviewed-by: alanb, chegar, dfuchs
SO_RCVBUF was previously set to match the SO_SNDBUF, however the kernel value for SO_RCVBUF is much larger. This mismatch caused the test to fail, and the fix removes this issue.
Reviewed-by: alanb, dfuchs
Move recent timestamp of most recent whole heap liveness analysis into CollectedHeap, removing the duplicates in all collectors
Reviewed-by: kbarrett, ayang, stefank
SocketTube is fixed to cater for errors caused by pausing/resuming events on an asynchronously closed connection, from within the selector's manager thread. Http2Connection and Stream are fixed to prevent sending a DataFrame on a stream after Reset has been sent.
Reviewed-by: chegar
TransportImpl is modified to make sure the CLOSED state is recorded before the channel is closed. The tests are modified to enable their retry mechanism on windows, similar to what was done previously for macOS.
Reviewed-by: prappo, chegar
Move the oop and handle releasing it in the service thread. Remove Universe::oops_do from callers.
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Tom Rodriguez <tom.rodriguez@oracle.com>
Reviewed-by: dholmes, zgu, eosterlund, cjplummer
OopStorage instance now owned by subsystems, and generalize dead entry notification
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Stefan Karlsson <stefan.karlsson@oracle.com>
Reviewed-by: coleenp, tschatzl
8237743: test/langtools/jdk/jshell/FailOverExecutionControlTest.java fails No ExecutionControlProvider with name 'nonExistent' and parameter keys: []
8199646: JShell tests: jdk/jshell/FailOverDirectExecutionControlTest.java failed with java.lang.UnsupportedOperationException
Reviewed-by: jlahoda
Implement parallel processing of strong OopStorage entries for G1.
Co-authored-by: Erik Osterlund <erik.osterlund@oracle.com>
Co-authored-by: Stefan Karlsson <stefan.karlsson@oracle.com>
Reviewed-by: kbarrett, stefank
Change CC_INTERP conditional to ZERO and remove in places where unnecessary. Fix build to exclude compilers and rename CppInterpreter to ZeroInterpreter. The "C++ Interpreter" has been removed from the code a while ago.
Reviewed-by: dholmes, ihse
Bail out in PhaseIdealLoop:split_thru_phi when trying to split a Div or ModNode iv phi whose zero check was removed but could potentially still be zero based on type information.
Reviewed-by: kvn, thartmann
The fix updates sun.net.httpserver.ExchangeImpl to use thread safe DateTimeFormatter for response headers, this replaces DateFormat that was using ThreadLocal.
Reviewed-by: dfuchs, alanb, chegar
This patch updates the @modules tag with +open in the tests UnreferencedDatagramSockets and UnreferncedMulticastSockets in advance of the removal of --illegal-access to allow access to private member fields required by the tests.
Reviewed-by: alanb, dfuchs
8245585: Add SourceVersion.RELEASE_16
8245586: Add source 16 and target 16 to javac
8245544: com/sun/tools/javac/platform/JDKPlatformProvider.java does not support ct.sym with platform versions 16+
Co-authored-by: David Holmes <david.holmes@oracle.com>
Co-authored-by: Jan Lahoda <jan.lahoda@oracle.com>
Reviewed-by: erikj, dholmes, ihse, neugens, jjg, jlahoda, jlaskey, mikael
<p>Please consult the AIX section of the <ahref="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a> OpenJDK Build Wiki page for details about which versions of AIX are supported.</p>
<tdstyle="text-align: left;">Microsoft Visual Studio 2019 update 16.5.3</td>
<tdstyle="text-align: left;">Microsoft Visual Studio 2019 update 16.7.2</td>
</tr>
</tbody>
</table>
<p>All compilers are expected to be able to compile to the C99 language standard, as some C99 features are used in the source code. Microsoft Visual Studio doesn't fully support C99 so in practice shared code is limited to using C99 features that it does support.</p>
<h3id="gcc">gcc</h3>
<p>The minimum accepted version of gcc is 5.0. Older versions will generate a warning by <code>configure</code> and are unlikely to work.</p>
<p>The JDK is currently known to be able to compile with at least version 9.2 of gcc.</p>
<p>The JDK is currently known to be able to compile with at least version 10.2 of gcc.</p>
<p>In general, any version between these two should be usable.</p>
<h3id="clang">clang</h3>
<p>The minimum accepted version of clang is 3.2. Older versions will not be accepted by <code>configure</code>.</p>
<p>The minimum accepted version of clang is 3.5. Older versions will not be accepted by <code>configure</code>.</p>
<p>To use clang instead of gcc on Linux, use <code>--with-toolchain-type=clang</code>.</p>
<h3id="apple-xcode">Apple Xcode</h3>
<p>The oldest supported version of Xcode is 8.</p>
@@ -292,9 +295,8 @@
<p>It is advisable to keep an older version of Xcode for building the JDK when updating Xcode. This <ahref="http://iosdevelopertips.com/xcode/install-multiple-versions-of-xcode.html">blog page</a> has good suggestions on managing multiple Xcode versions. To use a specific version of Xcode, use <code>xcode-select -s</code> before running <code>configure</code>, or use <code>--with-toolchain-path</code> to point to the version of Xcode to use, e.g. <code>configure --with-toolchain-path=/Applications/Xcode8.app/Contents/Developer/usr/bin</code></p>
<p>If you have recently (inadvertently) updated your OS and/or Xcode version, and the JDK can no longer be built, please see the section on <ahref="#problems-with-the-build-environment">Problems with the Build Environment</a>, and <ahref="#getting-help">Getting Help</a> to find out if there are any recent, non-merged patches available for this update.</p>
<p>The minimum accepted version of Visual Studio is 2010. Older versions will not be accepted by <code>configure</code>. The maximum accepted version of Visual Studio is 2019. Versions older than 2017 are unlikely to continue working for long.</p>
<p>If you have multiple versions of Visual Studio installed, <code>configure</code> will by default pick the latest. You can request a specific version to be used by setting <code>--with-toolchain-version</code>, e.g. <code>--with-toolchain-version=2015</code>.</p>
<p>If you get <code>LINK: fatal error LNK1123: failure during conversion to COFF: file invalid</code> when building using Visual Studio 2010, you have encountered <ahref="http://support.microsoft.com/kb/2757355">KB2757355</a>, a bug triggered by a specific installation order. However, the solution suggested by the KB article does not always resolve the problem. See <ahref="https://stackoverflow.com/questions/10888391">this stackoverflow discussion</a> for other suggestions.</p>
<p>The minimum accepted version of Visual Studio is 2017. Older versions will not be accepted by <code>configure</code> and will not work. The maximum accepted version of Visual Studio is 2019.</p>
<p>If you have multiple versions of Visual Studio installed, <code>configure</code> will by default pick the latest. You can request a specific version to be used by setting <code>--with-toolchain-version</code>, e.g. <code>--with-toolchain-version=2017</code>.</p>
<h3id="ibm-xl-cc">IBM XL C/C++</h3>
<p>Please consult the AIX section of the <ahref="https://wiki.openjdk.java.net/display/Build/Supported+Build+Platforms">Supported Build Platforms</a> OpenJDK Build Wiki page for details about which versions of XLC are supported.</p>
<p>Use <code>--with-freetype-include=<path></code> and <code>--with-freetype-lib=<path></code> if <code>configure</code> does not automatically locate the platform FreeType files.</p>
<h3id="cups">CUPS</h3>
@@ -321,6 +324,7 @@
<ul>
<li>To install on an apt-based Linux, try running <code>sudo apt-get install libcups2-dev</code>.</li>
<li>To install on an rpm-based Linux, try running <code>sudo yum install cups-devel</code>.</li>
<li>To install on macOS, try running <code>brew install autoconf</code>.</li>
<li>To install on Windows, try running <code><path to Cygwin setup>/setup-x86_64 -q -P autoconf</code>.</li>
</ul>
@@ -689,6 +697,15 @@ ls build/linux-aarch64-normal-server-release/</code></pre>
<p>Additional architectures might be supported by Debian/Ubuntu Ports.</p>
<h3id="building-for-armaarch64">Building for ARM/aarch64</h3>
<p>A common cross-compilation target is the ARM CPU. When building for ARM, it is useful to set the ABI profile. A number of pre-defined ABI profiles are available using <code>--with-abi-profile</code>: arm-vfp-sflt, arm-vfp-hflt, arm-sflt, armv5-vfp-sflt, armv6-vfp-hflt. Note that soft-float ABIs are no longer properly supported by the JDK.</p>
<h3id="building-for-musl">Building for musl</h3>
<p>Just like it's possible to cross-compile for a different CPU, it's possible to cross-compile for musl libc on a glibc-based <em>build</em> system. A devkit suitable for most target CPU architectures can be obtained from <ahref="https://musl.cc">musl.cc</a>. After installing the required packages in the sysroot, configure the build with <code>--openjdk-target</code>:</p>
<p>This is a collection of rules, guidelines, and suggestions for writing HotSpot code. Following these will help new code fit in with existing HotSpot code, making it easier to read and maintain. Failure to follow these guidelines may lead to discussion during code reviews, if not outright rejection of a change.</p>
<h3id="why-care-about-style">Why Care About Style?</h3>
<p>Some programmers seem to have lexers and even C preprocessors installed directly behind their eyeballs. The rest of us require code that is not only functionally correct but also easy to read. More than that, since there is no one style for easy-to-read code, and since a mashup of many styles is just as confusing as no style at all, it is important for coders to be conscious of the many implicit stylistic choices that historically have gone into the HotSpot code base.</p>
<p>Some of these guidelines are driven by the cross-platform requirements for HotSpot. Shared code must work on a variety of platforms, and may encounter deficiencies in some. Using platform conditionalization in shared code is usually avoided, while shared code is strongly preferred to multiple platform-dependent implementations, so some language features may be recommended against.</p>
<p>Some of the guidelines here are relatively arbitrary choices among equally plausible alternatives. The purpose of stating and enforcing these rules is largely to provide a consistent look to the code. That consistency makes the code more readable by avoiding non-functional distractions from the interesting functionality.</p>
<p>When changing pre-existing code, it is reasonable to adjust it to match these conventions. Exception: If the pre-existing code clearly conforms locally to its own peculiar conventions, it is not worth reformatting the whole thing. Also consider separating changes that make extensive stylistic updates from those which make functional changes.</p>
<h3id="counterexamples-and-updates">Counterexamples and Updates</h3>
<p>Many of the guidelines mentioned here have (sometimes widespread) counterexamples in the HotSpot code base. Finding a counterexample is not sufficient justification for new code to follow the counterexample as a precedent, since readers of your code will rightfully expect your code to follow the greater bulk of precedents documented here.</p>
<p>Occasionally a guideline mentioned here may be just out of synch with the actual HotSpot code base. If you find that a guideline is consistently contradicted by a large number of counterexamples, please bring it up for discussion and possible change. The architectural rule, of course, is "When in Rome do as the Romans". Sometimes in the suburbs of Rome the rules are a little different; these differences can be pointed out here.</p>
<p>Proposed changes should be discussed on the <ahref="mailto:hotspot-dev@openjdk.java.net">HotSpot Developers</a> mailing list, and approved by <ahref="https://en.wikipedia.org/wiki/Rough_consensus">rough consensus</a> of the <ahref="https://openjdk.java.net/census#hotspot">HotSpot Group</a> Members. The Group Lead determines whether consensus has been reached. Changes are likely to be cautious and incremental, since HotSpot coders have been using these guidelines for years.</p>
<h2id="structure-and-formatting">Structure and Formatting</h2>
<h3id="factoring-and-class-design">Factoring and Class Design</h3>
<ul>
<li><p>Group related code together, so readers can concentrate on one section of one file.</p></li>
<li><p>Classes are the primary code structuring mechanism. Place related functionality in a class, or a set of related classes. Use of either namespaces or public non-member functions is rare in HotSpot code. Static non-member functions are not uncommon.</p></li>
<li><p>If a class <code>FooBar</code> is going to be used in more than one place, put it a file named fooBar.hpp and fooBar.cpp. If the class is a sidekick to a more important class <code>BazBat</code>, it can go in bazBat.hpp.</p></li>
<li><p>Put a member function <code>FooBar::bang</code> into the same file that defined <code>FooBar</code>, or its associated <em>.inline.hpp or </em>.cpp file.</p></li>
<li><p>Use public accessor functions for member variables accessed outside the class.</p></li>
<li><p>Assign names to constant literals and use the names instead.</p></li>
<li><p>Keep functions small, a screenful at most. Split out chunks of logic into file-local classes or static functions if needed.</p></li>
<li><p>Factor away nonessential complexity into local inline helper functions and helper classes.</p></li>
<li><p>Think clearly about internal invariants that apply to each class, and document them in the form of asserts within member functions.</p></li>
<li><p>Make simple, self-evident contracts for member functions. If you cannot communicate a simple contract, redesign the class.</p></li>
<li><p>Implement classes as if expecting rough usage by clients. Check for incorrect usage of a class using <code>assert(...)</code>, <code>guarantee(...)</code>, <code>ShouldNotReachHere()</code> and comments wherever needed. Performance is almost never a reason to omit asserts.</p></li>
<li><p>When possible, design as if for reusability. This forces a clear design of the class's externals, and clean hiding of its internals.</p></li>
<li><p>Initialize all variables and data structures to a known state. If a class has a constructor, initialize it there.</p></li>
<li><p>Do no optimization before its time. Prove the need to optimize.</p></li>
<li><p>When you must defactor to optimize, preserve as much structure as possible. If you must hand-inline some name, label the local copy with the original name.</p></li>
<li><p>If you need to use a hidden detail (e.g., a structure offset), name it (as a constant or function) in the class that owns it.</p></li>
<li><p>Don't use the Copy and Paste keys to replicate more than a couple lines of code. Name what you must repeat.</p></li>
<li><p>If a class needs a member function to change a user-visible attribute, the change should be done with a "setter" accessor matched to the simple "getter".</p></li>
</ul>
<h3id="source-files">Source Files</h3>
<ul>
<li><p>All source files must have a globally unique basename. The build system depends on this uniqueness.</p></li>
<li><p>Do not put non-trivial function implementations in .hpp files. If the implementation depends on other .hpp files, put it in a .cpp or a .inline.hpp file.</p></li>
<li><p>.inline.hpp files should only be included in .cpp or .inline.hpp files.</p></li>
<li><p>All .cpp files include precompiled.hpp as the first include line.</p></li>
<li><p>precompiled.hpp is just a build time optimization, so don't rely on it to resolve include problems.</p></li>
<li><p>Keep the include lines alphabetically sorted.</p></li>
<li><p>Put conditional inclusions (<code>#if ...</code>) at the end of the include list.</p></li>
</ul>
<h3id="jtreg-tests">JTReg Tests</h3>
<ul>
<li><p>JTReg tests should have meaningful names.</p></li>
<li><p>JTReg tests associated with specific bugs should be tagged with the <code>@bug</code> keyword in the test description.</p></li>
<li><p>JTReg tests should be organized by component or feature under <code>test/</code>, in a directory hierarchy that generally follows that of the <code>src/</code> directory. There may be additional subdirectories to further categorize tests by feature. This structure makes it easy to run a collection of tests associated with a specific feature by specifying the associated directory as the source of the tests to run.</p>
<ul>
<li>Some (older) tests use the associated bug number in the directory name, the test name, or both. That naming style should no longer be used, with existing tests using that style being candidates for migration.</li>
</ul></li>
</ul>
<h3id="naming">Naming</h3>
<ul>
<li><p>The length of a name may be correlated to the size of its scope. In particular, short names (even single letter names) may be fine in a small scope, but are usually inappropriate for larger scopes.</p></li>
<li><p>Prefer whole words rather than abbreviations, unless the abbreviation is more widely used than the long form in the code's domain.</p></li>
<li><p>Choose names consistently. Do not introduce spurious variations. Abbreviate corresponding terms to a consistent length.</p></li>
<li><p>Global names must be unique, to avoid <ahref="https://en.cppreference.com/w/cpp/language/definition"title="One Definition Rule">One Definition Rule</a> (ODR) violations. A common prefixing scheme for related global names is often used. (This is instead of using namespaces, which are mostly avoided in HotSpot.)</p></li>
<li><p>Don't give two names to the semantically same thing. But use different names for semantically different things, even if they are representationally the same. (So use meaningful <code>typedef</code> or template alias names where appropriate.)</p></li>
<li><p>When choosing names, avoid categorical nouns like "variable", "field", "parameter", "value", and verbs like "compute", "get". (<code>storeValue(int param)</code> is bad.)</p></li>
<li><p>Type names and global names should use mixed-case with the first letter of each word capitalized (<code>FooBar</code>).</p></li>
<li><p>Embedded abbreviations in otherwise mixed-case names are usually capitalized entirely rather than being treated as a single word with only the initial letter capitalized, e.g. "HTML" rather than "Html".</p></li>
<li><p>Function and local variable names use lowercase with words separated by a single underscore (<code>foo_bar</code>).</p></li>
<li><p>Class data member names have a leading underscore, and use lowercase with words separated by a single underscore (<code>_foo_bar</code>).</p></li>
<li><p>Constant names may be upper-case or mixed-case, according to historical necessity. (Note: There are many examples of constants with lowercase names.)</p></li>
<li><p>Constant names should follow an existing pattern, and must have a distinct appearance from other names in related APIs.</p></li>
<li><p>Class and type names should be noun phrases. Consider an "er" suffix for a class that represents an action.</p></li>
<li><p>Function names should be verb phrases that reflect changes of state known to a class's user, or else noun phrases if they cause no change of state visible to the class's user.</p></li>
<li><p>Getter accessor names are noun phrases, with no "<code>get_</code>" noise word. Boolean getters can also begin with "<code>is_</code>" or "<code>has_</code>". Member function for reading data members usually have the same name as the data member, exclusive of the leading underscore.</p></li>
<li><p>Setter accessor names prepend "<code>set_</code>" to the getter name.</p></li>
<li><p>Other member function names are verb phrases, as if commands to the receiver.</p></li>
<li><p>Avoid leading underscores (as "<code>_oop</code>") except in cases required above. (Names with leading underscores can cause portability problems.)</p></li>
</ul>
<h3id="commenting">Commenting</h3>
<ul>
<li><p>Clearly comment subtle fixes.</p></li>
<li><p>Clearly comment tricky classes and functions.</p></li>
<li><p>If you have to choose between commenting code and writing wiki content, comment the code. Link from the wiki to the source file if it makes sense.</p></li>
<li><p>As a general rule don't add bug numbers to comments (they would soon overwhelm the code). But if the bug report contains significant information that can't reasonably be added as a comment, then refer to the bug report.</p></li>
<li><p>Personal names are discouraged in the source code, which is a team product.</p></li>
</ul>
<h3id="macros">Macros</h3>
<ul>
<li><p>You can almost always use an inline function or class instead of a macro. Use a macro only when you really need it.</p></li>
<li><p>Templates may be preferable to multi-line macros. (There may be subtle performance effects with templates on some platforms; revert to macros if absolutely necessary.)</p></li>
<li><p><code>#ifdef</code>s should not be used to introduce platform-specific code into shared code (except for <code>_LP64</code>). They must be used to manage header files, in the pattern found at the top of every source file. They should be used mainly for major build features, including <code>PRODUCT</code>, <code>ASSERT</code>, <code>_LP64</code>, <code>INCLUDE_SERIALGC</code>, <code>COMPILER1</code>, etc.</p></li>
<li><p>For build features such as <code>PRODUCT</code>, use <code>#ifdef PRODUCT</code> for multiple-line inclusions or exclusions.</p></li>
<li><p>For short inclusions or exclusions based on build features, use macros like <code>PRODUCT_ONLY</code> and <code>NOT_PRODUCT</code>. But avoid using them with multiple-line arguments, since debuggers do not handle that well.</p></li>
<li><p>Use <code>CATCH</code>, <code>THROW</code>, etc. for HotSpot-specific exception processing.</p></li>
</ul>
<h3id="whitespace">Whitespace</h3>
<ul>
<li><p>In general, don't change whitespace unless it improves readability or consistency. Gratuitous whitespace changes will make integrations and backports more difficult.</p></li>
<li><p>Use One-True-Brace-Style. The opening brace for a function or class is normally at the end of the line; it is sometimes moved to the beginning of the next line for emphasis. Substatements are enclosed in braces, even if there is only a single statement. Extremely simple one-line statements may drop braces around a substatement.</p></li>
<li><p>Indentation levels are two columns.</p></li>
<li><p>There is no hard line length limit. That said, bear in mind that excessively long lines can cause difficulties. Some people like to have multiple side-by-side windows in their editors, and long lines may force them to choose among unpleasant options. They can use wide windows, reducing the number that can fit across the screen, and wasting a lot of screen real estate because most lines are not that long. Alternatively, they can have more windows across the screen, with long lines wrapping (or worse, requiring scrolling to see in their entirety), which is harder to read. Similar issues exist for side-by-side code reviews.</p></li>
<li><p>Tabs are not allowed in code. Set your editor accordingly.<br> (Emacs: <code>(setq-default indent-tabs-mode nil)</code>.)</p></li>
<li><p>Use good taste to break lines and align corresponding tokens on adjacent lines.</p></li>
<li><p>Use spaces around operators, especially comparisons and assignments. (Relaxable for boolean expressions and high-precedence operators in classic math-style formulas.)</p></li>
<li><p>Put spaces on both sides of control flow keywords <code>if</code>, <code>else</code>, <code>for</code>, <code>switch</code>, etc. Don't add spaces around the associated <em>control</em> expressions. Examples:</p>
<pre><code>while (test_foo(args...)) { // Yes
while(test_foo(args...)) { // No, missing space after while
while ( test_foo(args...) ) { // No, excess spaces around control</code></pre></li>
<li><p>Use extra parentheses in expressions whenever operator precedence seems doubtful. Always use parentheses in shift/mask expressions (<code><<</code>, <code>&</code>, <code>|</code>). Don't add whitespace immediately inside parentheses.</p></li>
<li><p>Use more spaces and blank lines between larger constructs, such as classes or function definitions.</p></li>
<li><p>If the surrounding code has any sort of vertical organization, adjust new lines horizontally to be consistent with that organization. (E.g., trailing backslashes on long macro definitions often align.)</p></li>
</ul>
<h3id="miscellaneous">Miscellaneous</h3>
<ul>
<li><p>Use the <ahref="https://en.cppreference.com/w/cpp/language/raii"title="Resource Acquisition Is Initialization">Resource Acquisition Is Initialization</a> (RAII) design pattern to manage bracketed critical sections. See class <code>ResourceMark</code> for an example.</p></li>
<li>Avoid implicit conversions to <code>bool</code>.
<ul>
<li>Use <code>bool</code> for boolean values.</li>
<li>Do not use ints or pointers as (implicit) booleans with <code>&&</code>, <code>||</code>, <code>if</code>, <code>while</code>. Instead, compare explicitly, i.e. <code>if (x != 0)</code> or <code>if (ptr != nullptr)</code>, etc.</li>
<li>Do not use declarations in <em>condition</em> forms, i.e. don't use <code>if (T v = value) { ... }</code>.</li>
</ul></li>
<li><p>Use functions from globalDefinitions.hpp and related files when performing bitwise operations on integers. Do not code directly as C operators, unless they are extremely simple. (Examples: <code>align_up</code>, <code>is_power_of_2</code>, <code>exact_log2</code>.)</p></li>
<li><p>Use arrays with abstractions supporting range checks.</p></li>
<li><p>Always enumerate all cases in a switch statement or provide a default case. It is ok to have an empty default with comment.</p></li>
</ul>
<h2id="use-of-c-features">Use of C++ Features</h2>
<p>HotSpot was originally written in a subset of the C++98/03 language. More recently, support for C++14 is provided, though again, HotSpot only uses a subset. (Backports to JDK versions lacking support for more recent Standards must of course stick with the original C++98/03 subset.)</p>
<p>This section describes that subset. Features from the C++98/03 language may be used unless explicitly excluded here. Features from C++11 and C++14 may be explicitly permitted or explicitly excluded, and discussed accordingly here. There is a third category, undecided features, about which HotSpot developers have not yet reached a consensus, or perhaps have not discussed at all. Use of these features is also excluded.</p>
<p>(The use of some features may not be immediately obvious and may slip in anyway, since the compiler will accept them. The code review process is the main defense against this.)</p>
<p>Some features are discussed in their own subsection, typically to provide more extensive discussion or rationale for limitations. Features that don't have their own subsection are listed in omnibus feature sections for permitted, excluded, and undecided features.</p>
<p>Lists of new features for C++11 and C++14, along with links to their descriptions, can be found in the online documentation for some of the compilers and libraries. The C++14 Standard is the definitive description.</p>
<ul>
<li><ahref="https://gcc.gnu.org/projects/cxx-status.html">C++ Standards Support in GCC</a></li>
<li><ahref="https://clang.llvm.org/cxx_status.html">C++ Support in Clang</a></li>
<li><ahref="https://docs.microsoft.com/en-us/cpp/visual-cpp-language-conformance">Visual C++ Language Conformance</a></li>
<p>As a rule of thumb, permitting features which simplify writing code and, especially, reading code, is encouraged.</p>
<p>Similar discussions for some other projects:</p>
<ul>
<li><p><ahref="https://google.github.io/styleguide/cppguide.html">Google C++ Style Guide</a> — Currently (2020) targeting C++17.</p></li>
<li><p><ahref="https://chromium-cpp.appspot.com">C++11 and C++14 use in Chromium</a> — Categorizes features as allowed, banned, or to be discussed.</p></li>
<li><p><ahref="https://llvm.org/docs/CodingStandards.html">llvm Coding Standards</a> — Currently (2020) targeting C++14.</p></li>
<li><p><ahref="https://firefox-source-docs.mozilla.org/code-quality/coding-style/using_cxx_in_firefox_code.html">Using C++ in Mozilla code</a> — C++17 support is required for recent versions (2020).</p></li>
</ul>
<h3id="error-handling">Error Handling</h3>
<p>Do not use exceptions. Exceptions are disabled by the build configuration for some platforms.</p>
<p>Rationale: There is significant concern over the performance cost of exceptions and their usage model and implications for maintainable code. That's not just a matter of history that has been fixed; there remain questions and problems even today (2019). See, for example, <ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0709r0.pdf">Zero cost deterministic exceptions</a>. Because of this, HotSpot has always used a build configuration that disables exceptions where that is available. As a result, HotSpot code uses error handling mechanisms such as two-phase construction, factory functions, returning error codes, and immediate termination. Even if the cost of exceptions were not a concern, the existing body of code was not written with exception safety in mind. Making HotSpot exception safe would be a very large undertaking.</p>
<p>In addition to the usual alternatives to exceptions, HotSpot provides its own exception mechanism. This is based on a set of macros defined in utilities/exceptions.hpp.</p>
<h3id="rtti-runtime-type-information">RTTI (Runtime Type Information)</h3>
<p>Do not use <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">Runtime Type Information</a> (RTTI). <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> is disabled by the build configuration for some platforms. Among other things, this means <code>dynamic_cast</code> cannot be used.</p>
<p>Rationale: Other than to implement exceptions (which HotSpot doesn't use), most potential uses of <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> are better done via virtual functions. Some of the remainder can be replaced by bespoke mechanisms. The cost of the additional runtime data structures needed to support <ahref="https://en.wikipedia.org/wiki/Run-time_type_information"title="Runtime Type Information">RTTI</a> are deemed not worthwhile, given the alternatives.</p>
<h3id="memory-allocation">Memory Allocation</h3>
<p>Do not use the standard global allocation and deallocation functions (operator new and related functions). Use of these functions by HotSpot code is disabled for some platforms.</p>
<p>Rationale: HotSpot often uses "resource" or "arena" allocation. Even where heap allocation is used, the standard global functions are avoided in favor of wrappers around malloc and free that support the VM's Native Memory Tracking (NMT) feature.</p>
<p>Native memory allocation failures are often treated as non-recoverable. The place where "out of memory" is (first) detected may be an innocent bystander, unrelated to the actual culprit.</p>
<h3id="class-inheritance">Class Inheritance</h3>
<p>Use public single inheritance.</p>
<p>Prefer composition rather than non-public inheritance.</p>
<p>Restrict inheritance to the "is-a" case; use composition rather than non-is-a related inheritance.</p>
<p>Avoid multiple inheritance. Never use virtual inheritance.</p>
<h3id="namespaces">Namespaces</h3>
<p>Avoid using namespaces. HotSpot code normally uses "all static" classes rather than namespaces for grouping. An "all static" class is not instantiable, has only static members, and is normally derived (possibly indirectly) from the helper class <code>AllStatic</code>.</p>
<p>Benefits of using such classes include:</p>
<ul>
<li><p>Provides access control for members, which is unavailable with namespaces.</p></li>
<li><p>Closed for additional members. Namespaces allow names to be added in multiple contexts, making it harder to see the complete API.</p></li>
</ul>
<p>Namespaces should be used only in cases where one of those "benefits" is actually a hindrance.</p>
<p>In particular, don't use anonymous namespaces. They seem like they should be useful, and indeed have some real benefits for naming and generated code size on some platforms. Unfortunately, debuggers don't seem to like them at all.</p>
<p><ahref="https://groups.google.com/forum/#!topic/mozilla.dev.platform/KsaG3lEEaRM"class="uri">https://groups.google.com/forum/#!topic/mozilla.dev.platform/KsaG3lEEaRM</a><br> Suggests Visual Studio debugger might not be able to refer to anonymous namespace symbols, so can't set breakpoints in them. Though the discussion seems to go back and forth on that.</p>
<p><ahref="https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html"class="uri">https://firefox-source-docs.mozilla.org/code-quality/coding-style/coding_style_cpp.html</a><br> Search for "Anonymous namespaces" Suggests preferring "static" to anonymous namespaces where applicable, because of poor debugger support for anonymous namespaces.</p>
<p><ahref="https://sourceware.org/bugzilla/show_bug.cgi?id=16874"class="uri">https://sourceware.org/bugzilla/show_bug.cgi?id=16874</a><br> Bug for similar gdb problems.</p>
<h3id="c-standard-library">C++ Standard Library</h3>
<p>Avoid using the C++ Standard Library.</p>
<p>Historically, HotSpot has mostly avoided use of the Standard Library.</p>
<p>(It used to be impossible to use most of it in shared code, because the build configuration for Solaris with Solaris Studio made all but a couple of pieces inaccessible. Support for header-only parts was added in mid-2017. Support for Solaris was removed in 2020.)</p>
<p>Some reasons for this include</p>
<ul>
<li><p>Exceptions. Perhaps the largest core issue with adopting the use of Standard Library facilities is exceptions. HotSpot does not use exceptions and, for platforms which allow doing so, builds with them turned off. Many Standard Library facilities implicitly or explicitly use exceptions.</p></li>
<li><p><code>assert</code>. An issue that is quickly encountered is the <code>assert</code> macro name collision (<ahref="https://bugs.openjdk.java.net/browse/JDK-8007770">JDK-8007770</a>). Some mechanism for addressing this would be needed before much of the Standard Library could be used. (Not all Standard Library implementations use assert in header files, but some do.)</p></li>
<li><p>Memory allocation. HotSpot requires explicit control over where allocations occur. The C++98/03 <code>std::allocator</code> class is too limited to support our usage. (Changes in more recent Standards may remove this limitation.)</p></li>
<li><p>Implementation vagaries. Bugs, or simply different implementation choices, can lead to different behaviors among the various Standard Libraries we need to deal with.</p></li>
<li><p>Inconsistent naming conventions. HotSpot and the C++ Standard use different naming conventions. The coexistence of those different conventions might appear jarring and reduce readability.</p></li>
</ul>
<p>There are a few exceptions to this rule.</p>
<ul>
<li><code>#include <new></code> to use placement <code>new</code>, <code>std::nothrow</code>, and <code>std::nothrow_t</code>.</li>
<li><code>#include <limits></code> to use <code>std::numeric_limits</code>.</li>
<li><code>#include <cstddef></code> to use <code>std::nullptr_t</code>.</li>
</ul>
<p>TODO: Rather than directly #including (permitted) Standard Library headers, use a convention of #including wrapper headers (in some location like hotspot/shared/stdcpp). This provides a single place for dealing with issues we might have for any given header, esp. platform-specific issues.</p>
<h3id="type-deduction">Type Deduction</h3>
<p>Use type deduction only if it makes the code clearer or safer. Do not use it merely to avoid the inconvenience of writing an explicit type, unless that type is itself difficult to write. An example of the latter is a function template return type that depends on template parameters in a non-trivial way.</p>
<p>There are several contexts where types are deduced.</p>
<ul>
<li><p>Function argument deduction. This is always permitted, and indeed encouraged. It is nearly always better to allow the type of a function template argument to be deduced rather than explicitly specified.</p></li>
<li><p><code>auto</code> variable declarations (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf">n1984</a>)<br> For local variables, this can be used to make the code clearer by eliminating type information that is obvious or irrelevant. Excessive use can make code much harder to understand.</p></li>
<li><p>Function return type deduction (<ahref="https://isocpp.org/files/papers/N3638.html">n3638</a>)<br> Only use if the function body has a very small number of <code>return</code> statements, and generally relatively little other code.</p></li>
<li><p>Generic lambdas. Lambdas are not (yet) permitted.</p></li>
<li><p>Lambda init captures. Lambdas are not (yet) permitted.</p></li>
</ul>
<h3id="expression-sfinae">Expression SFINAE</h3>
<p><ahref="https://en.cppreference.com/w/cpp/language/sfinae"title="Substitution Failure Is Not An Error">Substitution Failure Is Not An Error</a> (SFINAE) is a template metaprogramming technique that makes use of template parameter substitution failures to make compile-time decisions.</p>
<p>C++11 relaxed the rules for what constitutes a hard-error when attempting to substitute template parameters with template arguments, making most deduction errors be substitution errors; see (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2634.html">n2634</a>). This makes <ahref="https://en.cppreference.com/w/cpp/language/sfinae"title="Substitution Failure Is Not An Error">SFINAE</a> more powerful and easier to use. However, the implementation complexity for this change is significant, and this seems to be a place where obscure corner-case bugs in various compilers can be found. So while this feature can (and indeed should) be used (and would be difficult to avoid), caution should be used when pushing to extremes.</p>
<p>Here are a few closely related example bugs:<br><ahref="https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95468"class="uri">https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95468</a><br><ahref="https://developercommunity.visualstudio.com/content/problem/396562/sizeof-deduced-type-is-sometimes-not-a-constant-ex.html"class="uri">https://developercommunity.visualstudio.com/content/problem/396562/sizeof-deduced-type-is-sometimes-not-a-constant-ex.html</a></p>
<h3id="enum">enum</h3>
<p>Where appropriate, <em>scoped-enums</em> should be used. (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2347.pdf">n2347</a>)</p>
<p>Use of <em>unscoped-enums</em> is permitted, though ordinary constants may be preferable when the automatic initializer feature isn't used.</p>
<p>The underlying type (the <em>enum-base</em>) of an unscoped enum type should always be specified explicitly. When unspecified, the underlying type is dependent on the range of the enumerator values and the platform.</p>
<p>The underlying type of a <em>scoped-enum</em> should also be specified explicitly if conversions may be applied to values of that type.</p>
<p>Due to bugs in certain (very old) compilers, there is widespread use of enums and avoidance of in-class initialization of static integral constant members. Compilers having such bugs are no longer supported. Except where an enum is semantically appropriate, new code should use integral constants.</p>
<h3id="thread_local">thread_local</h3>
<p>Do not use <code>thread_local</code> (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2659.htm">n2659</a>); instead, use the HotSpot macro <code>THREAD_LOCAL</code>. The initializer must be a constant expression.</p>
<p>As was discussed in the review for <ahref="https://mail.openjdk.java.net/pipermail/hotspot-dev/2019-September/039487.html">JDK-8230877</a>, <code>thread_local</code> allows dynamic initialization and destruction semantics. However, that support requires a run-time penalty for references to non-function-local <code>thread_local</code> variables defined in a different translation unit, even if they don't need dynamic initialization. Dynamic initialization and destruction of namespace-scoped thread local variables also has the same ordering problems as for ordinary namespace-scoped variables.</p>
<h3id="nullptr">nullptr</h3>
<p>Prefer <code>nullptr</code> (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2431.pdf">n2431</a>) to <code>NULL</code>. Don't use (constexpr or literal) 0 for pointers.</p>
<p>For historical reasons there are widespread uses of both <code>NULL</code> and of integer 0 as a pointer value.</p>
<h3id="atomic"><atomic></h3>
<p>Do not use facilities provided by the <code><atomic></code> header (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2427.html">n2427</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2752.htm">n2752</a>); instead, use the HotSpot <code>Atomic</code> class and related facilities.</p>
<p>Atomic operations in HotSpot code must have semantics which are consistent with those provided by the JDK's compilers for Java. There are platform-specific implementation choices that a C++ compiler might make or change that are outside the scope of the C++ Standard, and might differ from what the Java compilers implement.</p>
<p>In addition, HotSpot <code>Atomic</code> has a concept of "conservative" memory ordering, which may differ from (may be stronger than) sequentially consistent. There are algorithms in HotSpot that are believed to rely on that ordering.</p>
<li><p>Default template arguments for function templates (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#226">CWG D226</a>)</p></li>
<li><p>Defaulted and deleted functions (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2346.htm">n2346</a>)</p></li>
<li><p>Dynamic initialization and destruction with concurrency (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2660.htm">n2660</a>)</p></li>
<li><p><code>final</code> virtual specifiers for classes and virtual functions (<ahref="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2009/n2928.htm">n2928</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3206.htm">n3206</a>), (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2011/n3272.htm">n3272</a>)</p></li>
<li><p>Local and unnamed types as template parameters (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2657.htm">n2657</a>)</p></li>
</ul>
<h3id="excluded-features">Excluded Features</h3>
<ul>
<li>New string and character literals
<ul>
<li>New character types (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2249.html">n2249</a>)</li>
<li>Universal character name literals (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2170.html">n2170</a>)</li>
</ul>
<p>HotSpot doesn't need any of the new character and string literal types.</p></li>
<li><p>User-defined literals (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2765.pdf">n2765</a>) — User-defined literals should not be added casually, but only through a proposal to add a specific UDL.</p></li>
<li><p>Inline namespaces (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2535.htm">n2535</a>) — HotSpot makes very limited use of namespaces.</p></li>
<li><p><code>using namespace</code> directives. In particular, don't use <code>using namespace std;</code> to avoid needing to qualify Standard Library names.</p></li>
<li><p>Propagating exceptions (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2179.html">n2179</a>) — HotSpot does not permit the use of exceptions, so this feature isn't useful.</p></li>
<li><p>Avoid namespace-scoped variables with non-constexpr initialization. In particular, avoid variables with types requiring non-trivial initialization or destruction. Initialization order problems can be difficult to deal with and lead to surprises, as can destruction ordering. HotSpot doesn't generally try to cleanup on exit, and running destructors at exit can also lead to problems.</p></li>
<li><p><code>[[deprecated]]</code> attribute (<ahref="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3760.html">n3760</a>) — Not relevant in HotSpot code.</p></li>
<li><p>Avoid most operator overloading, preferring named functions. When operator overloading is used, ensure the semantics conform to the normal expected behavior of the operation.</p></li>
<li><p>Avoid most implicit conversion constructors and (implicit or explicit) conversion operators. (Note that conversion to <code>bool</code> isn't needed in HotSpot code because of the "no implicit boolean" guideline.)</p></li>
<p>The purpose of these guidelines is to establish a shared vision on what kind of native tests and how we want to develop them for Hotspot using GoogleTest. Hence these guidelines include style items as well as test approach items.</p>
<p>First section of this document describes properties of good tests which are common for almost all types of test regardless of language, framework, etc. Further sections provide recommendations to achieve those properties and other HotSpot and/or GoogleTest specific guidelines.</p>
<h2id="good-test-properties">Good test properties</h2>
<h3id="lightness">Lightness</h3>
<p>Use the most lightweight type of tests.</p>
<p>In Hotspot, there are 3 different types of tests regarding their dependency on a JVM, each next level is slower than previous</p>
<ul>
<li><p><code>TEST</code> : a test does not depend on a JVM</p></li>
<li><p><code>TEST_VM</code> : a test does depend on an initialized JVM, but are supposed not to break a JVM, i.e. leave it in a workable state.</p></li>
<li><p><code>TEST_OTHER_VM</code> : a test depends on a JVM and requires a freshly initialized JVM or leaves a JVM in non-workable state</p></li>
</ul>
<h3id="isolation">Isolation</h3>
<p>Tests have to be isolated: not to have visible side-effects, influences on other tests results.</p>
<p>Results of one test should not depend on test execution order, other tests, otherwise it is becoming almost impossible to find out why a test failed. Due to hotspot-specific, it is not so easy to get a full isolation, e.g. we share an initialized JVM between all <code>TEST_VM</code> tests, so if your test changes JVM's state too drastically and does not change it back, you had better consider <code>TEST_OTHER_VM</code>.</p>
<h3id="atomicity-and-self-containment">Atomicity and self-containment</h3>
<p>Tests should be <em>atomic</em> and <em>self-contained</em> at the same time.</p>
<p>One test should check a particular part of a class, subsystem, functionality, etc. Then it is quite easy to determine what parts of a product are broken basing on test failures. On the other hand, a test should test that part more-or-less entirely, because when one sees a test <code>FooTest::bar</code>, they assume all aspects of bar from <code>Foo</code> are tested.</p>
<p>However, it is impossible to cover all aspects even of a method, not to mention a subsystem. In such cases, it is recommended to have several tests, one for each aspect of a thing under test. For example one test to tests how <code>Foo::bar</code> works if an argument is <code>null</code>, another test to test how it works if an argument is acceptable but <code>Foo</code> is not in the right state to accept it and so on. This helps not only to make tests atomic, self-contained but also makes test name self-descriptive (discussed in more details in <ahref="#test-names">Test names</a>).</p>
<h3id="repeatability">Repeatability</h3>
<p>Tests have to be repeatable.</p>
<p>Reproducibility is very crucial for a test. No one likes sporadic test failures, they are hard to investigate, fix and verify a fix.</p>
<p>In some cases, it is quite hard to write a 100% repeatable test, since besides a test there can be other moving parts, e.g. in case of <code>TEST_VM</code> there are several concurrently running threads. Despite this, we should try to make a test as reproducible as possible.</p>
<h3id="informativeness">Informativeness</h3>
<p>In case of a failure, a test should be as <em>informative</em> as possible.</p>
<p>Having more information about a test failure than just compared values can be very useful for failure troubleshooting, it can reduce or even completely eliminate debugging hours. This is even more important in case of not 100% reproducible failures.</p>
<p>Achieving this property, one can easily make a test too verbose, so it will be really hard to find useful information in the ocean of useless information. Hence they should not only think about how to provide <ahref="#error-messages">good information</a>, but also <ahref="#uncluttered-output">when to do it</a>.</p>
<h3id="testing-instead-of-visiting">Testing instead of visiting</h3>
<p>Tests should <em>test</em>.</p>
<p>It is not enough just to "visit" some code, a test should check that code does that it has to do, compare return values with expected values, check that desired side effects are done, and undesired are not, and so on. In other words, a test should contain at least one GoogleTest assertion and do not rely on JVM asserts.</p>
<p>Generally speaking to write a good test, one should create a model of the system under tests, a model of possible bugs (or bugs which one wants to find) and design tests using those models.</p>
<h3id="nearness">Nearness</h3>
<p>Prefer having checks inside test code.</p>
<p>Not only does having test logic outside, e.g. verification method, depending on asserts in product code contradict with several items above but also decreases test’s readability and stability. It is much easier to understand that a test is testing when all testing logic is located inside a test or nearby in shared test libraries. As a rule of thumb, the closer a check to a test, the better.</p>
<h2id="asserts">Asserts</h2>
<h3id="several-checks">Several checks</h3>
<p>Prefer <code>EXPECT</code> over <code>ASSERT</code> if possible.</p>
<p>This is related to the <ahref="#informativeness">informativeness</a> property of tests, information for other checks can help to better localize a defect’s root-cause. One should use <code>ASSERT</code> if it is impossible to continue test execution or if it does not make much sense. Later in the text, <code>EXPECT</code> forms will be used to refer to both <code>ASSERT/EXPECT</code>.</p>
<p>When it is possible to make several different checks, but impossible to continue test execution if at least one check fails, you can use <code>::testing::Test::HasNonfatalFailure()</code> function. The recommended way to express that is <code>ASSERT_FALSE(::testing::Test::HasNonfatalFailure())</code>. Besides making it clear why a test is aborted, it also allows you to provide more information about a failure.</p>
<h3id="first-parameter-is-expected-value">First parameter is expected value</h3>
<p>In all equality assertions, expected values should be passed as the first parameter.</p>
<p>This convention is adopted by GoogleTest, and there is a slight difference in how GoogleTest treats parameters, the most important one is <code>null</code> detection. Due to different reasons, <code>null</code> detection is enabled only for the first parameter, that is to said <code>EXPECT_EQ(NULL, object)</code> checks that object is <code>null</code>, while <code>EXPECT_EQ(object, NULL)</code> checks that object equals to <code>NULL</code>, GoogleTest is very strict regarding types of compared values so the latter will generates a compile-time error.</p>
<p>Use floating-point special macros to compare <code>float/double</code> values.</p>
<p>Because of floating-point number representations and round-off errors, regular equality comparison will not return true in most cases. There are special <code>EXPECT_FLOAT_EQ/EXPECT_DOUBLE_EQ</code> assertions which check that the distance between compared values is not more than 4 ULPs, there is also <code>EXPECT_NEAR(v1, v2, eps)</code> which checks that the absolute value of the difference between <code>v1</code> and <code>v2</code> is not greater than <code>eps</code>.</p>
<p>Use string special macros for C strings comparisons.</p>
<p><code>EXPECT_EQ</code> just compares pointers’ values, which is hardly what one wants comparing C strings. GoogleTest provides <code>EXPECT_STREQ</code> and <code>EXPECT_STRNE</code> macros to compare C string contents. There are also case-insensitive versions <code>EXPECT_STRCASEEQ</code>, <code>EXPECT_STRCASENE</code>.</p>
<h3id="error-messages">Error messages</h3>
<p>Provide informative, but not too verbose error messages.</p>
<p>All GoogleTest asserts print compared expressions and their values, so there is no need to have them in error messages. Asserts print only compared values, they do not print any of interim variables, e.g. <code>ASSERT_TRUE((val1 == val2 && isFail(foo(8)) || i == 18)</code> prints only one value. If you use some complex predicates, please consider <code>EXPECT_PRED*</code> or <code>EXPECT_FORMAT_PRED</code> assertions family, they check that a predicate returns true/success and print out all parameters values.</p>
<p>However in some cases, default information is not enough, a commonly used example is an assert inside a loop, GoogleTest will not print iteration values (unless it is an assert's parameter). Other demonstrative examples are printing error code and a corresponding error message; printing internal states which might have an impact on results. One should add this information to assert message using <code><<</code> operator.</p>
<p>Too verbose tests which print all information even if they pass are very bad practice. They just pollute output, so it becomes harder to find useful information. In order not print information till it is really needed, one should consider saving it to a temporary buffer and pass to an assert. <ahref="https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/shared/test_memset_with_concurrent_readers.cpp"class="uri">https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/shared/test_memset_with_concurrent_readers.cpp</a> has a good example how to do that.</p>
<p>Wrap a subroutine call into <code>EXPECT_NO_FATAL_FAILURE</code> macro to propagate failures.</p>
<p><code>ASSERT</code> and <code>FAIL</code> abort only the current function, so if you have them in a subroutine, a test will not be aborted after the subroutine even if <code>ASSERT</code> or <code>FAIL</code> fails. You should call such subroutines in <code>ASSERT_NO_FATAL_FAILURE</code> macro to propagate fatal failures and abort a test. <code>(EXPECT|ASSERT)_NO_FATAL_FAILURE</code> can also be used to provide more information.</p>
<p>Due to obvious reasons, there are no <code>(EXPECT|ASSERT)_NO_NONFATAL_FAILURE</code> macros. However, if you need to check if a subroutine generated a nonfatal failure (failed an <code>EXPECT</code>), you can use <code>::testing::Test::HasNonfatalFailure</code> function, or <code>::testing::Test::HasFailure</code> function to check if a subroutine generated any failures, see <ahref="#several-checks">Several checks</a>.</p>
<h2id="naming-and-grouping">Naming and Grouping</h2>
<h3id="test-group-names">Test group names</h3>
<p>Test group names should be in CamelCase, start and end with a letter. A test group should be named after tested class, functionality, subsystem, etc.</p>
<p>This naming scheme helps to find tests, filter them and simplifies test failure analysis. For example, class <code>Foo</code> - test group <code>Foo</code>, compiler logging subsystem - test group <code>CompilerLogging</code>, G1 GC — test group <code>G1GC</code>, and so forth.</p>
<h3id="filename">Filename</h3>
<p>A test file must have <code>test_</code> prefix and <code>.cpp</code> suffix.</p>
<p>Both are actually requirements from the current build system to recognize your tests.</p>
<h3id="file-location">File location</h3>
<p>Test file location should reflect a location of the tested part of the product.</p>
<ul>
<li><p>All unit tests for a class from <code>foo/bar/baz.cpp</code> should be placed <code>foo/bar/test_baz.cpp</code> in <code>hotspot/test/native/</code> directory. Having all tests for a class in one file is a common practice for unit tests, it helps to see all existing tests at once, share functions and/or resources without losing encapsulation.</p></li>
<li><p>For tests which test more than one class, directory hierarchy should be the same as product hierarchy, and file name should reflect the name of the tested subsystem/functionality. For example, if a sub-system under tests belongs to <code>gc/g1</code>, tests should be placed in <code>gc/g1</code> directory.</p></li>
</ul>
<p>Please note that framework prepends directory name to a test group name. For example, if <code>TEST(foo, check_this)</code> and <code>TEST(bar, check_that)</code> are defined in <code>hotspot/test/native/gc/shared/test_foo.cpp</code> file, they will be reported as <code>gc/shared/foo::check_this</code> and <code>gc/shared/bar::check_that</code>.</p>
<h3id="test-names">Test names</h3>
<p>Test names should be in small_snake_case, start and end with a letter. A test name should reflect that a test checks.</p>
<p>Such naming makes tests self-descriptive and helps a lot during the whole test life cycle. It is easy to do test planning, test inventory, to see what things are not tested, to review tests, to analyze test failures, to evolve a test, etc. For example <code>foo_return_0_if_name_is_null</code> is better than <code>foo_sanity</code> or <code>foo_basic</code> or just <code>foo</code>, <code>humongous_objects_can_not_be_moved_by_young_gc</code> is better than <code>ho_young_gc</code>.</p>
<p>Actually using underscore is against GoogleTest project convention, because it can lead to illegal identifiers, however, this is too strict. Restricting usage of underscore for test names only and prohibiting test name starts or ends with an underscore are enough to be safe.</p>
<h3id="fixture-classes">Fixture classes</h3>
<p>Fixture classes should be named after tested classes, subsystems, etc (follow <ahref="#test-group-names">Test group names rule</a>) and have <code>Test</code> suffix to prevent class name conflicts.</p>
<h3id="friend-classes">Friend classes</h3>
<p>All test purpose friends should have either <code>Test</code> or <code>Testable</code> suffix.</p>
<p>It greatly simplifies understanding of friendship’s purpose and allows statically check that private members are not exposed unexpectedly. Having <code>FooTest</code> as a friend of <code>Foo</code> without any comments will be understood as a necessary evil to get testability.</p>
<h3id="oscpu-specific-tests">OS/CPU specific tests</h3>
<p>Guard OS/CPU specific tests by <code>#ifdef</code> and have OS/CPU name in filename.</p>
<p>For the time being, we do not support separate directories for OS, CPU, OS-CPU specific tests, in case we will have lots of such tests, we will change directory layout and build system to support that in the same way it is done in hotspot.</p>
<h2id="miscellaneous">Miscellaneous</h2>
<h3id="hotspot-style">Hotspot style</h3>
<p>Abide the norms and rules accepted in Hotspot style guide.</p>
<p>Tests are a part of Hotspot, so everything (if applicable) we use for Hotspot, should be used for tests as well. Those guidelines cover test-specific things.</p>
<h3id="codetest-metrics">Code/test metrics</h3>
<p>Coverage information and other code/test metrics are quite useful to decide what tests should be written, what tests should be improved and what can be removed.</p>
<p>For unit tests, widely used and well-known coverage metric is branch coverage, which provides good quality of tests with relatively easy test development process. For other levels of testing, branch coverage is not as good, and one should consider others metrics, e.g. transaction flow coverage, data flow coverage.</p>
<h3id="access-to-non-public-members">Access to non-public members</h3>
<p>Use explicit friend class to get access to non-public members.</p>
<p>We do not use GoogleTest macro to declare friendship relation, because, from our point of view, it is less clear than an explicit declaration.</p>
<p>Declaring a test fixture class as a friend class of a tested test is the easiest and the clearest way to get access. However, it has some disadvantages, here is some of them:</p>
<ul>
<li>Each test has to be declared as a friend</li>
<li>Subclasses do not inheritance friendship relation</li>
</ul>
<p>In other words, it is harder to share code between tests. Hence if you want to share code or expect it to be useful in other tests, you should consider making members in a tested class protected and introduce a shared test-only class which expose those members via public functions, or even making members publicly accessible right away in a product class. If it is not an option to change members visibility, one can create a friend class which exposes members.</p>
<h3id="death-tests">Death tests</h3>
<p>You can not use death tests inside <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code>.</p>
<p>We tried to make Hotspot-GoogleTest integration as transparent as possible, however, due to the current implementation of <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> tests, you cannot use death test functionality in them. These tests are implemented as GoogleTest death tests, and GoogleTest does not allow to have a death test inside another death test.</p>
<h3id="external-flags">External flags</h3>
<p>Passing external flags to a tested JVM is not supported.</p>
<p>The rationality of such design decision is to simplify both tests and a test framework and to avoid failures related to incompatible flags combination till there is a good solution for that. However there are cases when one wants to test a JVM with specific flags combination, <code>_JAVA_OPTIONS</code> environment variable can be used to do that. Flags from <code>_JAVA_OPTIONS</code> will be used in <code>TEST_VM</code>, <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> tests.</p>
<p>Passing flags to a tested JVM in <code>TEST_OTHER_VM</code> and <code>TEST_VM_ASSERT*</code> should be possible, but is not implemented yet.</p>
<p>Facility to pass test-specific flags is needed for system, regression or other types of tests which require a fully initialized JVM in some particular configuration, e.g. with Serial GC selected. There is no support for such tests now, however, there is a plan to add that in upcoming releases.</p>
<p>For now, if a test depends on flags values, it should have <code>if (!<flag>) { return }</code> guards in the very beginning and <code>@requires</code> comment similar to jtreg <code>@requires</code> directive right before test macros. <ahref="https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/g1/test_g1IHOPControl.cpp"class="uri">https://hg.openjdk.java.net/jdk/jdk/file/tip/test/hotspot/gtest/gc/g1/test_g1IHOPControl.cpp</a> ha an example of this temporary workaround. It is important to follow that pattern as it allows us to easily find all such tests and update them as soon as there is an implementation of flag passing facility.</p>
<p>In long-term, we expect jtreg to support GoogleTest tests as first class citizens, that is to say, jtreg will parse <spanclass="citation"data-cites="requires">@requires</span> comments and filter out inapplicable tests.</p>
<h3id="flag-restoring">Flag restoring</h3>
<p>Restore changed flags.</p>
<p>It is quite common for tests to configure JVM in a certain way changing flags’ values. GoogleTest provides two ways to set up environment before a test and restore it afterward: using either constructor and destructor or <code>SetUp</code> and <code>TearDown</code> functions. Both ways require to use a test fixture class, which sometimes is too wordy. The simpler facilities like <code>FLAG_GUARD</code> macro or <code>*FlagSetting</code> classes could be used in such cases to restore/set values.</p>
<p>Caveats:</p>
<ul>
<li><p>Changing a flag’s value could break the invariants between flags' values and hence could lead to unexpected/unsupported JVM state.</p></li>
<li><p><code>FLAG_SET_*</code> macros can change more than one flag (in order to maintain invariants) so it is hard to predict what flags will be changed and it makes restoring all changed flags a nontrivial task. Thus in case one uses <code>FLAG_SET_*</code> macros, they should use <code>TEST_OTHER_VM</code> test type.</p></li>
<p>In case you have any questions regarding GoogleTest itself, its asserts, test declaration macros, other macros, etc, please consult its documentation.</p>
<h2id="todo">TODO</h2>
<p>Although this document provides guidelines on the most important parts of test development using GTest, it still misses a few items:</p>
<ul>
<li><p>Examples, esp for <ahref="#access-to-non-public-members">access to non-public members</a></p></li>
<li>test types: purpose, drawbacks, limitation
<ul>
<li><code>TEST_VM</code></li>
<li><code>TEST_VM_F</code></li>
<li><code>TEST_OTHER_VM</code></li>
<li><code>TEST_VM_ASSERT</code></li>
<li><code>TEST_VM_ASSERT_MSG</code></li>
</ul></li>
<li>Miscellaneous
<ul>
<li>Test libraries
<ul>
<li>where to place</li>
<li>how to write</li>
<li>how to use</li>
</ul></li>
<li>test your tests
<ul>
<li>how to run tests in random order</li>
<li>how to run only specific tests</li>
<li>how to run each test separately</li>
<li>check that a test can find bugs it is supposed to by introducing them</li>
</ul></li>
<li>mocks/stubs/dependency injection</li>
<li>setUp/tearDown
<ul>
<li>vs c-tor/d-tor</li>
<li>empty test to test them</li>
</ul></li>
<li>internal (declared in .cpp) struct/classes</li>
<p>Sets the argument <code>-timeoutHandlerTimeout</code> for JTReg. The default value is 0. This is only valid if the failure handler is built.</p>
<h4id="test_mode">TEST_MODE</h4>
<p>The test mode (<code>agentvm</code> or <code>othervm</code>).</p>
<p>Defaults to <code>agentvm</code>.</p>
@@ -153,8 +155,10 @@ TEST FAILURE</code></pre>
<p>Limit memory consumption (<code>-Xmx</code> and <code>-vmoption:-Xmx</code>, or none).</p>
<p>Limit memory consumption for JTReg test framework and VM under test. Set to 0 to disable the limits.</p>
<p>Defaults to 512m, except for hotspot, where it defaults to 0 (no limit).</p>
<h4id="max_output">MAX_OUTPUT</h4>
<p>Set the property <code>javatest.maxOutputSize</code> for the launcher, to change the default JTReg log limit.</p>
<h4id="keywords">KEYWORDS</h4>
<p>JTReg kewords sent to JTReg using <code>-k</code>. Please be careful in making sure that spaces and special characters (like <code>!</code>) are properly quoted. To avoid some issues, the special value <code>%20</code> can be used instead of space.</p>
<p>JTReg keywords sent to JTReg using <code>-k</code>. Please be careful in making sure that spaces and special characters (like <code>!</code>) are properly quoted. To avoid some issues, the special value <code>%20</code> can be used instead of space.</p>
<p>Use additional problem lists file or files, in addition to the default ProblemList.txt located at the JTReg test roots.</p>
<p>If multiple file names are specified, they should be separated by space (or, to help avoid quoting issues, the special value <code>%20</code>).</p>
@@ -170,6 +174,8 @@ TEST FAILURE</code></pre>
<h4id="vm_options-1">VM_OPTIONS</h4>
<p>Additional Java options to be used when compiling and running classes (sent to JTReg as <code>-vmoption</code>).</p>
<p>This option is only needed in special circumstances. To pass Java options to your test classes, use <code>JAVA_OPTIONS</code>.</p>
<h4id="launcher_options">LAUNCHER_OPTIONS</h4>
<p>Additional Java options that are sent to the java launcher that starts the JTReg harness.</p>
<h4id="aot_modules-1">AOT_MODULES</h4>
<p>Generate AOT modules before testing for the specified module, or set of modules. If multiple modules are specified, they should be separated by space (or, to help avoid quoting issues, the special value <code>%20</code>).</p>
<h4id="retry_count">RETRY_COUNT</h4>
@@ -205,14 +211,19 @@ TEST FAILURE</code></pre>
<p>Docker tests with default parameters may fail on systems with glibc versions not compatible with the one used in the default docker image (e.g., Oracle Linux 7.6 for x86). For example, they pass on Ubuntu 16.04 but fail on Ubuntu 18.04 if run like this on x86:</p>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"</code></pre>
<p>To run these tests correctly, additional parameters for the correct docker image are required on Ubuntu 18.04 by using <code>JAVA_OPTIONS</code>.</p>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"JTREG="JAVA_OPTIONS=-Djdk.test.docker.image.name=ubuntu -Djdk.test.docker.image.version=latest"</code></pre>
<pre><code>$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"\
<p>If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting <code>LANG="en_US"</code> in the environment before running tests should work. On Windows, setting <code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code> helps for most, but not all test cases. For example:</p>
<p>If your locale is non-US, some tests are likely to fail. To work around this you can set the locale to US. On Unix platforms simply setting <code>LANG="en_US"</code> in the environment before running tests should work. On Windows, setting <code>JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US"</code> helps for most, but not all test cases.</p>
<p>For example:</p>
<pre><code>$ export LANG="en_US"&& make test TEST=...
$ make test JTREG="VM_OPTIONS=-Duser.language=en -Duser.country=US" TEST=...</code></pre>
<h3id="pkcs11-tests">PKCS11 Tests</h3>
<p>It is highly recommended to use the latest NSS version when running PKCS11 tests. Improper NSS version may lead to unexpected failures which are hard to diagnose. For example, sun/security/pkcs11/Secmod/AddTrustedCert.java may fail on Ubuntu 18.04 with the default NSS version in the system. To run these tests correctly, the system property <code>test.nss.lib.paths</code> is required on Ubuntu 18.04 to specify the alternative NSS lib directories. For example:</p>
<pre><code>$ make test TEST="jtreg:sun/security/pkcs11/Secmod/AddTrustedCert.java" JTREG="JAVA_OPTIONS=-Dtest.nss.lib.paths=/path/to/your/latest/NSS-libs"</code></pre>
<p>It is highly recommended to use the latest NSS version when running PKCS11 tests. Improper NSS version may lead to unexpected failures which are hard to diagnose. For example, sun/security/pkcs11/Secmod/AddTrustedCert.java may fail on Ubuntu 18.04 with the default NSS version in the system. To run these tests correctly, the system property <code>test.nss.lib.paths</code> is required on Ubuntu 18.04 to specify the alternative NSS lib directories.</p>
<p>For example:</p>
<pre><code>$ make test TEST="jtreg:sun/security/pkcs11/Secmod/AddTrustedCert.java" \
<p>For more notes about the PKCS11 tests, please refer to test/jdk/sun/security/pkcs11/README.</p>
<h3id="client-ui-tests">Client UI Tests</h3>
<p>Some Client UI tests use key sequences which may be reserved by the operating system. Usually that causes the test failure. So it is highly recommended to disable system key shortcuts prior testing. The steps to access and disable system key shortcuts for various platforms are provided below.</p>
Defaults to TEST_JOBS (if set by `--with-test-jobs=`), otherwise it defaults to
@@ -265,32 +267,43 @@ JOBS, except for Hotspot, where the default is *number of CPU cores/2*,
but never more than *memory size in GB/2*.
#### TIMEOUT_FACTOR
The timeout factor (`-timeoutFactor`).
Defaults to 4.
#### FAILURE_HANDLER_TIMEOUT
Sets the argument `-timeoutHandlerTimeout` for JTReg. The default value is 0.
This is only valid if the failure handler is built.
#### TEST_MODE
The test mode (`agentvm` or `othervm`).
Defaults to `agentvm`.
#### ASSERT
Enable asserts (`-ea -esa`, or none).
Set to `true` or `false`. If true, adds `-ea -esa`. Defaults to true, except
for hotspot.
#### VERBOSE
The verbosity level (`-verbose`).
Defaults to `fail,error,summary`.
#### RETAIN
What test data to retain (`-retain`).
Defaults to `fail,error`.
#### MAX_MEM
Limit memory consumption (`-Xmx` and `-vmoption:-Xmx`, or none).
Limit memory consumption for JTReg test framework and VM under test. Set to 0
@@ -298,9 +311,14 @@ to disable the limits.
Defaults to 512m, except for hotspot, where it defaults to 0 (no limit).
#### MAX_OUTPUT
Set the property `javatest.maxOutputSize` for the launcher, to change the
default JTReg log limit.
#### KEYWORDS
JTReg kewords sent to JTReg using `-k`. Please be careful in making sure that
JTReg keywords sent to JTReg using `-k`. Please be careful in making sure that
spaces and special characters (like `!`) are properly quoted. To avoid some
issues, the special value `%20` can be used instead of space.
@@ -323,23 +341,30 @@ Set to `true` or `false`.
If `true`, JTReg will use `-match:` option, otherwise `-exclude:` will be used.
Default is `false`.
#### OPTIONS
Additional options to the JTReg test framework.
Use `JTREG="OPTIONS=--help all"` to see all available JTReg options.
#### JAVA_OPTIONS
Additional Java options for running test classes (sent to JTReg as
`-javaoption`).
#### VM_OPTIONS
Additional Java options to be used when compiling and running classes (sent to
JTReg as `-vmoption`).
This option is only needed in special circumstances. To pass Java options to
your test classes, use `JAVA_OPTIONS`.
#### LAUNCHER_OPTIONS
Additional Java options that are sent to the java launcher that starts the
JTReg harness.
#### AOT_MODULES
Generate AOT modules before testing for the specified module, or set of
@@ -353,6 +378,7 @@ Retry failed tests up to a set number of times. Defaults to 0.
### Gtest keywords
#### REPEAT
The number of times to repeat the tests (`--gtest_repeat`).
Default is 1. Set to -1 to repeat indefinitely. This can be especially useful
@@ -360,6 +386,7 @@ combined with `OPTIONS=--gtest_break_on_failure` to reproduce an intermittent
problem.
#### OPTIONS
Additional options to the Gtest test framework.
Use `GTEST="OPTIONS=--help"` to see all available Gtest options.
@@ -373,98 +400,127 @@ modules. If multiple modules are specified, they should be separated by space
### Microbenchmark keywords
#### FORK
Override the number of benchmark forks to spawn. Same as specifying `-f <num>`.
#### ITER
Number of measurement iterations per fork. Same as specifying `-i <num>`.
#### TIME
Amount of time to spend in each measurement iteration, in seconds. Same as
specifying `-r <num>`
#### WARMUP_ITER
Number of warmup iterations to run before the measurement phase in each fork.
Same as specifying `-wi <num>`.
#### WARMUP_TIME
Amount of time to spend in each warmup iteration. Same as specifying `-w <num>`.
#### RESULTS_FORMAT
Specify to have the test run save a log of the values. Accepts the same values
as `-rff`, i.e., `text`, `csv`, `scsv`, `json`, or `latex`.
#### VM_OPTIONS
Additional VM arguments to provide to forked off VMs. Same as `-jvmArgs <args>`
#### OPTIONS
Additional arguments to send to JMH.
## Notes for Specific Tests
### Docker Tests
Docker tests with default parameters may fail on systems with glibc versions not
compatible with the one used in the default docker image (e.g., Oracle Linux 7.6 for x86).
For example, they pass on Ubuntu 16.04 but fail on Ubuntu 18.04 if run like this on x86:
Docker tests with default parameters may fail on systems with glibc versions
not compatible with the one used in the default docker image (e.g., Oracle
Linux 7.6 for x86). For example, they pass on Ubuntu 16.04 but fail on Ubuntu
18.04 if run like this on x86:
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"
```
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker"
```
To run these tests correctly, additional parameters for the correct docker image are
required on Ubuntu 18.04 by using `JAVA_OPTIONS`.
To run these tests correctly, additional parameters for the correct docker
image are required on Ubuntu 18.04 by using `JAVA_OPTIONS`.
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker" JTREG="JAVA_OPTIONS=-Djdk.test.docker.image.name=ubuntu -Djdk.test.docker.image.version=latest"
```
$ make test TEST="jtreg:test/hotspot/jtreg/containers/docker" \
+ log_info(redefine, class, load, exceptions)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
+
assert(newer_klass == newer_method->method_holder(), "call after swapping redefined guts");
assert(newer_method != NULL, "method_with_idnum() should not be NULL");
- log_info(redefine, class, load, exceptions)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
+ log_info(redefine, class, load, exceptions)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
- assert(newer_klass == newer_method->method_holder(), "call after swapping redefined guts");
- assert(newer_method != NULL, "method_with_idnum() should not be NULL");
- log_info(redefine, class, load, exceptions)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
+ log_debug(redefine, class, update)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
assert(newer_klass == newer_method->method_holder(), "call after swapping redefined guts");
assert(newer_method != NULL, "method_with_idnum() should not be NULL");
- guarantee(sib->super() == super || super->newest_version() == SystemDictionary::Object_klass(), "siblings should have same superklass");
+ guarantee(sib->super() == super || AllowEnhancedClassRedefinition && super->newest_version() == SystemDictionary::Object_klass(), "siblings should have same superklass");
- def(EnhancedRedefineClasses_lock , PaddedMutex , nonleaf+7, false, Monitor::_safepoint_check_always); // for ensuring that class redefinition is not done in parallel
+ def(EnhancedRedefineClasses_lock , PaddedMutex , nonleaf+7, false, _safepoint_check_always); // for ensuring that class redefinition is not done in parallel
def(JNICritical_lock , PaddedMonitor, nonleaf, true, _safepoint_check_always); // used for JNI critical regions
+ log_debug(redefine, class, update)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
+
+ assert(newer_klass == newer_method->method_holder(), "call after swapping redefined guts");
+ assert(newer_method != NULL, "method_with_idnum() should not be NULL");
- log_debug(redefine, class, update)("Adjusting method: '%s' of new class %s", newer_method->name_and_sig_as_C_string(), newer_klass->name()->as_C_string());
-
- assert(newer_klass == newer_method->method_holder(), "call after swapping redefined guts");
- assert(newer_method != NULL, "method_with_idnum() should not be NULL");
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
