diff --git a/.github/workflows/build-cross-compile.yml b/.github/workflows/build-cross-compile.yml index 351d087ef7d..b3c63f488a0 100644 --- a/.github/workflows/build-cross-compile.yml +++ b/.github/workflows/build-cross-compile.yml @@ -64,33 +64,33 @@ jobs: gnu-arch: aarch64 debian-arch: arm64 debian-repository: https://httpredir.debian.org/debian/ - debian-version: bookworm + debian-version: trixie tolerate-sysroot-errors: false - target-cpu: arm gnu-arch: arm debian-arch: armhf debian-repository: https://httpredir.debian.org/debian/ - debian-version: bookworm + debian-version: trixie tolerate-sysroot-errors: false gnu-abi: eabihf - target-cpu: s390x gnu-arch: s390x debian-arch: s390x debian-repository: https://httpredir.debian.org/debian/ - debian-version: bookworm + debian-version: trixie tolerate-sysroot-errors: false - target-cpu: ppc64le gnu-arch: powerpc64le debian-arch: ppc64el debian-repository: https://httpredir.debian.org/debian/ - debian-version: bookworm + debian-version: trixie tolerate-sysroot-errors: false - target-cpu: riscv64 gnu-arch: riscv64 debian-arch: riscv64 debian-repository: https://httpredir.debian.org/debian/ - debian-version: sid - tolerate-sysroot-errors: true + debian-version: trixie + tolerate-sysroot-errors: false steps: - name: 'Checkout the JDK source' diff --git a/make/scripts/generate-symbol-data.sh b/bin/generate-symbol-data.sh similarity index 83% rename from make/scripts/generate-symbol-data.sh rename to bin/generate-symbol-data.sh index 6f38d873009..283757a6918 100644 --- a/make/scripts/generate-symbol-data.sh +++ b/bin/generate-symbol-data.sh @@ -1,6 +1,6 @@ #!/bin/sh # -# Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2019, 2025, Oracle and/or its affiliates. All rights reserved. # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. # # This code is free software; you can redistribute it and/or modify it @@ -52,12 +52,39 @@ # include the SCM state that was used to build it, which can be found in ${JDK_N_INSTALL}/release, # in property "SOURCE". +source_path="$(dirname ${0})" +this_script_dir="$(cd -- "${source_path}" > /dev/null && pwd)" +if test -z "${this_script_dir}"; then + echo "Error: Could not determine location of this script" + exit 1 +fi + +symbols_dir="$(dirname $this_script_dir)/src/jdk.compiler/share/data/symbols" +if [ ! -d $symbols_dir ] ; then + echo "Cannot locate symbols directory: $symbols_dir" >&2 + exit 1 +fi + +generator_dir="$(dirname $this_script_dir)/make/langtools/src/classes/build/tools/symbolgenerator" + if [ "$1x" = "x" ] ; then echo "Must provide the target JDK as a parameter:" >&2 echo "$0 " >&2 exit 1 fi; +if [ ! -d $1 ] ; then + echo "Target JDK argument is not a directory:" $1 >&2 + exit 1 +fi; + +if [ ! -x $1/bin/java ] ; then + echo "Target JDK argument is not a valid JDK: $1" >&2 + exit 1 +fi; + +cd $symbols_dir + if [ ! -f symbols ] ; then echo "Must run inside the src/jdk.compiler/share/data/symbols directory" >&2 exit 1 @@ -72,5 +99,5 @@ $1/bin/java --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \ --add-exports jdk.compiler/com.sun.tools.javac.jvm=ALL-UNNAMED \ --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \ --add-modules jdk.jdeps \ - ../../../../../make/langtools/src/classes/build/tools/symbolgenerator/CreateSymbols.java \ + $generator_dir/CreateSymbols.java \ build-description-incremental symbols include.list diff --git a/bin/idea.sh b/bin/idea.sh index eb37964f396..a184884b61a 100644 --- a/bin/idea.sh +++ b/bin/idea.sh @@ -125,7 +125,8 @@ if [ -d "$TOPLEVEL_DIR/.hg" ] ; then VCS_TYPE="hg4idea" fi -if [ -d "$TOPLEVEL_DIR/.git" ] ; then +# Git worktrees use a '.git' file rather than directory, so test both. +if [ -d "$TOPLEVEL_DIR/.git" -o -f "$TOPLEVEL_DIR/.git" ] ; then VCS_TYPE="Git" fi diff --git a/make/scripts/lic_check.sh b/bin/lic_check.sh similarity index 98% rename from make/scripts/lic_check.sh rename to bin/lic_check.sh index d70d8914181..2fc6abf4d82 100644 --- a/make/scripts/lic_check.sh +++ b/bin/lic_check.sh @@ -1,6 +1,6 @@ #! /bin/sh -f # -# Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved. # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. # # This code is free software; you can redistribute it and/or modify it @@ -62,7 +62,7 @@ B=`basename "${script_directory}"` script_dir="`cd \"${D}\" 2>/dev/null && pwd || echo \"${D}\"`/${B}" # set up a variable for the template directory -template_dir=${script_dir}/../data/license-templates +template_dir=${script_dir}/../make/data/license-templates # Check existence of the template directory. if [ ! -d ${template_dir} ] ; then diff --git a/make/scripts/normalizer.pl b/bin/normalizer.pl similarity index 100% rename from make/scripts/normalizer.pl rename to bin/normalizer.pl diff --git a/bin/unshuffle_list.txt b/bin/unshuffle_list.txt deleted file mode 100644 index a910f6b4621..00000000000 --- a/bin/unshuffle_list.txt +++ /dev/null @@ -1,191 +0,0 @@ -# -# Copyright (c) 2014, 2025, Oracle and/or its affiliates. All rights reserved. -# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -# -# This code is free software; you can redistribute it and/or modify it -# under the terms of the GNU General Public License version 2 only, as -# published by the Free Software Foundation. -# -# This code is distributed in the hope that it will be useful, but WITHOUT -# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -# version 2 for more details (a copy is included in the LICENSE file that -# accompanied this code). -# -# You should have received a copy of the GNU General Public License version -# 2 along with this work; if not, write to the Free Software Foundation, -# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -# -# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA -# or visit www.oracle.com if you need additional information or have any -# questions. -# - -src/bsd : jdk/src/bsd -src/demo : jdk/src/demo -src/java.activation : jaxws/src/java.activation -src/java.base : jdk/src/java.base -src/java.compiler : langtools/src/java.compiler -src/java.corba : corba/src/java.corba -src/java.datatransfer : jdk/src/java.datatransfer -src/java.desktop : jdk/src/java.desktop -src/java.instrument : jdk/src/java.instrument -src/java.logging : jdk/src/java.logging -src/java.management : jdk/src/java.management -src/java.management.rmi : jdk/src/java.management.rmi -src/java.naming : jdk/src/java.naming -src/java.prefs : jdk/src/java.prefs -src/java.rmi : jdk/src/java.rmi -src/java.scripting : jdk/src/java.scripting -src/java.se : jdk/src/java.se -src/java.security.jgss : jdk/src/java.security.jgss -src/java.security.sasl : jdk/src/java.security.sasl -src/java.se.ee : jdk/src/java.se.ee -src/java.smartcardio : jdk/src/java.smartcardio -src/java.sql : jdk/src/java.sql -src/java.sql.rowset : jdk/src/java.sql.rowset -src/java.transaction : jdk/src/java.transaction -src/java.xml : jaxp/src/java.xml -src/java.xml.bind : jaxws/src/java.xml.bind -src/java.xml.crypto : jdk/src/java.xml.crypto -src/java.xml.ws : jaxws/src/java.xml.ws -src/java.xml.ws.annotation : jaxws/src/java.xml.ws.annotation -src/jdk.accessibility : jdk/src/jdk.accessibility -src/jdk.aot : hotspot/src/jdk.aot -src/jdk.attach : jdk/src/jdk.attach -src/jdk.charsets : jdk/src/jdk.charsets -src/jdk.compiler : jdk/src/jdk.compiler langtools/src/jdk.compiler -src/jdk.crypto.cryptoki : jdk/src/jdk.crypto.cryptoki -src/jdk.crypto.ec : jdk/src/jdk.crypto.ec -src/jdk.crypto.mscapi : jdk/src/jdk.crypto.mscapi -src/jdk.dynalink : nashorn/src/jdk.dynalink -src/jdk.editpad : jdk/src/jdk.editpad -src/jdk.hotspot.agent : hotspot/src/jdk.hotspot.agent -src/jdk.httpserver : jdk/src/jdk.httpserver -src/jdk.incubator.httpclient : jdk/src/jdk.incubator.httpclient -src/jdk.internal.ed : jdk/src/jdk.internal.ed -src/jdk.internal.jvmstat : jdk/src/jdk.internal.jvmstat -src/jdk.internal.le : jdk/src/jdk.internal.le -src/jdk.internal.opt : jdk/src/jdk.internal.opt -src/jdk.internal.vm.ci : hotspot/src/jdk.internal.vm.ci -src/jdk.internal.vm.compiler : hotspot/src/jdk.internal.vm.compiler -src/jdk.jartool : jdk/src/jdk.jartool -src/jdk.javadoc : langtools/src/jdk.javadoc -src/jdk.jcmd : jdk/src/jdk.jcmd -src/jdk.jconsole : jdk/src/jdk.jconsole -src/jdk.jdeps : langtools/src/jdk.jdeps -src/jdk.jdi : jdk/src/jdk.jdi -src/jdk.jdwp.agent : jdk/src/jdk.jdwp.agent -src/jdk.jlink : jdk/src/jdk.jlink -src/jdk.jshell : langtools/src/jdk.jshell -src/jdk.jstatd : jdk/src/jdk.jstatd -src/jdk.localedata : jdk/src/jdk.localedata -src/jdk.management : jdk/src/jdk.management -src/jdk.management.agent : jdk/src/jdk.management.agent -src/jdk.naming.dns : jdk/src/jdk.naming.dns -src/jdk.naming.rmi : jdk/src/jdk.naming.rmi -src/jdk.net : jdk/src/jdk.net -src/jdk.pack : jdk/src/jdk.pack -src/jdk.scripting.nashorn : nashorn/src/jdk.scripting.nashorn -src/jdk.scripting.nashorn.shell : nashorn/src/jdk.scripting.nashorn.shell -src/jdk.sctp : jdk/src/jdk.sctp -src/jdk.security.auth : jdk/src/jdk.security.auth -src/jdk.security.jgss : jdk/src/jdk.security.jgss -src/jdk.unsupported : jdk/src/jdk.unsupported -src/jdk.xml.bind : jaxws/src/jdk.xml.bind -src/jdk.xml.dom : jaxp/src/jdk.xml.dom -src/jdk.xml.ws : jaxws/src/jdk.xml.ws -src/jdk.zipfs : jdk/src/jdk.zipfs -src/langtools/sample : langtools/src/sample -src/linux : jdk/src/linux -src/sample : jdk/src/sample -src/hotspot/share : hotspot/src/share/vm -src/hotspot/cpu/aarch64 : hotspot/src/cpu/aarch64/vm -src/hotspot/cpu/arm : hotspot/src/cpu/arm/vm -src/hotspot/cpu/ppc : hotspot/src/cpu/ppc/vm -src/hotspot/cpu/s390 : hotspot/src/cpu/s390/vm -src/hotspot/cpu/x86 : hotspot/src/cpu/x86/vm -src/hotspot/cpu/zero : hotspot/src/cpu/zero/vm -src/hotspot/os/aix : hotspot/src/os/aix/vm -src/hotspot/os/bsd : hotspot/src/os/bsd/vm -src/hotspot/os/linux : hotspot/src/os/linux/vm -src/hotspot/os/posix/dtrace : hotspot/src/os/posix/dtrace -src/hotspot/os/posix : hotspot/src/os/posix/vm -src/hotspot/os/windows : hotspot/src/os/windows/vm -src/hotspot/os_cpu/aix_ppc : hotspot/src/os_cpu/aix_ppc/vm -src/hotspot/os_cpu/bsd_x86 : hotspot/src/os_cpu/bsd_x86/vm -src/hotspot/os_cpu/bsd_zero : hotspot/src/os_cpu/bsd_zero/vm -src/hotspot/os_cpu/linux_aarch64 : hotspot/src/os_cpu/linux_aarch64/vm -src/hotspot/os_cpu/linux_arm : hotspot/src/os_cpu/linux_arm/vm -src/hotspot/os_cpu/linux_ppc : hotspot/src/os_cpu/linux_ppc/vm -src/hotspot/os_cpu/linux_s390 : hotspot/src/os_cpu/linux_s390/vm -src/hotspot/os_cpu/linux_x86 : hotspot/src/os_cpu/linux_x86/vm -src/hotspot/os_cpu/linux_zero : hotspot/src/os_cpu/linux_zero/vm -src/hotspot/os_cpu/windows_x86 : hotspot/src/os_cpu/windows_x86/vm -src/hotspot : hotspot/src -src/utils/IdealGraphVisualizer : hotspot/src/share/tools/IdealGraphVisualizer -src/utils/LogCompilation : hotspot/src/share/tools/LogCompilation -src/utils/hsdis : hotspot/src/share/tools/hsdis -src/utils/reorder : jdk/make/non-build-utils/reorder -src/utils/src/build : jdk/make/non-build-utils/src/build -make/BuildNashorn.gmk : nashorn/make/BuildNashorn.gmk -make/CompileDemos.gmk : jdk/make/CompileDemos.gmk -make/CompileInterimLangtools.gmk : langtools/make/CompileInterim.gmk -make/CompileModuleTools.gmk : jdk/make/CompileModuleTools.gmk -make/CompileToolsHotspot.gmk : hotspot/make/CompileTools.gmk -make/CompileToolsJdk.gmk : jdk/make/CompileTools.gmk -make/CopyInterimCLDRConverter.gmk : jdk/make/CopyInterimCLDRConverter.gmk -make/GenerateModuleSummary.gmk : jdk/make/GenerateModuleSummary.gmk -make/ModuleTools.gmk : jdk/make/ModuleTools.gmk -make/ToolsJdk.gmk : jdk/make/Tools.gmk -make/ToolsLangtools.gmk : langtools/make/Tools.gmk -make/UnpackSecurity.gmk : jdk/make/UnpackSecurity.gmk -make/autoconf : common/autoconf -make/conf : common/conf -make/copy : jdk/make/copy -make/copy/Copy-java.corba.gmk : corba/make/copy/Copy-java.corba.gmk -make/corba : corba/make -make/data : jdk/make/data -make/gendata : jdk/make/gendata -make/gendata/Gendata-jdk.compiler.gmk : langtools/make/gendata/Gendata-jdk.compiler.gmk -make/gensrc : jdk/make/gensrc -make/gensrc/Gensrc-java.corba.gmk : corba/make/gensrc/Gensrc-java.corba.gmk -make/gensrc/Gensrc-jdk.compiler.gmk : langtools/make/gensrc/Gensrc-jdk.compiler.gmk -make/gensrc/Gensrc-jdk.hotspot.agent.gmk : hotspot/make/gensrc/Gensrc-jdk.hotspot.agent.gmk -make/gensrc/Gensrc-jdk.internal.vm.compiler.gmk : hotspot/make/gensrc/Gensrc-jdk.internal.vm.compiler.gmk -make/gensrc/Gensrc-jdk.javadoc.gmk : langtools/make/gensrc/Gensrc-jdk.javadoc.gmk -make/gensrc/Gensrc-jdk.jdeps.gmk : langtools/make/gensrc/Gensrc-jdk.jdeps.gmk -make/gensrc/Gensrc-jdk.jshell.gmk : langtools/make/gensrc/Gensrc-jdk.jshell.gmk -make/gensrc/GensrcCommonLangtools.gmk : langtools/make/gensrc/GensrcCommon.gmk -make/hotspot : hotspot/make -make/jdk : jdk/make -make/langtools : langtools/make -make/launcher : jdk/make/launcher -make/lib : jdk/make/lib -make/lib/Lib-jdk.hotspot.agent.gmk : hotspot/make/lib/Lib-jdk.hotspot.agent.gmk -make/mapfiles : jdk/make/mapfiles -make/mapfiles/libjsig : hotspot/make/mapfiles/libjsig -make/mapfiles/libjvm_db : hotspot/make/mapfiles/libjvm_db -make/mapfiles/libjvm_dtrace : hotspot/make/mapfiles/libjvm_dtrace -make/mapfiles/libsaproc : hotspot/make/mapfiles/libsaproc -make/nashorn : nashorn/make -make/nb_native : common/nb_native -make/scripts/addNotices.sh : jdk/make/scripts/addNotices.sh -make/scripts/compare.sh : common/bin/compare.sh -make/scripts/compare_exceptions.sh.incl : common/bin/compare_exceptions.sh.incl -make/scripts/genExceptions.sh : jdk/make/scripts/genExceptions.sh -make/scripts/hide_important_warnings_from_javac.sh : common/bin/hide_important_warnings_from_javac.sh -make/scripts/logger.sh : common/bin/logger.sh -make/src/native/fixpath.c : common/src/fixpath.c -make/test/JtregNativeHotspot.gmk : hotspot/make/test/JtregNative.gmk -make/test/JtregNativeJdk.gmk : jdk/make/test/JtregNative.gmk -test/jdk : jdk/test -test/langtools : langtools/test -test/nashorn : nashorn/test -test/jaxp : jaxp/test -test/hotspot/gtest : hotspot/test/native -test/hotspot/jtreg : hotspot/test -bin : common/bin -bin/nashorn : nashorn/bin -doc : common/doc -doc/nashorn : nashorn/docs diff --git a/bin/unshuffle_patch.sh b/bin/unshuffle_patch.sh deleted file mode 100644 index c5cdc3851c3..00000000000 --- a/bin/unshuffle_patch.sh +++ /dev/null @@ -1,237 +0,0 @@ -#!/bin/bash -# -# Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved. -# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -# -# This code is free software; you can redistribute it and/or modify it -# under the terms of the GNU General Public License version 2 only, as -# published by the Free Software Foundation. -# -# This code is distributed in the hope that it will be useful, but WITHOUT -# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -# version 2 for more details (a copy is included in the LICENSE file that -# accompanied this code). -# -# You should have received a copy of the GNU General Public License version -# 2 along with this work; if not, write to the Free Software Foundation, -# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -# -# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA -# or visit www.oracle.com if you need additional information or have any -# questions. -# - -# Script for updating a patch file as per the shuffled/unshuffled source location. - -usage() { - echo "Usage: $0 [-h|--help] [-v|--verbose] [-to9|-to10] [-r ] " - echo "where:" - echo " -to9 create patches appropriate for a JDK 9 source tree" - echo " When going to 9, the output patches will be suffixed with the" - echo " repo name" - echo " -to10 create patches appropriate for a JDK 10 source tree" - echo " -r specify repo for source patch, set to 'top' for top repo" - echo " is the input patch file, that needs shuffling/unshuffling" - echo " is the updated patch file " - echo " " - exit 1 -} - -SCRIPT_DIR=`dirname $0` -UNSHUFFLE_LIST=$SCRIPT_DIR"/unshuffle_list.txt" - -if [ ! -f "$UNSHUFFLE_LIST" ] ; then - echo "FATAL: cannot find $UNSHUFFLE_LIST" >&2 - exit 1 -fi - -vflag="false" -while [ $# -gt 0 ] -do - case $1 in - -h | --help ) - usage - ;; - - -v | --verbose ) - vflag="true" - ;; - - -r) - repo="$2" - shift - ;; - - -to9) - shuffle_to=9 - ;; - - -to10) - shuffle_to=10 - ;; - - -*) # bad option - usage - ;; - - * ) # non option - break - ;; - esac - shift -done - -# Make sure we have the right number of arguments -if [ ! $# -eq 2 ] ; then - echo "ERROR: Invalid number of arguments." >&2 - usage -fi - -# Check the given repo -repos="top corba jaxp jaxws jdk langtools nashorn hotspot" -found="false" -if [ -n "$repo" ]; then - for r in $repos ; do - if [ $repo = "$r" ] ; then - found="true" - break; - fi - done - if [ $found = "false" ] ; then - echo "ERROR: Unknown repo: $repo. Should be one of [$repos]." >&2 - usage - fi -fi - -if [ "$shuffle_to" != "9" -a "$shuffle_to" != "10" ]; then - echo "ERROR: Must pick either -to9 or -to10" - exit 1 -fi - -# When going to 10, a repo must be specified for the source patch -if [ "$shuffle_to" = "10" -a -z "$repo" ]; then - echo "ERROR: Must specify src repo for JDK 9 patch" - exit 1 -fi - -# Check given input/output files -input="$1" -if [ "x$input" = "x-" ] ; then - input="/dev/stdin" -fi - -if [ ! -f $input -a "x$input" != "x/dev/stdin" ] ; then - echo "ERROR: Cannot find input patch file: $input" >&2 - exit 1 -fi - -output="$2" -if [ "x$output" = "x-" ] ; then - output="/dev/stdout" -fi -base_output="$output" - -if [ "$shuffle_to" = "10" ]; then - if [ -f $output -a "x$output" != "x/dev/stdout" ] ; then - echo "ERROR: Output patch already exists: $output" >&2 - exit 1 - fi -else - for r in $repos; do - if [ -f "$output.$r" ]; then - echo "ERROR: Output patch already exists: $output.$r" >&2 - exit 1 - fi - done -fi - -verbose() { - if [ ${vflag} = "true" ] ; then - echo "$@" >&2 - fi -} - -unshuffle() { - line=$@ - verbose "Attempting to rewrite: \"$line\"" - - # Retrieve the file name - path= - if echo "$line" | egrep '^diff' > /dev/null ; then - if ! echo "$line" | egrep '\-\-git' > /dev/null ; then - echo "ERROR: Only git patches supported. Please use 'hg export --git ...'." >&2 - exit 1 - fi - path="`echo "$line" | sed -e s@'diff --git a/'@@ -e s@' b/.*$'@@`" - elif echo "$line" | egrep '^\-\-\-' > /dev/null ; then - path="`echo "$line" | sed -e s@'--- a/'@@`" - elif echo "$line" | egrep '^\+\+\+' > /dev/null ; then - path="`echo "$line" | sed s@'+++ b/'@@`" - fi - verbose "Extracted path: \"$path\"" - - # Find the most specific matches in the shuffle list - matches= - if [ -n "$repo" -a "$repo" != "top" ]; then - matchpath="$repo"/"$path"/x - else - matchpath="$path"/x - fi - while [ "$matchpath" != "" ] ; do - matchpath="`echo $matchpath | sed s@'\(.*\)/.*$'@'\1'@`" - - if [ "$shuffle_to" = "10" ] ; then - pattern=": $matchpath$" - else - pattern="^$matchpath :" - fi - verbose "Attempting to find \"$matchpath\"" - matches=`egrep "$pattern" "$UNSHUFFLE_LIST"` - if ! [ "x${matches}" = "x" ] ; then - verbose "Got matches: [$matches]" - break; - fi - - if ! echo "$matchpath" | egrep '.*/.*' > /dev/null ; then - break; - fi - done - - # Rewrite the line, if we have a match - if ! [ "x${matches}" = "x" ] ; then - shuffled="${matches%% : *}" - unshuffled="${matches#* : }" - patch_suffix_9="" - for r in $repos; do - if [ "$unshuffled" != "${unshuffled#$r}" ]; then - unshuffled="${unshuffled#$r\/}" - patch_suffix_9=".$r" - fi - done - verbose "shuffled: $shuffled" - verbose "unshuffled: $unshuffled" - verbose "patch_suffix_9: $patch_suffix_9" - if [ "$shuffle_to" = "10" ] ; then - newline="`echo "$line" | sed -e s@"$unshuffled"@"$shuffled"@g`" - else - newline="`echo "$line" | sed -e s@"$shuffled"@"$unshuffled"@g`" - output=$base_output$patch_suffix_9 - verbose "Writing to $output" - fi - verbose "Rewriting to \"$newline\"" - echo "$newline" >> $output - else - echo "WARNING: no match found for $path" - echo "$line" >> $output - fi -} - -while IFS= read -r line -do - if echo "$line" | egrep '^diff|^\-\-\-|^\+\+\+' > /dev/null ; then - unshuffle "$line" - else - printf "%s\n" "$line" >> $output - fi -done < "$input" diff --git a/make/scripts/update_copyright_year.sh b/bin/update_copyright_year.sh similarity index 95% rename from make/scripts/update_copyright_year.sh rename to bin/update_copyright_year.sh index 578ab4cbc99..fa7989d234b 100644 --- a/make/scripts/update_copyright_year.sh +++ b/bin/update_copyright_year.sh @@ -62,17 +62,22 @@ Help() echo "options:" echo "-c Specifies the company. Set to Oracle by default." echo "-y Specifies the copyright year. Set to current year by default." + echo "-b Specifies the base reference for change set lookup." echo "-f Updates the copyright for all change sets in a given year," - echo " as specified by -y." + echo " as specified by -y. Overrides -b flag." echo "-h Print this help." echo } full_year=false +base_reference=master # Process options -while getopts "c:fhy:" option; do +while getopts "b:c:fhy:" option; do case $option in + b) # supplied base reference + base_reference=${OPTARG} + ;; c) # supplied company year company=${OPTARG} ;; @@ -111,7 +116,7 @@ else if [ "$full_year" = "true" ]; then vcs_list_changesets=(git log --no-merges --since="${year}-01-01T00:00:00Z" --until="${year}-12-31T23:59:59Z" --pretty=tformat:"%H") else - vcs_list_changesets=(git log --no-merges 'master..HEAD' --since="${year}-01-01T00:00:00Z" --until="${year}-12-31T23:59:59Z" --pretty=tformat:"%H") + vcs_list_changesets=(git log --no-merges "${base_reference}..HEAD" --since="${year}-01-01T00:00:00Z" --until="${year}-12-31T23:59:59Z" --pretty=tformat:"%H") fi vcs_changeset_message=(git log -1 --pretty=tformat:"%B") # followed by ${changeset} vcs_changeset_files=(git diff-tree --no-commit-id --name-only -r) # followed by ${changeset} diff --git a/bin/update_pch.sh b/bin/update_pch.sh new file mode 100644 index 00000000000..d7871fdd753 --- /dev/null +++ b/bin/update_pch.sh @@ -0,0 +1,111 @@ +#!/bin/sh +# Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved. +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +# +# This code is free software; you can redistribute it and/or modify it +# under the terms of the GNU General Public License version 2 only, as +# published by the Free Software Foundation. +# +# This code is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +# version 2 for more details (a copy is included in the LICENSE file that +# accompanied this code). +# +# You should have received a copy of the GNU General Public License version +# 2 along with this work; if not, write to the Free Software Foundation, +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +# +# Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA +# or visit www.oracle.com if you need additional information or have any +# questions. + +# The output of this script may require some degree of human curation: +# - Redundant headers, e.g. both x.hpp, x.inline.hpp are included; +# - Headers relative to a non-default feature should be protected by an +# appropriate 'if' clause to make sure all variants can build without +# errors. + +source_path="$(dirname ${0})" +this_script_dir="$(cd -- "${source_path}" > /dev/null && pwd)" +if test -z "${this_script_dir}"; then + echo "Error: Could not determine location of this script" + exit 1 +fi + +# Work in top directory +cd $this_script_dir/.. + +# Time threshold for header compilation, if the time exceeds the +# threshold the header will be precompiled. +if [ -z "$MIN_MS" ]; then + MIN_MS=100000 +fi + +if [ -z "$CLEAN" ]; then + CLEAN=true +elif [ "$CLEAN" != "true" ] && [ "$CLEAN" != "false" ]; then + echo "Expected either 'true' or 'false' for CLEAN" +fi + +# CBA_PATH should point to a valid ClangBuildAnalyzer executable. +# Build steps: +# git clone --depth 1 git@github.com:aras-p/ClangBuildAnalyzer.git +# cd ClangBuildAnalyzer +# make -f projects/make/Makefile +if [ -z "$CBA_PATH" ]; then + CBA_PATH="./ClangBuildAnalyzer/build/ClangBuildAnalyzer" +fi + +set -eux + +PRECOMPILED_HPP="src/hotspot/share/precompiled/precompiled.hpp" +CBA_CONFIG="ClangBuildAnalyzer.ini" +TIMESTAMP="$(date +%Y%m%d-%H%M)" +RUN_NAME="pch_update_$TIMESTAMP" +CBA_OUTPUT="cba_out_$TIMESTAMP" + +if [ "$CLEAN" = "true" ]; then + trap 'rm -rf "build/'"$RUN_NAME"'" "$CBA_OUTPUT" "$CBA_CONFIG"' EXIT +fi + +sh configure --with-toolchain-type=clang \ + --with-conf-name="$RUN_NAME" \ + --disable-precompiled-headers \ + --with-extra-cxxflags="-ftime-trace" \ + --with-extra-cflags="-ftime-trace" + +make clean CONF_NAME="$RUN_NAME" +make hotspot CONF_NAME="$RUN_NAME" +"$CBA_PATH" --all "./build/$RUN_NAME/hotspot/variant-server/libjvm/objs" \ + "$CBA_OUTPUT" + +# Preserve license and comments on top +cat "$PRECOMPILED_HPP" | awk '/^#include/ {exit} {print}' > "$PRECOMPILED_HPP.tmp" + +if [ ! -f "$CBA_CONFIG" ]; then +cat < "$CBA_CONFIG" +[counts] +header=100 +headerChain=0 +template=0 +function=0 +fileCodegen=0 +fileParse=0 + +[misc] +onlyRootHeaders=true +EOF +fi + +"$CBA_PATH" --analyze "$CBA_OUTPUT" | \ + grep " ms: " | \ + # Keep the headers more expensive than ${1}ms + awk -v x="$MIN_MS" '$1 < x { exit } { print $3 }' | \ + # Filter away non-hotspot headers + grep hotspot/share | \ + awk -F "hotspot/share/" '{ printf "#include \"%s\"\n", $2 }' \ + >> "$PRECOMPILED_HPP.tmp" +mv "$PRECOMPILED_HPP.tmp" "$PRECOMPILED_HPP" + +java test/hotspot/jtreg/sources/SortIncludes.java --update "$PRECOMPILED_HPP" diff --git a/doc/building.html b/doc/building.html index f7af2648592..99eb3e0c473 100644 --- a/doc/building.html +++ b/doc/building.html @@ -1451,10 +1451,10 @@ of a cross-compiling toolchain and a sysroot environment which can easily be used together with the --with-devkit configure option to cross compile the JDK. On Linux/x86_64, the following command:

