From e8a1a8707ee6192c85ac62a2a51c815e07613c38 Mon Sep 17 00:00:00 2001 From: Kim Barrett Date: Sun, 2 Nov 2025 07:02:06 +0000 Subject: [PATCH] 8369186: HotSpot Style Guide should permit some uses of the C++ Standard Library Reviewed-by: jrose, lkorinth, iwalulya, kvn, stefank --- doc/hotspot-style.html | 199 ++++++++++++++---- doc/hotspot-style.md | 183 ++++++++++++---- src/hotspot/cpu/aarch64/assembler_aarch64.hpp | 2 +- src/hotspot/cpu/riscv/assembler_riscv.hpp | 4 +- src/hotspot/share/code/codeBlob.cpp | 3 +- src/hotspot/share/code/relocInfo.cpp | 2 +- src/hotspot/share/cppstdlib/cstddef.hpp | 49 +++++ src/hotspot/share/cppstdlib/limits.hpp | 41 ++++ src/hotspot/share/cppstdlib/type_traits.hpp | 46 ++++ src/hotspot/share/gc/shared/bufferNode.hpp | 5 +- .../share/gc/shared/oopStorage.inline.hpp | 5 +- .../share/gc/shared/oopStorageParState.hpp | 5 +- .../gc/shared/oopStorageParState.inline.hpp | 5 +- src/hotspot/share/gc/shared/workerUtils.hpp | 3 +- .../gc/shenandoah/shenandoahSimpleBitMap.hpp | 3 +- src/hotspot/share/gc/z/zAddress.inline.hpp | 3 +- src/hotspot/share/gc/z/zArray.hpp | 3 +- .../gc/z/zDeferredConstructed.inline.hpp | 3 +- src/hotspot/share/gc/z/zDirector.cpp | 3 +- src/hotspot/share/gc/z/zForwardingEntry.hpp | 5 +- src/hotspot/share/gc/z/zInitialize.hpp | 5 +- src/hotspot/share/gc/z/zPageAge.inline.hpp | 3 +- src/hotspot/share/gc/z/zPageTable.inline.hpp | 3 +- src/hotspot/share/gc/z/zSafeDelete.hpp | 5 +- src/hotspot/share/gc/z/zSafeDelete.inline.hpp | 5 +- src/hotspot/share/gc/z/zStat.cpp | 3 +- src/hotspot/share/memory/metadataFactory.hpp | 3 +- .../share/memory/metaspace/counters.hpp | 3 +- src/hotspot/share/memory/metaspaceClosure.hpp | 3 +- .../share/metaprogramming/enableIf.hpp | 4 +- .../metaprogramming/primitiveConversions.hpp | 5 +- src/hotspot/share/nmt/arrayWithFreeList.hpp | 5 +- .../share/nmt/nmtNativeCallStackStorage.hpp | 3 +- src/hotspot/share/oops/accessBackend.hpp | 5 +- .../share/oops/accessBackend.inline.hpp | 3 +- src/hotspot/share/oops/accessDecorators.hpp | 5 +- src/hotspot/share/oops/compressedOops.hpp | 5 +- src/hotspot/share/oops/instanceOop.hpp | 5 +- src/hotspot/share/oops/markWord.hpp | 3 +- src/hotspot/share/oops/objArrayOop.hpp | 3 +- src/hotspot/share/oops/oop.hpp | 3 +- src/hotspot/share/oops/oopHandle.hpp | 5 +- src/hotspot/share/oops/oopsHierarchy.hpp | 5 +- src/hotspot/share/oops/typeArrayOop.hpp | 5 +- src/hotspot/share/opto/rangeinference.hpp | 3 +- src/hotspot/share/runtime/arguments.cpp | 3 +- src/hotspot/share/runtime/atomicAccess.hpp | 3 +- .../share/runtime/continuationFreezeThaw.cpp | 3 +- src/hotspot/share/runtime/flags/jvmFlag.hpp | 5 +- src/hotspot/share/runtime/lockStack.cpp | 3 +- .../share/runtime/sharedRuntimeTrans.cpp | 3 +- .../share/services/diagnosticFramework.hpp | 4 +- src/hotspot/share/utilities/align.hpp | 3 +- src/hotspot/share/utilities/byteswap.hpp | 4 +- .../utilities/concurrentHashTable.inline.hpp | 3 +- .../share/utilities/deferredStatic.hpp | 2 +- .../share/utilities/devirtualizer.inline.hpp | 5 +- src/hotspot/share/utilities/enumIterator.hpp | 5 +- .../share/utilities/globalDefinitions.hpp | 6 +- src/hotspot/share/utilities/hashTable.hpp | 5 +- src/hotspot/share/utilities/intn_t.hpp | 3 +- src/hotspot/share/utilities/intpow.hpp | 5 +- src/hotspot/share/utilities/parseInteger.hpp | 4 +- .../share/utilities/population_count.hpp | 5 +- src/hotspot/share/utilities/powerOfTwo.hpp | 7 +- src/hotspot/share/utilities/rbTree.hpp | 3 +- src/hotspot/share/utilities/reverse_bits.hpp | 6 +- src/hotspot/share/utilities/tuple.hpp | 4 +- 68 files changed, 531 insertions(+), 235 deletions(-) create mode 100644 src/hotspot/share/cppstdlib/cstddef.hpp create mode 100644 src/hotspot/share/cppstdlib/limits.hpp create mode 100644 src/hotspot/share/cppstdlib/type_traits.hpp diff --git a/doc/hotspot-style.html b/doc/hotspot-style.html index f1c25dab7f4..a2ffb57e5a3 100644 --- a/doc/hotspot-style.html +++ b/doc/hotspot-style.html @@ -114,7 +114,7 @@ id="toc-compatibility-with-c11">Compatibility with C11 id="toc-additional-permitted-features">Additional Permitted Features -
  • Excluded +
  • Forbidden Features
  • Undecided @@ -506,19 +506,19 @@ uses a subset. (Backports to JDK versions lacking support for more recent Standards must of course stick with the original C++98/03 subset.)

    This section describes that subset. Features from the C++98/03 -language may be used unless explicitly excluded here. Features from +language may be used unless explicitly forbidden here. Features from C++11, C++14, and C++17 may be explicitly permitted or explicitly -excluded, and discussed accordingly here. There is a third category, +forbidden, 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.

    +is also forbidden.

    (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.)

    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.

    +sections for permitted, forbidden, and undecided features.

    Lists of new features for C++11, C++14, and C++17, along with links to their descriptions, can be found in the online documentation for some of the compilers and libraries. The C++17 Standard is the definitive @@ -594,14 +594,15 @@ title="Runtime Type Information">RTTI are deemed not worthwhile, given the alternatives.

    Memory Allocation

    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.

    +(global operator new and related functions), other than the +non-allocating forms of those functions. Use of these functions by +HotSpot code is disabled for some platforms.

    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. Typically, uses of the global operator -new are inadvertent and therefore often associated with memory -leaks.

    +in favor of wrappers around malloc and free +that support the JVM's Native Memory Tracking (NMT) feature. Typically, +uses of the global operator new are inadvertent and +therefore often associated with memory leaks.

    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.

    @@ -648,7 +649,39 @@ for anonymous namespaces.

    class="uri">https://sourceware.org/bugzilla/show_bug.cgi?id=16874
    Bug for similar gdb problems.

    C++ Standard Library

    -

    Avoid using the C++ Standard Library.

    +

    Only curated parts of the C++ Standard Library may be used by HotSpot +code.

    +

    Functions that may throw exceptions must not be used. This is in +accordance with the HotSpot policy of not +using exceptions.

    +

    Also in accordance with HotSpot policy, the standard global allocator must not be +used. This means that uses of standard container classes cannot +presently be used, as doing so requires specialization on some allocator +type that is integrated with the existing HotSpot allocation mechanisms. +(Such allocators may be provided in the future.)

    +

    Standard Library identifiers should usually be fully qualified; +using directives must not be used to bring Standard Library +identifiers into scope just to remove the need for namespace +qualification. Requiring qualification makes it easy to distinguish +between references to external libraries and code that is part of +HotSpot.

    +

    As with language features, Standard Library facilities are either +permitted, explicitly forbidden, or undecided (and so implicitly +forbidden).

    +

    Most HotSpot code should not directly #include C++ +Standard Library headers. HotSpot provides a set of wrapper headers for +the Standard Library headers containing permitted definitions. These +wrappers are in the cppstdlib directory, with the same name +as the corresponding Standard Library header and a .hpp +extension. These wrappers provide a place for any additional code (some +of which may be platform-specific) needed to support HotSpot usage.

    +

    These wrappers also provide a place to document HotSpot usage, +including any restrictions. The set of wrappers and the usage +documentation should be considered part of HotSpot style. Any changes +are subject to the same process as applies to this document. (For +historical reasons, there may be many direct inclusions of some C++ +Standard Library headers.)

    Historically, HotSpot has mostly avoided use of the Standard Library.

    (It used to be impossible to use most of it in shared code, because @@ -661,46 +694,60 @@ in mid-2017. Support for Solaris was removed in 2020.)

    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.

    • +use exceptions. On the other hand, many don't, and can be used without +concern for this issue. Others may have a useful subset that doesn't use +exceptions.

  • assert. An issue that is quickly encountered is the assert macro name collision (JDK-8007770). -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.)

    • +(Not all Standard Library implementations use assert in +header files, but some do.) HotSpot provides a mechanism for addressing +this, by establishing a scope around the include of a library header +where the HotSpot assert macro is suppressed. One of the +reasons for using wrapper headers rather than directly including +standard headers is to provide a central place to deal with this issue +for each header.

  • Memory allocation. HotSpot requires explicit control over where allocations occur. The C++98/03 std::allocator class is too -limited to support our usage. (Changes in more recent Standards may -remove this limitation.)

    • +limited to support our usage. But changes to the allocator concept in +more recent Standards removed some of the limitations, supporting +stateful allocators. HotSpot may, in the future, provide +standard-conforming allocators that are integrated with HotSpot's +existing allocation mechanisms.

  • Implementation vagaries. Bugs, or simply different implementation choices, can lead to different behaviors among the various Standard -Libraries we need to deal with.

    • +Libraries we need to deal with. But only selected parts of the Standard +Library are being permitted, and one of the selection criteria is +maturity. Some of these facilities are among the most heavily tested and +used C++ codes that exist.

  • Inconsistent naming conventions. HotSpot and the C++ Standard use different naming conventions. The coexistence of those different -conventions might appear jarring and reduce readability.

    • - -

    There are a few exceptions to this rule.

    +conventions might appear jarring and reduce readability. However, +experience in some other code bases suggests this isn't a significant +problem, so long as Standard Library names are namespace-qualified. It +is tempting to bring the Standard Library names into scope via a +using std; directive. Doing so makes writing code using +those names easier, since the qualifiers don't need to be included. But +there are several reasons not to do that.

    -

    Certain restrictions apply to the declarations provided by -<type_traits>.

    - -

    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.

    Type Deduction

    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, @@ -1577,10 +1624,10 @@ href="http://wg21.link/p0138r2">p0138r2)

  • Allow typename in template template parameter (n4051) — template template parameters are barely used (if at all) in HotSpot, but there's no reason to -artificially disallow this syntactic regularization in any such +artificially forbid this syntactic regularization in any such uses.

    • -

    Excluded Features

    +

    Forbidden Features

    Structured Bindings

    The use of structured bindings p0217r3 is forbidden. Preferred @@ -1622,8 +1669,33 @@ initialization for classes with base classes (p0017r1). HotSpot makes very little use of aggregate classes, preferring explicit constructors even for very simple classes.

    -

    Additional Excluded Features

    +

    Additional Forbidden +Features