-
bash configure --with-devkit=<devkit-path> --openjdk-target=ppc64-linux-gnu && make
-

will configure and build the JDK for Linux/ppc64 assuming that -<devkit-path> points to a Linux/x86_64 to Linux/ppc64 -devkit.

+
bash configure --with-devkit=<devkit-path> --openjdk-target=ppc64le-linux-gnu && make
+

will configure and build the JDK for Linux/ppc64le assuming that +<devkit-path> points to a Linux/x86_64 to +Linux/ppc64le devkit.

Devkits can be created from the make/devkit directory by executing:

make [ TARGETS="<TARGET_TRIPLET>+" ] [ BASE_OS=<OS> ] [ BASE_OS_VERSION=<VER> ]
@@ -1481,10 +1481,10 @@ following targets are known to work:

arm-linux-gnueabihf -ppc64-linux-gnu +ppc64le-linux-gnu -ppc64le-linux-gnu +riscv64-linux-gnu s390x-linux-gnu diff --git a/doc/building.md b/doc/building.md index 32c6ae46540..047255d1848 100644 --- a/doc/building.md +++ b/doc/building.md @@ -1258,11 +1258,11 @@ toolchain and a sysroot environment which can easily be used together with the following command: ``` -bash configure --with-devkit= --openjdk-target=ppc64-linux-gnu && make +bash configure --with-devkit= --openjdk-target=ppc64le-linux-gnu && make ``` -will configure and build the JDK for Linux/ppc64 assuming that `` -points to a Linux/x86_64 to Linux/ppc64 devkit. +will configure and build the JDK for Linux/ppc64le assuming that `` +points to a Linux/x86_64 to Linux/ppc64le devkit. Devkits can be created from the `make/devkit` directory by executing: @@ -1281,8 +1281,8 @@ at least the following targets are known to work: | x86_64-linux-gnu | | aarch64-linux-gnu | | arm-linux-gnueabihf | -| ppc64-linux-gnu | | ppc64le-linux-gnu | +| riscv64-linux-gnu | | s390x-linux-gnu | `BASE_OS` must be one of `OL` for Oracle Enterprise Linux or `Fedora`. If the diff --git a/doc/hotspot-style.html b/doc/hotspot-style.html index dafd29d6f54..f1c25dab7f4 100644 --- a/doc/hotspot-style.html +++ b/doc/hotspot-style.html @@ -50,6 +50,9 @@ id="toc-factoring-and-class-design">Factoring and Class Design
  • Commenting
  • Macros
  • Whitespace
    • +
  • Avoid implicit conversions +to bool
  • Miscellaneous
    • @@ -72,28 +75,78 @@ Standard Library Deduction
  • Expression SFINAE
    • +
  • Trailing return type +syntax for functions
    • +
  • Non-type template parameter +values
  • enum
  • alignas
  • thread_local
  • nullptr
  • <atomic>
    • +
  • Variable Templates and +Inline Variables
  • Initializing variables with static storage duration
  • Uniform Initialization
    • +
  • Mandatory Copy Elision
  • Local Function Objects
  • Inheriting constructors
  • Attributes
  • noexcept
    • +
  • Enhanced selection +statements
    • +
  • Expression Evaluation +Order
    • +
  • Compatibility with C11
  • Additional Permitted Features
    • +
  • Excluded +Features +
  • Undecided +Features +
    • @@ -209,6 +262,16 @@ lines of code. Name what you must repeat.

    attribute, the change should be done with a "setter" accessor matched to the simple "getter".

    +

    Conventions for Lock-free +Code

    +

    Sometimes variables are accessed concurrently without appropriate +synchronization context, such as a held mutex or at a safepoint. In such +cases the variable should be declared volatile and it +should NOT be accessed as a normal C++ lvalue. Rather, access should be +performed via functions from Atomic, such as +Atomic::load, Atomic::store, etc.

    +

    This special formulation makes it more clear to maintainers that the +variable is accessed concurrently in a lock-free manner.

    Source Files

    • All source files must have a globally unique basename. The build @@ -408,22 +471,25 @@ adjust new lines horizontally to be consistent with that organization. (E.g., trailing backslashes on long macro definitions often align.)

    -

    Miscellaneous

    -
      -

    • Use the Resource Acquisition Is -Initialization (RAII) design pattern to manage bracketed critical -sections. See class ResourceMark for an example.

      • -

    • Avoid implicit conversions to bool.

      +

      Avoid implicit conversions +to bool

      • Use bool for boolean values.
      • Do not use ints or pointers as (implicit) booleans with &&, ||, if, while. Instead, compare explicitly, i.e. if (x != 0) or if (ptr != nullptr), etc.
        • -
      • Do not use declarations in condition forms, i.e. don't use -if (T v = value) { ... }.
        • -
      • +
    • Do not use non-boolean declarations in condition forms, +i.e. don't use if (T v = value) { ... }. But see Enhanced selection +statements.
      • +
    +

    Miscellaneous

    +
      +

    • Use the Resource Acquisition Is +Initialization (RAII) design pattern to manage bracketed critical +sections. See class ResourceMark for an example.

    • 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: @@ -435,16 +501,16 @@ default case. It is ok to have an empty default with comment.

    Use of C++ Features

    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 +More recently, support for C++17 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.)

    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 +C++11, C++14, and C++17 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.

    (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 @@ -453,9 +519,9 @@ is the main defense against this.)

    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.

    -

    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 +

    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 description.

    +

    * Function return type +deduction (n3638)
    Only use if the function body has a very small number of return -statements, and generally relatively little other code.

    +statements, and generally relatively little other code.

    +
      +
    • Class template argument deduction (n3602, p0091r3)
      The template arguments +of a class template may be deduced from the arguments to a constructor. +This is similar to ordinary function argument deduction, though partial +deduction with only some template arguments explicitly provided +is not permitted for class template argument deduction. Deduction guides +may be used to provide additional control over the deduction. As with +auto variable declarations, excessive use can make code +harder to understand, because explicit type information is lacking. But +it can also remove the need to be explicit about types that are either +obvious, or that are very hard to write. For example, these allow the +addition of a scope-guard mechanism with nice syntax; something like +this
      • +
    +
      ScopeGuard guard{[&]{ ... cleanup code ... }};
    +

    • Also see lambda expressions.

      • +

    • decltype(auto) should be avoided, whether for +variables, for non-type template parameters, or for function return +types. There are subtle and complex differences between this placeholder +type and auto. Any use would need very careful +explanation.

    Expression SFINAE

    https://gcc.gnu.org/bugzilla/show_bug.cgi?id=95468
    https://developercommunity.visualstudio.com/content/problem/396562/sizeof-deduced-type-is-sometimes-not-a-constant-ex.html

    +

    Trailing return type +syntax for functions

    +

    A function's return type may be specified after the parameters and +qualifiers (n2541). +In such a declaration the normal return type is auto and +the return type is indicated by -> followed by the type. +Although both use auto in the "normal" leading return type +position, this differs from function return type +deduction, in that the return type is explicit rather than deduced, +but specified in a trailing position.

    +

    Use of trailing return types is permitted. However, the normal, +leading position for the return type is preferred. A trailing return +type should only be used where it provides some benefit. Such benefits +usually arise because a trailing return type is in a different scope +than a leading return type.

    +
      +

    • If the function identifier is a nested name specifier, then the +trailing return type occurs in the nested scope. This may permit simpler +naming in the return type because of the different name lookup +context.

      • +

    • The trailing return type is in the scope of the parameters, +making their types accessible via decltype. For +example

      • +
    +
    template<typename T, typename U> auto add(T t, U u) -> decltype(t + u);
    +

    rather than

    +
    template<typename T, typename U> decltype((*(T*)0) + (*(U*)0)) add(T t, U u);
    +
      +
    • Complex calculated leading return types may obscure the normal +syntactic boundaries, making it more difficult for a reader to find the +function name and parameters. This is particularly common in cases where +the return type is being used for SFINAE. A trailing +return type may be preferable in such situations.
      • +
    +

    Non-type template parameter +values

    +

    C++17 extended the arguments permitted for non-type template +parameters (n4268). The kinds of +values (the parameter types) aren't changed. However, the values can now +be the result of arbitrary constant expressions (with a few restrictions +on the result), rather than a much more limited and restrictive set of +expressions. In particular, the argument for a pointer or reference type +parameter can now be the result of a constexpr function.

    enum

    Where appropriate, scoped-enums should be used. (n2347)

    @@ -795,6 +938,41 @@ differ from what the Java compilers implement.

    "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.

    +

    Variable Templates and +Inline Variables

    +

    The use of variable templates (including static data member +templates) (N3651) is permitted. +They provide parameterized variables and constants in a simple and +direct form, instead of requiring the use of various workarounds.

    +

    Variables with static storage duration and variable templates may be +declared inline (p0386r2), and this usage is +permitted. This has similar effects as for declaring a function inline: +it can be defined, identically, in multiple translation units, must be +defined in every translation unit in which it is ODR used, and the behavior of the +program is as if there is exactly one variable.

    +

    Declaring a variable inline allows the complete definition to be in a +header file, rather than having a declaration in a header and the +definition in a .cpp file. The guidance on initialization +of such variables still applies. Inline variables with dynamic +initializations can make initialization order problems worse. The few +ordering constraints that exist for non-inline variables don't apply, as +there isn't a single program-designated translation unit containing the +definition.

    +

    A constexpr static data member or static data member +template is implicitly inline. As a consequence, an ODR use of such a member doesn't require +a definition in some .cpp file. (This is a change from pre-C++17. +Beginning with C++17, such a definition is considered a duplicate +definition, and is deprecated.)

    +

    Declaring a thread_local variable template or +inline variable is forbidden in HotSpot code. The use of thread_local is already +heavily restricted.

    Initializing variables with static storage duration

    @@ -846,6 +1024,45 @@ initialization

    Although related, the use of std::initializer_list remains forbidden, as part of the avoidance of the C++ Standard Library in HotSpot code.

    +

    Mandatory Copy Elision

    +

    Copy elision +(or here) +is a compiler optimization used to avoid potentially expensive copies in +certain situations. It is critical to making practical the performance +of return by value or pass by value. It is also unusual in not following +the as-if rule for optimizations - copy elision can be applied even if +doing so bypasses side-effects of copying/moving the object. The C++ +standard explicitly permits this.

    +

    However, because it's an optional optimization, the relevant +copy/move constructor must be available and accessible, in case the +compiler chooses to not apply the optimization even in a situation where +permitted.

    +

    C++17 changed some cases of copy elision so that there is never a +copy/move in these cases (p0135r1). The interesting cases +involve a function that returns an unnamed temporary object, and +constructors. In such cases the object being initialized from the +temporary is always direct initialized, with no copy/move ever involved; +see RVO and more specifically URVO.

    +

    Since this is now standard behavior it can't be avoided in the +covered situations. This could change the behavior of code that relied +on side effects by constructors, but that's both uncommon and was +already problematic because of the previous optional copy elision. But +HotSpot code can, and should, explicitly take advantage of this newly +required behavior where it makes sense to do so.

    +

    For example, it may be beneficial to delay construction of the result +of a function until the return statement, rather than having a local +variable that is modified into the desired state and then returned. +(Though NRVO may apply in that +case.)

    +

    It is also now possible to define a factory function for a class that +is neither movable nor copyable, if it can be written in a way that +makes use of this feature.

    Local Function Objects

    • Local function objects, including lambda expressions, may be @@ -918,6 +1135,13 @@ href="https://en.wikipedia.org/wiki/Partial_application" title="Partial Application">partial application. Again here, lambdas are typically much simpler and less verbose than function object classes.

      +

      A lambda is a constexpr function if either the parameter declaration +clause is followed by constexpr, or it satisfies the +requirements for a constexpr function (p0170r1). +Thus, using a lambda to package up some computation doesn't incur +unnecessary overhead or prevent use in a context required to be +compile-time evaluated (such as an array size).

      Because of these benefits, lambda expressions are permitted in HotSpot code, with some restrictions and usage guidance. An anonymous lambda is one which is passed directly as an argument. A named lambda is @@ -965,6 +1189,18 @@ making the captured value unaffected by modifications to the outer variable. But this only applies to captured auto variables, not member variables, and is inconsistent with referential transparency.

    +

  • By-value capture of this (using a capture list like +[*this] (p0018r3)) +is also not permitted. One of the motivating use-cases is when the +lifetime of the lambda exceeds the lifetime of the object for the +containing member function. That is, we have an upward lambda that is +capturing this of the enclosing method. But again, that +use-case doesn't apply if only downward lambdas are used. Another +use-case is when we simply want the lambda to be operating on a copy of +this for some reason. This is sufficiently uncommon that it +can be handled by manual copying, so readers don't need to understand +this rare syntax.

  • Non-capturing lambdas (with an empty capture list - []) have limited utility. There are cases where no captures are required (pure functions, for example), but if the function is small @@ -974,14 +1210,15 @@ href="https://isocpp.org/files/papers/N3649.html">N3649) are not permitted. Capture initializers inherently increase the complexity of the capture list, and provide little benefit over an additional in-scope local variable.

    • - -

    The use of mutable lambda expressions is forbidden +

  • The use of mutable lambda expressions is forbidden because there don't seem to be many, if any, good use-cases for them in HotSpot. A lambda expression needs to be mutable in order to modify a by-value captured value. But with only downward lambdas, such usage seems likely to be rare and complicated. It is better to use a function object class in any such cases that arise, rather than requiring all -HotSpot developers to understand this relatively obscure feature.

    +HotSpot developers to understand this relatively obscure +feature.

    • +

    While it is possible to directly invoke an anonymous lambda expression, that feature should not be used, as such a form can be confusing to readers. Instead, name the lambda and call it by name.

    @@ -1099,23 +1336,12 @@ href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2540.htm">n2540C++11 provides simple syntax allowing a class to inherit the constructors of a base class. Unfortunately there are a number of problems with the original specification, and C++17 contains significant -revisions (p0136r1 opens with a list of 8 Core Issues). Since -HotSpot doesn't support use of C++17, use of inherited constructors -could run into those problems. Such uses might also change behavior in a -future HotSpot update to use C++17 or later, potentially in subtle ways -that could lead to hard to diagnose problems. Because of this, HotSpot -code must not use inherited constructors.

    -

    Note that gcc7 provides the -fnew-inheriting-ctors -option to use the p0136r1 semantics. This is enabled by default when -using C++17 or later. It is also enabled by default for -fabi-version=11 (introduced by gcc7) or higher when using -C++11/14, as the change is considered a Defect Report that applies to -those versions. Earlier versions of gcc don't have that option, and -other supported compilers may not have anything similar.

    +revisions (p0136r1 +opens with a list of 8 Core Issues). Although those issues have been +addressed, the benefits from this feature are small compared to the +complexity. Because of this, HotSpot code must not use inherited +constructors.

    +

    p0195r0

    Attributes

    The use of some attributes (n2761) @@ -1131,9 +1357,17 @@ those cases HotSpot has a preferred location.

    beginning of the function's declaration, rather than between the function name and the parameter list. +

    p0068r0 is the initial +proposal for the attributes added by C++17.)

    Only the following attributes are permitted:

    The following attributes are expressly forbidden:

      @@ -1141,6 +1375,23 @@ function name and the parameter list. memory_order_consume.
    • [[deprecated]] - Not relevant in HotSpot code.
    +

    Direct use of non-standard (and presumably scoped) attributes in +shared code is also forbidden. Using such would depend on the C++17 +feature that an attribute not recognized by the implementation is +ignored (p0283r2). If such an +attribute is needed in shared code, the well-established technique of +providing an ATTRIBUTE_XXX macro with per-compiler +definitions (sometimes empty) should be used. Compilers may warn about +unrecognized attributes (whether by name or by location), in order to +report typos or misuse. Disabling such warnings globally would not be +desirable.

    +

    The use of using directives in attribute lists is also +forbidden. (p0028r0) (p0028r4) We don't generally use +scoped attributes in attribute lists with other attributes. Rather, uses +of scoped attributes (which are implementation defined) are generally +hidden behind a portability macro that includes the surrounding +brackets.

    noexcept

    Use of noexcept exception specifications (n3050) are permitted with restrictions @@ -1190,9 +1441,72 @@ Standard Library facilities.

    functions not declared noexcept. So HotSpot code doesn't ever need to check, either with conditional exception specifications or with noexcept expressions.

    +

    The exception specification is part of the type of a function (p0012r1. This likely has little +impact on HotSpot code, since the use of noexcept is +expected to be rare.

    Dynamic exception specifications were deprecated in C++11. C++17 removed all but throw(), with that remaining a deprecated equivalent to noexcept.

    +

    Enhanced selection +statements

    +

    C++17 modified the condition part of if and +switch statements, permitting an init-statement to +be included (p0305r1).

    +

    Use of this feature is permitted. (However, complex uses may +interfere with readability.) Limiting the scope of a variable involved +in the condition, while also making the value available to the +statement's body, can improve readability. The alternative method of +scope-limiting by introducing a nested scope isn't very popular and is +rarely used.

    +

    This new syntax is in addition to the condition being a +declaration with a brace-or-equal-initializer. For an +if statement this new sytax gains that benefit without +violating the long-standing guidance against using implicit conversions to +bool, which still stands.

    +

    For example, uses of Unified Logging sometimes explicitly check +whether a LogTarget is enabled. Instead of

    +
      LogTarget(...) lt;
+  if (lt.is_enabled()) {
+    LogStream log(lt);
+    ... use log ...
+  }
+  ... lt is accessible but probably not needed here ...
    +

    using this feature one could write

    +
      if (LogTarget(...) lt; lt.is_enabled()) {
+    LogStream log(lt);
+    ... use log ...
+  }
    +

    C++17 also added compile-time if statements (p0292r2). Use of +if constexpr is permitted. This feature can replace and +(sometimes vastly) simplify many uses of SFINAE. The same +declaration and initialization guidance for the condition part +apply here as for ordinary if statements.

    +

    Expression Evaluation Order

    +

    C++17 tightened up the evaluation order for some kinds of +subexpressions (p0138r2). Note, +however, that the Alternate Evaluation Order for Function Calls +alternative in that paper was adopted, rather than the strict left to +right order of evaluation for function call arguments that was proposed +in the main body of the paper.

    +

    The primary purpose of this change seems to be to make certain kinds +of call chaining well defined. That's not a style widely used in +HotSpot. In general it is better to continue to avoid questions in this +area by isolating operations with side effects from other statements. In +particular, continue to avoid modifying a value in an expression where +it is also used.

    +

    Compatibility with C11

    +

    C++17 refers to C11 rather than C99. This means that C11 libraries +and functions may be used in HotSpot. There may be limitations because +of differing levels of compatibility among various compilers and +versions of those compilers.

    +

    Note that the C parts of the JDK have been built with C11 selected +for some time (JDK-8292008).

    Additional Permitted Features

      @@ -1208,8 +1522,10 @@ href="https://isocpp.org/files/papers/n3778.html">n3778)

      href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2242.pdf">n2242) (n2555)

      -

    • Static assertions (n1720)

      • +

    • Static assertions (n1720) +(n3928)
      Both the original +(C++11) two-argument form and the new (C++17) single-argument form are +permitted.

    • decltype (n2343) (n2930< href="https://en.cppreference.com/w/cpp/language/range-for">range-for)

    • Unrestricted Unions (n2544)

      • +

    • Preprocessor Condition __has_include (p0061r0) (p0061r1)

      • +

    • Hexadecimal Floating-Point Literals (p0245r1)

      • +

    • Construction Rules for enum class Values (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 +uses.

    -

    Excluded Features

    +

    Excluded Features

    +

    Structured Bindings

    +

    The use of structured bindings p0217r3 is forbidden. Preferred +approaches for handling functions with multiple return values +include

    +
      +

    • Return a named class/struct intended for that purpose, with named +and typed members/accessors.

      • +

    • Return a value along with out parameters (usually pointers, +sometimes references).

      • +

    • Designate a sentinel "failure" value in the normal return value +type, with some out of band location for additional information. For +example, this is the model typically used with errno, where +a function returns a normal result, or -1 to indicate an error, with +additional error information in errno.

      • +
    +

    There is a strong preference for names and explicit types, as opposed +to offsets and implicit types. For example, there are folks who strongly +dislike that some of the Standard Library functions return +std::pair because first and +second members don't carry any useful information.

    +

    File System Library

    +

    The use of the File System library is forbidden. HotSpot doesn't do +very much with files, and already has adequate mechanisms for its needs. +Rewriting in terms of this new library doesn't provide any obviously +significant benefits. Having a mix of the existing usage and uses of +this new library would be confusing.

    +

    n4100 p0218r0 p0219r1 p0317r1 p0392r0 p0430r2 p0492r2 p1164r1

    +

    Aggregate Extensions

    +

    Aggregates with base classes are forbidden. C++17 allows aggregate +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

    • New string and character literals

        @@ -1285,22 +1655,234 @@ useful.

        operator overloading is used, ensure the semantics conform to the normal expected behavior of the operation.

      • Avoid most implicit conversion constructors and (implicit or -explicit) conversion operators. (Note that conversion to -bool isn't needed in HotSpot code because of the "no -implicit boolean" guideline.)

        • +explicit) conversion operators. Conversion to bool +operators aren't needed because of the no implicit boolean +guideline.)

      • Avoid goto statements.

        • +

      • Attributes for namespaces and enumerators (n4266 — The only applicable attribute +is [[deprecated]], which is +forbidden.

        • +

      • Variadic using declarations (p0195r2)

        • +

      • std::variant<> (p0088r3) — Even if more of the C++ +Standard Library is permitted, this class will remain forbidded. Invalid +accesses are indicated by throwing exceptions.

        • +

      • std::any (p0220r1) — Even if more of the C++ +Standard Library is permitted, this class will remain forbidden. It may +require allocation, and always uses the standard allocator. It requires +RTTI.

        • +

      • std::as_const() (p0007r1) — If sufficiently useful, +HotSpot could add such a function. It would likely be added to +globalDefinitions.hpp, where there are already some similar small +utilities.

        • +

      • std::clamp() (p002501) — This function is already +provided in globalDefinitions.hpp.

        • +

      • Parallel STL Algorithms (p0024r2) — Even if more of the C++ +Standard Library is permitted, these will remain forbidden. They are +built on the standard C++ threading mechanisms. HotSpot doesn't use +those mechanisms, instead providing and using its own.

        • +

      • Cache Line Sizes p0154r1 — +HotSpot has its own mechanisms for this, using values like +DEFAULT_CACHE_LINE_SIZE. The platform-specific +implementation of the HotSpot mechanisms might use these library +functions, but there is no reason to move away from the current +approach. Quoting from JOSUTTIS: "... if you know better, +use specific values, but using these values is better than any assumed +fixed size for code supporting multiple platforms."

        • +

      • register storage class removal p0001r1 — The register +storage class has been removed. register is still a +keyword, so still can't be used for normal purposes. Also, this doesn't +affect the use of register for gcc-style extended asm code; +that's a different syntactic element with a different meaning.

        • +

      • Value of __cplusplus — Testing whether +__cplusplus is defined or not is permitted, and indeed +required. But the value should not need to be examined. The value is +changed with each revision of the Standard. But we build HotSpot and +(most of) the rest of the JDK with a specifically selected version of +the Standard. The value of __cplusplus should be known and +unchanging until we change the project's build configuration again. So +examining the value shouldn't ever be necessary.

        • +

      • Removal of ++ for bool (p0003r1)

        • +

      • Removal of trigraphs (n4086)

      -

      Undecided Features

      +

      Undecided Features

      This list is incomplete; it serves to explicitly call out some features that have not yet been discussed.

      +

      Some features are undecided (so implicitly forbidden) because we +don't expect to use them at all. This might be reconsidered if someone +finds a good use case.

      +

      Some Standard Library features are undecided (so implicitly +forbidden) because, while this Style Guide forbids the use of such, they +may be sufficiently useful that we want to permit them anyway. Doing so +may require some idiomatic mechanism for addressing things like +assert incompatibility, incompatibility with HotSpot's +FORBID_C_FUNCTION mechanism, and the like.

      +

      std::optional<>

      +

      It is undecided whether to permit the use of +std::optional<> (p0220r1). It may be sufficiently +useful that it should be permitted despite the usual prohibition against +using Standard Library facilities. Use of the value() +member function must be forbidden, as it reports an invalid access by +throwing an exception.

      +

      std::byte

      +

      It is undecided whether to permit the use of the +std::byte type (p0298r3). It may be sufficiently +useful that it should be permitted despite the usual prohibition against +using Standard Library facilities.

      +

      It has been suggested that changing the HotSpot address +type to use std::byte has some benefits. That is, +replace

      +
      typedef u_char*       address;
+typedef const u_char* const_address;
      +
      using address       = std::byte*;
+using const_address = const std::byte*;
      +

      in globalDefinitions.hpp.

      +

      A specific benefit that was mentioned is that it might improve the +horrible way that gdb handles our current definition of the +address type.

      +
      #include <cstddef>
+
+typedef unsigned char* address;
+typedef std::byte* address_b;
+
+int main() {
+
+  char* mem;
+
+  address addr = (address)mem;
+  address_b addr_b = (address_b)mem;
+
+  return 0;
+}
      +
      (gdb) p addr
+$1 = (address) 0x7ffff7fe4fa0 <dl_main> "\363\017\036\372Uf\017\357\300H\211\345AWI\211\377AVAUATSH\201\354\210\002"
+(gdb) p addr_b
+$2 = (address_b) 0x7ffff7fe4fa0 <dl_main>
      +

      This needs to be explored. Some folks have said they will do so.

      +

      String Views

      +

      It is undecided whether to permit the use of +std::string_view (p0220r1).

      +

      HotSpot doesn't use std::string, but uses +char* strings a lot. Wrapping such in a +std::string_view to enable the use of various algorithms +could be useful. But since HotSpot also doesn't permit use of +<algorithm> and the like, that only gets the limited +set of algorithms provided by the view class directly.

      +

      There is also the issue of NUL termination; string views +are not necessarily NUL terminated. Moreover, if one goes +to the work of making one that is NUL terminated, that +terminator is included in the size.

      +

      There are other caveats. Permitting use of string views would require +discussion of those.

      +

      Substring and Subsequence +Searching

      +

      In addition to simple substring searching, the Standard Library now +includes Boyer-Moore and Boyer-Moore-Horspool searchers, in case someone +wants to search really large texts. That seems an unlikely use-case for +HotSpot. See p0220r1.

      +

      new and +delete with Over-Aligned Data

      +

      It is undecided whether to permit the use of dynamic allocation of +overaligned types (n3396).

      +

      HotSpot currently only has a couple of over-aligned types that are +dynamically allocated. These are handled manually, not going through +new expressions, as that couldn't work before C++17.

      +

      One of the ways an over-aligned type might arise is by aligning a +data member. This might be done to avoid destructive interference for +concurrent accesses. But HotSpot uses a different approach, using +explicit padding. Again, this is in part because new and +delete of overaligned types didn't work. But we might +prefer to continue this approach.

      +

      We would need to add operator new overloads to +CHeapObj<> and possibly in other places in order to +support this. However, it has been suggested that implementing it +(efficiently) on top of NMT might be difficult. Note that +posix_memalign / _aligned_malloc don't help +here, because of NMT's use of malloc headers.

      +

      If we don't support it we may want to add operator new +overloads that are deleted, to prevent attempted uses.

      +

      Alignment usage in non-HotSpot parts of the OpenJDK:

      +
        +

      • alignas used once in harfbuzz, to align a +variable.

        • +

      • libpipewire has #define SPA_ALIGNED macro using gcc +aligned attribute, but doesn't use it.

        • +

      • libsleef has #define ALIGNED macro using gcc +aligned attribute. It is not used for class or member +declarations.

        • +
      +

      std::to_chars() and +std::from_chars

      +

      It is undecided whether to permit the use of +std::to_chars() and std::from_chars() (p0067r5).

      +

      These functions provide low-level conversions between character +sequences and numeric values. This seems like a good candidate for use +in HotSpot, potentially replacing various clumsy or less performant +alternatives. There is no memory allocation. Parsing failures are +indicated via error codes rather than exceptions. Various other nice for +HotSpot properties.

      +

      Note that the published C++17 Standard puts these in +<utility>, but a defect report moved them to +<charconv>. This also needs +<system_error>.

      +

      This would require upgrading the minimum gcc version to 11.1 for +floating point conversion support. The minimum Visual Studio version is +already sufficient. The minimum clang version requirement hasn't been +determined yet.

      +

      std::launder()

      +

      It is undecided whether to permit the use of +std::launder() (p0137r1).

      +

      Change to permitted if we discover a place where we need it. Or maybe +we should just permit it, but hope we don't need it.

      +

      Also, C++20 revised the relevant part of Object Lifetime in a way +that seems more permissive and with less need of laundering. We don't +know if implementations of prior versions take advantage of the +difference.

      +

      See Object Lifetime: C++17 6.8/8, C++20 6.7.3/8

      +

      Additional Undecided +Features

        -

      • Trailing return type syntax for functions (n2541)

        • -

      • Variable templates (n3651)

      • Member initializers and aggregates (n3653)

      • Rvalue references and move semantics

        • +

      • Shorthand for nested namespaces (n4230) — HotSpot makes very little use +of namespaces, so this seemingly innocuous feature probably isn't useful +to us.

        • +

      • Direct list initialization with auto (n3681) — This change fixed some issues +with direct list initialization and auto. But we don't use +that feature much, if at all. And perhaps shouldn't be using +it.

        • +

      • UTF-8 Character Literals (n4267) — Do we have a use-case for +this?

        • +

      • Fold Expressions (n4295) — +Provides a simple way to apply operators to a parameter pack. HotSpot +doesn't use variadic templates very much. That makes it questionable +that developers should need to know about this feature. But if someone +does come up with a good use-case, it's likely that the alternatives are +significantly worse, because pack manipulation without this can be +complicated.

        • +

      • std::invoke<>() (n4169)

      diff --git a/doc/hotspot-style.md b/doc/hotspot-style.md index 0a0089ee454..e49f49ec1c9 100644 --- a/doc/hotspot-style.md +++ b/doc/hotspot-style.md @@ -135,6 +135,17 @@ lines of code. Name what you must repeat. change should be done with a "setter" accessor matched to the simple "getter". +#### Conventions for Lock-free Code + +Sometimes variables are accessed concurrently without appropriate synchronization +context, such as a held mutex or at a safepoint. In such cases the variable should +be declared `volatile` and it should NOT be accessed as a normal C++ lvalue. Rather, +access should be performed via functions from `Atomic`, such as `Atomic::load`, +`Atomic::store`, etc. + +This special formulation makes it more clear to maintainers that the variable is +accessed concurrently in a lock-free manner. + ### Source Files * All source files must have a globally unique basename. The build @@ -366,20 +377,22 @@ adjust new lines horizontally to be consistent with that organization. (E.g., trailing backslashes on long macro definitions often align.) +### Avoid implicit conversions to bool + +* Use `bool` for boolean values. +* Do not use ints or pointers as (implicit) booleans with `&&`, `||`, +`if`, `while`. Instead, compare explicitly, i.e. `if (x != 0)` or +`if (ptr != nullptr)`, etc. +* Do not use non-boolean declarations in _condition_ forms, i.e. don't use +`if (T v = value) { ... }`. But see +[Enhanced selection statements](#enhanced-selection-statements). + ### Miscellaneous * Use the [Resource Acquisition Is Initialization][RAII] (RAII) design pattern to manage bracketed critical sections. See class `ResourceMark` for an example. -* Avoid implicit conversions to `bool`. - * Use `bool` for boolean values. - * Do not use ints or pointers as (implicit) booleans with `&&`, `||`, - `if`, `while`. Instead, compare explicitly, i.e. `if (x != 0)` or - `if (ptr != nullptr)`, etc. - * Do not use declarations in _condition_ forms, i.e. don't use - `if (T v = value) { ... }`. - * Use functions from globalDefinitions.hpp and related files when performing bitwise operations on integers. Do not code directly as C operators, unless @@ -391,18 +404,17 @@ they are extremely simple. (Examples: `align_up`, `is_power_of_2`, * Always enumerate all cases in a switch statement or provide a default case. It is ok to have an empty default with comment. - ## Use of C++ Features HotSpot was originally written in a subset of the C++98/03 language. -More recently, support for C++14 is provided, though again, +More recently, support for C++17 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.) 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, +C++11, C++14, and C++17 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 @@ -417,9 +429,9 @@ 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. -Lists of new features for C++11 and C++14, along with links to their +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++14 Standard is the definitive +compilers and libraries. The C++17 Standard is the definitive description. * [C++ Standards Support in GCC](https://gcc.gnu.org/projects/cxx-status.html) @@ -624,13 +636,41 @@ 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. +* `auto` for non-type template parameters +([p0127r2](http://wg21.link/p0127r2))
      +`auto` may be used as a placeholder for the type of a non-type template +parameter. The type is deduced from the value provided in a template +instantiation. + + * Function return type deduction ([n3638](https://isocpp.org/files/papers/N3638.html))
      Only use if the function body has a very small number of `return` statements, and generally relatively little other code. +* Class template argument deduction +([n3602](http://wg21.link/n3602), [p0091r3](http://wg21.link/p0091r3))
      +The template arguments of a class template may be deduced from the arguments +to a constructor. This is similar to ordinary function argument deduction, +though partial deduction with only _some_ template arguments explicitly +provided is not permitted for class template argument deduction. Deduction +guides may be used to provide additional control over the deduction. As with +`auto` variable declarations, excessive use can make code harder to +understand, because explicit type information is lacking. But it can also +remove the need to be explicit about types that are either obvious, or that +are very hard to write. For example, these allow the addition of a scope-guard +mechanism with nice syntax; something like this +``` + ScopeGuard guard{[&]{ ... cleanup code ... }}; +``` + * Also see [lambda expressions](#lambdaexpressions). +* `decltype(auto)` should be avoided, whether for variables, for non-type +template parameters, or for function return types. There are subtle and +complex differences between this placeholder type and `auto`. Any use would +need very careful explanation. + ### Expression SFINAE [Substitution Failure Is Not An Error][SFINAE] (SFINAE) @@ -652,6 +692,52 @@ Here are a few closely related example bugs:

      +### Trailing return type syntax for functions + +A function's return type may be specified after the parameters and qualifiers +([n2541](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm)). +In such a declaration the normal return type is `auto` and the return type is +indicated by `->` followed by the type. Although both use `auto` in the +"normal" leading return type position, this differs from +[function return type deduction](#function-return-type-deduction), +in that the return type is explicit rather than deduced, but specified in a +trailing position. + +Use of trailing return types is permitted. However, the normal, leading +position for the return type is preferred. A trailing return type should only +be used where it provides some benefit. Such benefits usually arise because a +trailing return type is in a different scope than a leading return type. + +* If the function identifier is a nested name specifier, then the trailing +return type occurs in the nested scope. This may permit simpler naming in the +return type because of the different name lookup context. + +* The trailing return type is in the scope of the parameters, making their +types accessible via `decltype`. For example +``` +template auto add(T t, U u) -> decltype(t + u); +``` +rather than +``` +template decltype((*(T*)0) + (*(U*)0)) add(T t, U u); +``` + +* Complex calculated leading return types may obscure the normal syntactic +boundaries, making it more difficult for a reader to find the function name and +parameters. This is particularly common in cases where the return type is +being used for [SFINAE]. A trailing return type may be preferable in such +situations. + +### Non-type template parameter values + +C++17 extended the arguments permitted for non-type template parameters +([n4268](http://wg21.link/n4268)). The kinds of values (the parameter types) +aren't changed. However, the values can now be the result of arbitrary +constant expressions (with a few restrictions on the result), rather than a +much more limited and restrictive set of expressions. In particular, the +argument for a pointer or reference type parameter can now be the result of a +constexpr function. + ### enum Where appropriate, _scoped-enums_ should be used. @@ -770,6 +856,39 @@ ordering, which may differ from (may be stronger than) sequentially consistent. There are algorithms in HotSpot that are believed to rely on that ordering. +### Variable Templates and Inline Variables + +The use of variable templates (including static data member templates) +([N3651](https://wg21.link/N3651)) is permitted. They provide parameterized +variables and constants in a simple and direct form, instead of requiring the +use of various workarounds. + +Variables with static storage duration and variable templates may be declared +`inline` ([p0386r2](https://wg21.link/p0386r2)), and this usage is +permitted. This has similar effects as for declaring a function inline: it can +be defined, identically, in multiple translation units, must be defined in +every translation unit in which it is [ODR used][ODR], and the behavior of the +program is as if there is exactly one variable. + +Declaring a variable inline allows the complete definition to be in a header +file, rather than having a declaration in a header and the definition in a +.cpp file. The guidance on +[initialization](#initializing-variables-with-static-storage-duration) of such +variables still applies. Inline variables with dynamic initializations can +make initialization order problems worse. The few ordering constraints +that exist for non-inline variables don't apply, as there isn't a single +program-designated translation unit containing the definition. + +A `constexpr` static data member or static data member template +is implicitly `inline`. As a consequence, an +[ODR use][ODR] of such a member doesn't require a definition in some .cpp +file. (This is a change from pre-C++17. Beginning with C++17, such a +definition is considered a duplicate definition, and is deprecated.) + +Declaring a `thread_local` variable template or `inline` variable is forbidden +in HotSpot code. [The use of `thread_local`](#thread_local) is already +heavily restricted. + ### Initializing variables with static storage duration Variables with static storage duration and _dynamic initialization_ @@ -813,6 +932,53 @@ Some relevant sections from cppreference.com: Although related, the use of `std::initializer_list` remains forbidden, as part of the avoidance of the C++ Standard Library in HotSpot code. +### Mandatory Copy Elision + +[Copy elision](https://en.wikipedia.org/wiki/Copy_elision) +(or [here](https://cn.cppreference.com/w/cpp/language/copy_elision.html)) +is a compiler optimization used to avoid potentially expensive copies in +certain situations. It is critical to making practical the performance of +return by value or pass by value. It is also unusual in not following the +as-if rule for optimizations - copy elision can be applied even if doing so +bypasses side-effects of copying/moving the object. The C++ standard +explicitly permits this. + +However, because it's an optional optimization, the relevant copy/move +constructor must be available and accessible, in case the compiler chooses to +not apply the optimization even in a situation where permitted. + +C++17 changed some cases of copy elision so that there is never a copy/move in +these cases ([p0135r1](http://wg21.link/p0135r1)). The interesting cases +involve a function that returns an unnamed temporary object, and constructors. +In such cases the object being initialized from the temporary is always direct +initialized, with no copy/move ever involved; see [RVO] and more specifically +[URVO]. + +Since this is now standard behavior it can't be avoided in the covered +situations. This could change the behavior of code that relied on side effects +by constructors, but that's both uncommon and was already problematic because +of the previous optional copy elision. But HotSpot code can, and should, +explicitly take advantage of this newly required behavior where it makes sense +to do so. + +For example, it may be beneficial to delay construction of the result of a +function until the return statement, rather than having a local variable that +is modified into the desired state and then returned. (Though [NRVO] may apply +in that case.) + +It is also now possible to define a factory function for a class that is +neither movable nor copyable, if it can be written in a way that makes use of +this feature. + +[RVO]: https://en.wikipedia.org/wiki/Copy_elision#RVO + "Return Value Optimization" + +[NRVO]: https://en.wikipedia.org/wiki/Copy_elision#NRVO + "Named Return Value Optimization" + +[URVO]: https://cn.cppreference.com/w/cpp/language/copy_elision.html + "Unnamed Return Value Optimization" + ### Local Function Objects * Local function objects, including lambda expressions, may be used. @@ -881,6 +1047,12 @@ Another use for local functions is [partial application][PARTIALAPP]. Again here, lambdas are typically much simpler and less verbose than function object classes. +A lambda is a constexpr function if either the parameter declaration clause is +followed by `constexpr`, or it satisfies the requirements for a constexpr +function ([p0170r1]). Thus, using a lambda to package up some computation +doesn't incur unnecessary overhead or prevent use in a context required to be +compile-time evaluated (such as an array size). + Because of these benefits, lambda expressions are permitted in HotSpot code, with some restrictions and usage guidance. An anonymous lambda is one which is passed directly as an argument. A named lambda is the value of a @@ -932,6 +1104,17 @@ the most part they don't apply to HotSpot code, given other usage restrictions. applies to captured auto variables, not member variables, and is inconsistent with referential transparency. +* By-value capture of `this` (using a capture list like `[*this]` ([p0018r3])) +is also not permitted. One of the motivating use-cases is when the lifetime of +the lambda exceeds the lifetime of the object for the containing member +function. That is, we have an upward lambda that is capturing `this` of the +enclosing method. But again, that use-case doesn't apply if only downward +lambdas are used. + Another use-case is when we simply want the lambda to be operating on a copy +of `this` for some reason. This is sufficiently uncommon that it can be +handled by manual copying, so readers don't need to understand this rare +syntax. + * Non-capturing lambdas (with an empty capture list - `[]`) have limited utility. There are cases where no captures are required (pure functions, for example), but if the function is small and simple then that's obvious @@ -941,7 +1124,7 @@ anyway. Capture initializers inherently increase the complexity of the capture list, and provide little benefit over an additional in-scope local variable. -The use of `mutable` lambda expressions is forbidden because there don't +* The use of `mutable` lambda expressions is forbidden because there don't seem to be many, if any, good use-cases for them in HotSpot. A lambda expression needs to be mutable in order to modify a by-value captured value. But with only downward lambdas, such usage seems likely to be rare and @@ -1088,21 +1271,12 @@ Do not use _inheriting constructors_ C++11 provides simple syntax allowing a class to inherit the constructors of a base class. Unfortunately there are a number of problems with the original specification, and C++17 contains significant revisions ([p0136r1] opens with -a list of 8 Core Issues). Since HotSpot doesn't support use of C++17, use of -inherited constructors could run into those problems. Such uses might also -change behavior in a future HotSpot update to use C++17 or later, potentially -in subtle ways that could lead to hard to diagnose problems. Because of this, -HotSpot code must not use inherited constructors. +a list of 8 Core Issues). Although those issues have been addressed, the +benefits from this feature are small compared to the complexity. Because of +this, HotSpot code must not use inherited constructors. -Note that gcc7 provides the `-fnew-inheriting-ctors` option to use the -[p0136r1] semantics. This is enabled by default when using C++17 or later. -It is also enabled by default for `fabi-version=11` (introduced by gcc7) or -higher when using C++11/14, as the change is considered a Defect Report that -applies to those versions. Earlier versions of gcc don't have that option, -and other supported compilers may not have anything similar. - -[p0136r1]: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/p0136r1.html - "p0136r1" +[p0136r1]: http:/wg21.link/p0136r1 "p0136r1" +[p0195r0](http://wg21.link/p0195r0) ### Attributes @@ -1121,15 +1295,39 @@ preferred location. function's declaration, rather than between the function name and the parameter list. +[p0068r0](http://wg21.link/p0068r0) is the initial proposal for the attributes +added by C++17.) + Only the following attributes are permitted: * `[[noreturn]]` +* `[[nodiscard]]` ([p0189r1](http://wg21.link/p0189r1)) +* `[[maybe_unused]]` ([p0212r1](http://wg21.link/p0212r1)) +* `[[fallthrough]]` ([p0188r1](http://wg21.link/p0188)) The following attributes are expressly forbidden: * `[[carries_dependency]]` - Related to `memory_order_consume`. * `[[deprecated]]` - Not relevant in HotSpot code. +Direct use of non-standard (and presumably scoped) attributes in shared code +is also forbidden. Using such would depend on the C++17 feature that an +attribute not recognized by the implementation is ignored +([p0283r2](http://wg21.link/p0283r2)). If such an attribute is needed in +shared code, the well-established technique of providing an `ATTRIBUTE_XXX` +macro with per-compiler definitions (sometimes empty) should be +used. Compilers may warn about unrecognized attributes (whether by name or by +location), in order to report typos or misuse. Disabling such warnings +globally would not be desirable. + +The use of `using` directives in attribute lists is also forbidden. +([p0028r0](http://wg21.link/p0028r0)) +([p0028r4](http://wg21.link/p0028r4)) +We don't generally use scoped attributes in attribute lists with other +attributes. Rather, uses of scoped attributes (which are implementation +defined) are generally hidden behind a portability macro that includes the +surrounding brackets. + ### noexcept Use of `noexcept` exception specifications @@ -1178,9 +1376,79 @@ HotSpot code can assume no exceptions will ever be thrown, even from functions not declared `noexcept`. So HotSpot code doesn't ever need to check, either with conditional exception specifications or with `noexcept` expressions. +The exception specification is part of the type of a function +([p0012r1](http://wg21.link/p0012r1). This likely has little impact on HotSpot +code, since the use of `noexcept` is expected to be rare. + Dynamic exception specifications were deprecated in C++11. C++17 removed all but `throw()`, with that remaining a deprecated equivalent to `noexcept`. +### Enhanced selection statements + +C++17 modified the _condition_ part of `if` and `switch` statements, permitting +an _init-statement_ to be included +([p0305r1](http://wg21.link/p0305r1)). + +Use of this feature is permitted. (However, complex uses may interfere with +readability.) Limiting the scope of a variable involved in the condition, +while also making the value available to the statement's body, can improve +readability. The alternative method of scope-limiting by introducing a nested +scope isn't very popular and is rarely used. + +This new syntax is in addition to the _condition_ being a declaration with a +_brace-or-equal-initializer_. For an `if` statement this new sytax gains that +benefit without violating the long-standing guidance against using +[implicit conversions to `bool`](#avoid-implicit-conversions-to-bool), +which still stands. + +For example, uses of Unified Logging sometimes explicitly check whether a +`LogTarget` is enabled. Instead of +``` + LogTarget(...) lt; + if (lt.is_enabled()) { + LogStream log(lt); + ... use log ... + } + ... lt is accessible but probably not needed here ... +``` +using this feature one could write +``` + if (LogTarget(...) lt; lt.is_enabled()) { + LogStream log(lt); + ... use log ... + } +``` + +C++17 also added compile-time `if` statements +([p0292r2](http://wg21.link/p0292r2)). Use of `if constexpr` is +permitted. This feature can replace and (sometimes vastly) simplify many uses +of [SFINAE]. The same declaration and initialization guidance for the +_condition_ part apply here as for ordinary `if` statements. + +### Expression Evaluation Order + +C++17 tightened up the evaluation order for some kinds of subexpressions +([p0138r2](http://wg21.link/p0138r2)). Note, however, that the Alternate +Evaluation Order for Function Calls alternative in that paper was adopted, +rather than the strict left to right order of evaluation for function call +arguments that was proposed in the main body of the paper. + +The primary purpose of this change seems to be to make certain kinds of call +chaining well defined. That's not a style widely used in HotSpot. In general +it is better to continue to avoid questions in this area by isolating +operations with side effects from other statements. In particular, continue to +avoid modifying a value in an expression where it is also used. + +### Compatibility with C11 + +C++17 refers to C11 rather than C99. This means that C11 libraries and +functions may be used in HotSpot. There may be limitations because of +differing levels of compatibility among various compilers and versions of +those compilers. + +Note that the C parts of the JDK have been built with C11 selected for some +time ([JDK-8292008](https://bugs.openjdk.org/browse/JDK-8292008)). + ### Additional Permitted Features * `alignof` @@ -1198,7 +1466,10 @@ but `throw()`, with that remaining a deprecated equivalent to `noexcept`. ([n2555](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2555.pdf)) * Static assertions -([n1720](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html)) +([n1720](http://wg21.link/n1720)) +([n3928](http://wg21.link/n3928))
      +Both the original (C++11) two-argument form and the new (C++17) +single-argument form are permitted. * `decltype` ([n2343](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2343.pdf)) @@ -1245,7 +1516,72 @@ but `throw()`, with that remaining a deprecated equivalent to `noexcept`. * Unrestricted Unions ([n2544](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2544.pdf)) -### Excluded Features +* Preprocessor Condition `__has_include` +([p0061r0](http://wg21.link/p0061r0)) +([p0061r1](http://wg21.link/p0061r1)) + +* Hexadecimal Floating-Point Literals +([p0245r1](http://wg21.link/p0245r1)) + +* Construction Rules for `enum class` Values +([p0138r2](http://wg21.link/p0138r2)) + +* Allow `typename` in template template parameter +([n4051](http://wg21.link/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 uses. + +## Excluded Features + +### Structured Bindings + +The use of structured bindings [p0217r3](http://wg21.link/p0217r3) is +forbidden. Preferred approaches for handling functions with multiple return +values include + +* Return a named class/struct intended for that purpose, with named and typed +members/accessors. + +* Return a value along with out parameters (usually pointers, sometimes +references). + +* Designate a sentinel "failure" value in the normal return value type, with +some out of band location for additional information. For example, this is +the model typically used with `errno`, where a function returns a normal +result, or -1 to indicate an error, with additional error information in +`errno`. + +There is a strong preference for names and explicit types, as opposed to +offsets and implicit types. For example, there are folks who strongly dislike +that some of the Standard Library functions return `std::pair` because `first` +and `second` members don't carry any useful information. + +### File System Library + +The use of the File System library is forbidden. HotSpot doesn't do very much +with files, and already has adequate mechanisms for its needs. Rewriting in +terms of this new library doesn't provide any obviously significant +benefits. Having a mix of the existing usage and uses of this new library +would be confusing. + +[n4100](http://wg21.link/n4100) +[p0218r0](http://wg21.link/p0218r0) +[p0219r1](http://wg21.link/p0219r1) +[p0317r1](http://wg21.link/p0317r1) +[p0392r0](http://wg21.link/p0392r0) +[p0430r2](http://wg21.link/p0430r2) +[p0492r2](http://wg21.link/p0492r2) +[p1164r1](http://wg21.link/p1164r1) + +### Aggregate Extensions + +Aggregates with base classes are forbidden. C++17 allows aggregate +initialization for classes with base classes +([p0017r1](https://wg21.link/p0017r1)). HotSpot makes very little use of +aggregate classes, preferring explicit constructors even for very simple +classes. + +### Additional Excluded Features * New string and character literals * New character types @@ -1281,27 +1617,274 @@ operator overloading is used, ensure the semantics conform to the normal expected behavior of the operation. * Avoid most implicit conversion constructors and (implicit or explicit) -conversion operators. (Note that conversion to `bool` isn't needed -in HotSpot code because of the "no implicit boolean" guideline.) +conversion operators. Conversion to `bool` operators aren't needed +because of the +[no implicit boolean](#avoid-implicit-conversions-to-bool) +guideline.) * Avoid `goto` statements. -### Undecided Features +* Attributes for namespaces and enumerators +([n4266](http://wg21.link/n4266) — +The only applicable attribute is [`[[deprecated]]`](#attributes), which is +forbidden. + +* Variadic `using` declarations +([p0195r2](http://wg21.link/p0195r2)) + +* `std::variant<>` +([p0088r3](http://wg21.link/p0088r3)) — +Even if more of the C++ Standard Library is permitted, this class will remain +forbidded. Invalid accesses are indicated by throwing exceptions. + +* `std::any` +([p0220r1](http://wg21.link/p0220r1)) — +Even if more of the C++ Standard Library is permitted, this class will remain +forbidden. It may require allocation, and always uses the standard +allocator. It requires [RTTI]. + +* `std::as_const()` +([p0007r1](http://wg21.link/p0007r1)) — +If sufficiently useful, HotSpot could add such a function. It would likely be +added to globalDefinitions.hpp, where there are already some similar small +utilities. + +* `std::clamp()` +([p002501](http://wg21.link/p002501)) — +This function is already provided in globalDefinitions.hpp. + +* Parallel STL Algorithms +([p0024r2](http://wg21.link/p0024r2)) — +Even if more of the C++ Standard Library is permitted, these will remain +forbidden. They are built on the standard C++ threading mechanisms. HotSpot +doesn't use those mechanisms, instead providing and using its own. + +* Cache Line Sizes +[p0154r1](http://wg21.link/p0154r1) — +HotSpot has its own mechanisms for this, using values like +`DEFAULT_CACHE_LINE_SIZE`. The platform-specific implementation of the HotSpot +mechanisms might use these library functions, but there is no reason to move +away from the current approach. Quoting from [JOSUTTIS]: "... if you know better, +use specific values, but using these values is better than any assumed fixed +size for code supporting multiple platforms." + +* `register` storage class removal +[p0001r1](http://wg21.link/p0001r1) — +The `register` storage class has been removed. `register` is still a keyword, +so still can't be used for normal purposes. Also, this doesn't affect the use +of `register` for gcc-style extended asm code; that's a different syntactic +element with a different meaning. + +* Value of `__cplusplus` — +Testing whether `__cplusplus` is defined or not is permitted, and indeed +required. But the value should not need to be examined. The value is changed +with each revision of the Standard. But we build HotSpot and (most of) the +rest of the JDK with a specifically selected version of the Standard. The +value of `__cplusplus` should be known and unchanging until we change the +project's build configuration again. So examining the value shouldn't ever be +necessary. + +* Removal of `++` for `bool` +([p0003r1](http://wg21.link/p0003r1)) + +* Removal of trigraphs +([n4086](http://wg21.link/n4086)) + +## Undecided Features This list is incomplete; it serves to explicitly call out some features that have not yet been discussed. -* Trailing return type syntax for functions -([n2541](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2541.htm)) +Some features are undecided (so implicitly forbidden) because we don't expect +to use them at all. This might be reconsidered if someone finds a good use +case. -* Variable templates -([n3651](https://isocpp.org/files/papers/N3651.pdf)) +Some Standard Library features are undecided (so implicitly forbidden) +because, while this Style Guide forbids the use of such, they may be +sufficiently useful that we want to permit them anyway. Doing so may require +some idiomatic mechanism for addressing things like `assert` incompatibility, +incompatibility with HotSpot's `FORBID_C_FUNCTION` mechanism, and the like. + +### std::optional<> + +It is undecided whether to permit the use of `std::optional<>` +([p0220r1](http://wg21.link/p0220r1)). It may be sufficiently useful that it +should be permitted despite the usual prohibition against using Standard +Library facilities. Use of the `value()` member function must be forbidden, as +it reports an invalid access by throwing an exception. + +### std::byte + +It is undecided whether to permit the use of the `std::byte` type +([p0298r3](http://wg21.link/p0298r3)). It may be sufficiently useful that it +should be permitted despite the usual prohibition against using Standard +Library facilities. + +It has been suggested that changing the HotSpot `address` type to use +`std::byte` has some benefits. That is, replace +``` +typedef u_char* address; +typedef const u_char* const_address; +``` +``` +using address = std::byte*; +using const_address = const std::byte*; +``` +in globalDefinitions.hpp. + +A specific benefit that was mentioned is that it might improve the horrible +way that gdb handles our current definition of the `address` type. +``` +#include + +typedef unsigned char* address; +typedef std::byte* address_b; + +int main() { + + char* mem; + + address addr = (address)mem; + address_b addr_b = (address_b)mem; + + return 0; +} +``` + +``` +(gdb) p addr +$1 = (address) 0x7ffff7fe4fa0 "\363\017\036\372Uf\017\357\300H\211\345AWI\211\377AVAUATSH\201\354\210\002" +(gdb) p addr_b +$2 = (address_b) 0x7ffff7fe4fa0 +``` + +This needs to be explored. Some folks have said they will do so. + +### String Views + +It is undecided whether to permit the use of `std::string_view` +([p0220r1](http://wg21.link/p0220r1)). + +HotSpot doesn't use `std::string`, but uses `char*` strings a lot. Wrapping +such in a `std::string_view` to enable the use of various algorithms could be +useful. But since HotSpot also doesn't permit use of `` and the +like, that only gets the limited set of algorithms provided by the view class +directly. + +There is also the issue of `NUL` termination; string views are not necessarily +`NUL` terminated. Moreover, if one goes to the work of making one that is +`NUL` terminated, that terminator is included in the size. + +There are other caveats. Permitting use of string views would require +discussion of those. + +### Substring and Subsequence Searching + +In addition to simple substring searching, the Standard Library now includes +Boyer-Moore and Boyer-Moore-Horspool searchers, in case someone wants to +search really large texts. That seems an unlikely use-case for HotSpot. See +[p0220r1](http://wg21.link/p0220r1). + +### `new` and `delete` with Over-Aligned Data + +It is undecided whether to permit the use of dynamic allocation of overaligned +types ([n3396](http://wg21.link/n3396)). + +HotSpot currently only has a couple of over-aligned types that are dynamically +allocated. These are handled manually, not going through `new` expressions, as +that couldn't work before C++17. + +One of the ways an over-aligned type might arise is by aligning a data member. +This might be done to avoid destructive interference for concurrent accesses. +But HotSpot uses a different approach, using explicit padding. Again, this is +in part because `new` and `delete` of overaligned types didn't work. But we +might prefer to continue this approach. + +We would need to add `operator new` overloads to `CHeapObj<>` and possibly in +other places in order to support this. However, it has been suggested that +implementing it (efficiently) on top of NMT might be difficult. Note that +`posix_memalign` / `_aligned_malloc` don't help here, because of NMT's use of +malloc headers. + +If we don't support it we may want to add `operator new` overloads that are +deleted, to prevent attempted uses. + +Alignment usage in non-HotSpot parts of the OpenJDK: + +* `alignas` used once in harfbuzz, to align a variable. + +* libpipewire has `#define SPA_ALIGNED` macro using gcc `aligned` attribute, +but doesn't use it. + +* libsleef has `#define ALIGNED` macro using gcc `aligned` attribute. It is +not used for class or member declarations. + +### `std::to_chars()` and `std::from_chars` + +It is undecided whether to permit the use of `std::to_chars()` and +`std::from_chars()` ([p0067r5](http://wg21.link/p0067r5)). + +These functions provide low-level conversions between character sequences and +numeric values. This seems like a good candidate for use in HotSpot, +potentially replacing various clumsy or less performant alternatives. There is +no memory allocation. Parsing failures are indicated via error codes rather +than exceptions. Various other nice for HotSpot properties. + +Note that the published C++17 Standard puts these in ``, but a defect +report moved them to ``. This also needs ``. + +This would require upgrading the minimum gcc version to 11.1 for floating +point conversion support. The minimum Visual Studio version is already +sufficient. The minimum clang version requirement hasn't been determined yet. + +### `std::launder()` + +It is undecided whether to permit the use of `std::launder()` +([p0137r1](http://wg21.link/p0137r1)). + +Change to permitted if we discover a place where we need it. Or maybe we +should just permit it, but hope we don't need it. + +Also, C++20 revised the relevant part of Object Lifetime in a way that seems +more permissive and with less need of laundering. We don't know if +implementations of prior versions take advantage of the difference. + +See Object Lifetime: C++17 6.8/8, C++20 6.7.3/8 + +### Additional Undecided Features * Member initializers and aggregates ([n3653](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3653.html)) * Rvalue references and move semantics +* Shorthand for nested namespaces +([n4230](http://wg21.link/n4230)) — +HotSpot makes very little use of namespaces, so this seemingly innocuous +feature probably isn't useful to us. + +* Direct list initialization with `auto` +([n3681](http://wg21.link/n3681)) — +This change fixed some issues with direct list initialization and `auto`. But +we don't use that feature much, if at all. And perhaps shouldn't be using it. + +* UTF-8 Character Literals +([n4267](http://wg21.link/n4267)) — +Do we have a use-case for this? + +* Fold Expressions +([n4295](http://wg21.link/n4295)) — +Provides a simple way to apply operators to a parameter pack. HotSpot doesn't +use variadic templates very much. That makes it questionable that developers +should need to know about this feature. But if someone does come up with a +good use-case, it's likely that the alternatives are significantly worse, +because pack manipulation without this can be complicated. + +* `std::invoke<>()` +([n4169](http://wg21.link/n4169)) + + + [ADL]: https://en.cppreference.com/w/cpp/language/adl "Argument Dependent Lookup" @@ -1319,3 +1902,6 @@ features that have not yet been discussed. [PARTIALAPP]: https://en.wikipedia.org/wiki/Partial_application "Partial Application" + +[JOSUTTIS]: https://www.cppstd17.com + "C++17: The Complete Guide" diff --git a/doc/starting-next-release.html b/doc/starting-next-release.html index 421229f9fbc..6cffdf38b0f 100644 --- a/doc/starting-next-release.html +++ b/doc/starting-next-release.html @@ -11,11 +11,8 @@ div.columns{display: flex; gap: min(4vw, 1.5em);} div.column{flex: auto; overflow-x: auto;} div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;} - /* The extra [class] is a hack that increases specificity enough to - override a similar rule in reveal.js */ - ul.task-list[class]{list-style: none;} + ul.task-list{list-style: none;} ul.task-list li input[type="checkbox"] { - font-size: inherit; width: 0.8em; margin: 0 0.8em 0.2em -1.6em; vertical-align: middle; diff --git a/doc/testing.html b/doc/testing.html index b9d1f4ed22f..89a9b1b23b7 100644 --- a/doc/testing.html +++ b/doc/testing.html @@ -72,11 +72,9 @@ id="toc-notes-for-specific-tests">Notes for Specific Tests
    • Non-US locale
    • PKCS11 Tests
      • -
  • ### Testing Ahead-of-time -Optimizations -