[GR-67680] Clearer Native Image output for how much memory it uses

* Example outputs:
  15.00GiB of memory (93.8% of system memory, using all available memory)
  15.00GiB of memory (93.8% of system memory, using all available memory, user flags: '-Xms4g')
  29.80GiB of memory (46.6% of system memory, capped at 32GB)
  13.60GiB of memory (85% of system memory because $CI set to 'true')
  13.60GiB of memory (85% of system memory because in container)
  13.60GiB of memory (85% of system memory because less than 8GiB available)
  9.00GiB of memory (56.3% of system memory, set via '-Xmx9g')
  8.00GiB of memory (50.0% of system memory, set via '-XX:MaxRAMPercentage=25 -Xms5g -Xmx8g -Xms6g')

Co-Authored-By: Betty Mann <betty.mann@oracle.com>
Co-Authored-By: Paul Wögerer <paul.woegerer@oracle.com>

Author: 3 people

docs/reference-manual/native-image/BuildOutput.md

@@ -30,7 +30,7 @@ GraalVM Native Image: Generating 'helloworld' (executable)...
  Garbage collector: Serial GC (max heap size: 80% of RAM)
 --------------------------------------------------------------------------------
 Build resources:
- - 28.45GB of memory (42.5% of system memory, using available memory)
+ - 14.69GiB of memory (47.0% of system memory, using all available memory)
  - 20 thread(s) (100.0% of 20 available processor(s), determined at start)
 [2/8] Performing analysis...  [******]                           (3.4s @ 0.40GB)
     3,297 types,   3,733 fields, and  15,247 methods found reachable
@@ -145,11 +145,13 @@ The memory limit and number of threads used by the build process.
 
 More precisely, the memory limit of the Java heap, so actual memory consumption can be higher.
 Please check the [peak RSS](#glossary-peak-rss) reported at the end of the build to understand how much memory was actually used.
-By default, the build process uses the dedicated mode (up to 85% of system memory) in containers or CI environments (when the `$CI` environment variable is set to `true`), but never more than 32GB of memory.
-Otherwise, it tries to use available memory to avoid memory pressure on developer machines (shared mode).
+The actual memory consumption can also be lower than the limit set, as the GC only commits memory that it needs.
+By default, the build process uses the dedicated mode (which uses 85% of system memory) in containers or CI environments (when the `$CI` environment variable is set to `true`), but never more than 32GB of memory.
+Otherwise, it uses shared mode, which uses the available memory to avoid memory pressure on developer machines.
 If less than 8GB of memory are available, the build process falls back to the dedicated mode.
 Therefore, consider freeing up memory if your machine is slow during a build, for example, by closing applications that you do not need.
 It is possible to override the default behavior and set relative or absolute memory limits, for example with `-J-XX:MaxRAMPercentage=60.0` or `-J-Xmx16g`.
+`Xms` (for example, `-J-Xms9g`) can also be used to ensure a minimum for the limit, if you know the image needs at least that much memory to build.
 
 By default, the build process uses all available processors to maximize speed, but not more than 32 threads.
 Use the `--parallelism` option to set the number of threads explicitly (for example, `--parallelism=4`).

substratevm/src/com.oracle.svm.driver/src/com/oracle/svm/driver/MemoryUtil.java

@@ -29,24 +29,29 @@
 import java.lang.management.ManagementFactory;
 import java.nio.file.Files;
 import java.nio.file.Paths;
-import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Function;
+import java.util.function.Supplier;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import java.util.stream.Stream;
 
 import com.oracle.svm.core.OS;
 import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.SubstrateUtil;
+import com.oracle.svm.core.util.BasedOnJDKFile;
 import com.oracle.svm.core.util.ExitStatus;
+import com.oracle.svm.driver.NativeImage.HostFlags;
 import com.oracle.svm.driver.NativeImage.NativeImageError;
 
 import jdk.jfr.internal.JVM;
+import org.graalvm.collections.Pair;
 
-class MemoryUtil {
-    private static final long KiB_TO_BYTES = 1024L;
-    private static final long MiB_TO_BYTES = 1024L * KiB_TO_BYTES;
-    private static final long GiB_TO_BYTES = 1024L * MiB_TO_BYTES;
+public final class MemoryUtil {
+    public static final long KiB_TO_BYTES = 1024L;
+    public static final long MiB_TO_BYTES = 1024L * KiB_TO_BYTES;
+    public static final long GiB_TO_BYTES = 1024L * MiB_TO_BYTES;
+    public static final long TiB_TO_BYTES = 1024L * GiB_TO_BYTES;
 
     /* Builder needs at least 512MiB for building a helloworld in a reasonable amount of time. */
     private static final long MIN_HEAP_BYTES = 512L * MiB_TO_BYTES;
@@ -61,89 +66,201 @@ class MemoryUtil {
      * Builder uses at most 32GB to avoid disabling compressed oops (UseCompressedOops).
      * Deliberately use GB (not GiB) to stay well below 32GiB when relative maximum is calculated.
      */
-    private static final long MAX_HEAP_BYTES = 32_000_000_000L;
+    public static final long MAX_HEAP_BYTES = 32_000_000_000L;
 
-    public static List<String> determineMemoryFlags(NativeImage.HostFlags hostFlags) {
-        List<String> flags = new ArrayList<>();
-        if (hostFlags.hasUseParallelGC()) {
-            // native image generation is a throughput-oriented task
-            flags.add("-XX:+UseParallelGC");
-        }
+    public static List<String> heuristicMemoryFlags(HostFlags hostFlags, List<String> memoryFlags) {
         /*
          * Use MaxRAMPercentage to allow users to overwrite max heap setting with
-         * -XX:MaxRAMPercentage or -Xmx, and freely adjust the min heap with
-         * -XX:InitialRAMPercentage or -Xms.
+         * -XX:MaxRAMPercentage or -Xmx (though determineMemoryUsageFlags will detect that case and
+         * not add any flag), and freely adjust the min heap with -XX:InitialRAMPercentage or -Xms.
          */
         if (hostFlags.hasMaxRAMPercentage()) {
-            flags.addAll(determineMemoryUsageFlags(value -> "-XX:MaxRAMPercentage=" + value));
+            return determineMemoryUsageFlags(memoryFlags, value -> "-XX:MaxRAMPercentage=" + value);
         } else if (hostFlags.hasMaximumHeapSizePercent()) {
-            flags.addAll(determineMemoryUsageFlags(value -> "-XX:MaximumHeapSizePercent=" + value.intValue()));
-        }
-        if (hostFlags.hasGCTimeRatio()) {
-            /*
-             * Optimize for throughput by increasing the goal of the total time for garbage
-             * collection from 1% to 10% (N=9). This also reduces peak RSS.
-             */
-            flags.add("-XX:GCTimeRatio=9"); // 1/(1+N) time for GC
-        }
-        if (hostFlags.hasExitOnOutOfMemoryError()) {
-            /*
-             * Let builder exit on first OutOfMemoryError to provide for shorter feedback loops.
-             */
-            flags.add("-XX:+ExitOnOutOfMemoryError");
+            return determineMemoryUsageFlags(memoryFlags, value -> "-XX:MaximumHeapSizePercent=" + value.intValue());
+        } else {
+            throw new Error("Neither -XX:MaxRAMPercentage= nor -XX:MaximumHeapSizePercent= are available");
         }
-        return flags;
     }
 
+    // A String in the memory reason to indicate that user memory flags overrode the heuristic
+    private static final String SET_VIA = ", set via '";
+
     /**
      * Returns memory usage flags for the build process. Dedicated mode uses a fixed percentage of
      * total memory and is the default in containers. Shared mode tries to use available memory to
      * reduce memory pressure on the host machine. Note that this method uses OperatingSystemMXBean,
      * which is container-aware.
      */
-    private static List<String> determineMemoryUsageFlags(Function<Double, String> toMemoryFlag) {
+    private static List<String> determineMemoryUsageFlags(List<String> memoryFlags, Function<Double, String> toMemoryFlag) {
         var osBean = (com.sun.management.OperatingSystemMXBean) ManagementFactory.getOperatingSystemMXBean();
-        final double totalMemorySize = osBean.getTotalMemorySize();
-        final double dedicatedMemorySize = totalMemorySize * DEDICATED_MODE_TOTAL_MEMORY_RATIO;
-
-        String memoryUsageReason = "unknown";
-        final boolean isDedicatedMemoryUsage;
-        if (SubstrateUtil.isCISetToTrue()) {
-            isDedicatedMemoryUsage = true;
-            memoryUsageReason = "$CI set to 'true'";
-        } else if (isContainerized()) {
-            isDedicatedMemoryUsage = true;
-            memoryUsageReason = "in container";
+        final long totalMemorySize = osBean.getTotalMemorySize();
+
+        var maxMemoryAndUsageText = maxMemoryHeuristic(totalMemorySize, SubstrateUtil.isCISetToTrue(), isContainerized(), MemoryUtil::getAvailableMemorySize, memoryFlags);
+        long maxMemory = maxMemoryAndUsageText.getLeft();
+        String memoryUsageText = maxMemoryAndUsageText.getRight();
+        String memoryUsageReason = "-D" + SubstrateOptions.BUILD_MEMORY_USAGE_REASON_TEXT_PROPERTY + "=" + memoryUsageText;
+
+        if (memoryUsageText.contains(SET_VIA)) {
+            return List.of(memoryUsageReason);
         } else {
-            isDedicatedMemoryUsage = false;
+            double maxRamPercentage = ((double) maxMemory) / totalMemorySize * 100.0;
+            String memoryFlag = toMemoryFlag.apply(maxRamPercentage);
+            return List.of(memoryFlag, memoryUsageReason);
         }
+    }
+
+    /**
+     * Returns the max memory (decided by the heuristic or by the user memory flags) in bytes and
+     * the reason.
+     */
+    public static Pair<Long, String> maxMemoryHeuristic(long totalMemorySize, boolean isCISetToTrue, boolean isContainerized, Supplier<Long> getAvailableMemorySize, List<String> memoryFlags) {
+        final long dedicatedMemorySize = (long) (totalMemorySize * DEDICATED_MODE_TOTAL_MEMORY_RATIO);
 
-        double reasonableMaxMemorySize;
-        if (isDedicatedMemoryUsage) {
-            reasonableMaxMemorySize = dedicatedMemorySize;
+        long maxMemory;
+        String reason;
+        if (isCISetToTrue) {
+            reason = "85% of system memory because $CI set to 'true'";
+            maxMemory = dedicatedMemorySize;
+        } else if (isContainerized) {
+            reason = "85% of system memory because in container";
+            maxMemory = dedicatedMemorySize;
         } else {
-            reasonableMaxMemorySize = getAvailableMemorySize();
-            if (reasonableMaxMemorySize >= MIN_AVAILABLE_MEMORY_THRESHOLD_GB * GiB_TO_BYTES) {
-                memoryUsageReason = "using available memory";
+            long availableMemorySize = getAvailableMemorySize.get();
+            if (availableMemorySize >= MIN_AVAILABLE_MEMORY_THRESHOLD_GB * GiB_TO_BYTES) {
+                reason = percentageOfSystemMemoryText(availableMemorySize, totalMemorySize) + ", using all available memory";
+                maxMemory = availableMemorySize;
             } else { // fall back to dedicated mode
-                memoryUsageReason = "less than " + MIN_AVAILABLE_MEMORY_THRESHOLD_GB + "GB of memory available";
-                reasonableMaxMemorySize = dedicatedMemorySize;
+                reason = "85%% of system memory because less than %dGiB available".formatted(MIN_AVAILABLE_MEMORY_THRESHOLD_GB);
+                maxMemory = dedicatedMemorySize;
             }
         }
 
-        if (reasonableMaxMemorySize < MIN_HEAP_BYTES) {
+        if (maxMemory < MIN_HEAP_BYTES) {
             throw new NativeImageError(
                             "There is not enough memory available on the system (got %sMiB, need at least %sMiB). Consider freeing up memory if builds are slow, for example, by closing applications that you do not need."
-                                            .formatted(reasonableMaxMemorySize / MiB_TO_BYTES, MIN_HEAP_BYTES / MiB_TO_BYTES),
+                                            .formatted(maxMemory / MiB_TO_BYTES, MIN_HEAP_BYTES / MiB_TO_BYTES),
                             null, ExitStatus.OUT_OF_MEMORY.getValue());
         }
 
-        /* Ensure max memory size does not exceed upper limit. */
-        reasonableMaxMemorySize = Math.min(reasonableMaxMemorySize, MAX_HEAP_BYTES);
+        // Ensure max memory size does not exceed upper limit
+        if (maxMemory > MAX_HEAP_BYTES) {
+            maxMemory = MAX_HEAP_BYTES;
+            reason = percentageOfSystemMemoryText(maxMemory, totalMemorySize) + ", capped at 32GB";
+        }
+
+        // Handle memory flags
+        if (!memoryFlags.isEmpty()) {
+            long newMaxMemory = determineMaxHeapBasedOnMemoryFlags(memoryFlags, maxMemory, totalMemorySize);
+            if (newMaxMemory > 0) {
+                reason = percentageOfSystemMemoryText(newMaxMemory, totalMemorySize) + SET_VIA + String.join(" ", memoryFlags) + "'";
+                maxMemory = newMaxMemory;
+            } else {
+                reason += ", user flags: '%s'".formatted(String.join(" ", memoryFlags));
+            }
+        }
+
+        double maxMemoryGiB = (double) maxMemory / GiB_TO_BYTES;
+        String memoryUsageText = "%.2fGiB of memory (%s)".formatted(maxMemoryGiB, reason);
+
+        return Pair.create(maxMemory, memoryUsageText);
+    }
+
+    static boolean isMemoryFlag(String flag) {
+        return Stream.of("-Xmx", "-Xms", "-XX:MaxRAMPercentage=", "-XX:MaximumHeapSizePercent=").anyMatch(flag::startsWith);
+    }
+
+    @BasedOnJDKFile("https://github.com/openjdk/jdk/blob/jdk-26+10/src/hotspot/share/runtime/arguments.cpp#L1530-L1532")
+    private static long determineMaxHeapBasedOnMemoryFlags(List<String> memoryFlags, long heuristicMaxMemory, long totalMemory) {
+        // Priority: Xmx, MaxRAMPercentage, MaximumHeapSizePercent
+        var xmx = getMaxMemoryFlagValue("-Xmx", memoryFlags, totalMemory);
+        var maxRAMPercentage = getMaxMemoryFlagValue("-XX:MaxRAMPercentage=", memoryFlags, totalMemory);
+        var maximumHeapSizePercent = getMaxMemoryFlagValue("-XX:MaximumHeapSizePercent=", memoryFlags, totalMemory);
+        var xms = getMaxMemoryFlagValue("-Xms", memoryFlags, totalMemory);
+        long newMaxMemory = 0;
+        if (xmx > 0) {
+            newMaxMemory = xmx;
+        } else if (maxRAMPercentage > 0) {
+            newMaxMemory = maxRAMPercentage;
+        } else if (maximumHeapSizePercent > 0) {
+            newMaxMemory = maximumHeapSizePercent;
+        }
+
+        if (newMaxMemory == 0 ? xms > heuristicMaxMemory : xms > newMaxMemory) {
+            // Xms only affects max memory if the value is higher than the current max memory value
+            newMaxMemory = xms;
+        }
+        return newMaxMemory;
+    }
+
+    private static String percentageOfSystemMemoryText(long maxMemory, long totalMemory) {
+        return "%.1f%% of system memory".formatted(toPercentage(maxMemory, totalMemory));
+    }
+
+    private static long getMaxMemoryFlagValue(String prefix, List<String> memoryFlags, long totalMemory) {
+        long max = 0;
+        for (String flag : memoryFlags) {
+            if (flag.startsWith(prefix)) {
+                long value = parseMemoryFlagValue(flag, totalMemory);
+                if (value > max) {
+                    max = value;
+                }
+            }
+        }
+        return max;
+    }
+
+    @BasedOnJDKFile("https://github.com/openjdk/jdk/blob/jdk-26+10/src/hotspot/share/utilities/parseInteger.hpp#L105-L160")
+    public static long parseMemoryFlagValue(String flag, long totalMemory) {
+        if (flag.startsWith("-Xmx") || flag.startsWith("-Xms")) {
+            String valuePart = flag.substring(4);
+            if (valuePart.isEmpty()) {
+                throw new Error("Invalid value for: " + flag);
+            }
+            char unit = valuePart.charAt(valuePart.length() - 1);
+            long multiplier = switch (unit) {
+                case 'T', 't' -> TiB_TO_BYTES;
+                case 'G', 'g' -> GiB_TO_BYTES;
+                case 'M', 'm' -> MiB_TO_BYTES;
+                case 'K', 'k' -> KiB_TO_BYTES;
+                default -> 1;
+            };
+            if (multiplier != 1) {
+                valuePart = valuePart.substring(0, valuePart.length() - 1);
+            }
+            long value = parseLongOrFlagError(flag, valuePart);
+            return value * multiplier;
+        } else if (flag.startsWith("-XX:MaxRAMPercentage=")) {
+            String valuePart = flag.substring("-XX:MaxRAMPercentage=".length());
+            double value = parseDoubleOrFlagError(flag, valuePart);
+            return (long) (value / 100.0 * totalMemory);
+        } else if (flag.startsWith("-XX:MaximumHeapSizePercent=")) {
+            String valuePart = flag.substring("-XX:MaximumHeapSizePercent=".length());
+            double value = parseLongOrFlagError(flag, valuePart);
+            return (long) (value / 100.0 * totalMemory);
+        } else {
+            throw new Error("Unknown flag: " + flag);
+        }
+    }
+
+    private static long parseLongOrFlagError(String flag, String valuePart) {
+        try {
+            return Long.parseLong(valuePart);
+        } catch (NumberFormatException e) {
+            throw new Error("Invalid value for: " + flag);
+        }
+    }
+
+    private static double parseDoubleOrFlagError(String flag, String valuePart) {
+        try {
+            return Double.parseDouble(valuePart);
+        } catch (NumberFormatException e) {
+            throw new Error("Invalid value for: " + flag);
+        }
+    }
 
-        double reasonableMaxRamPercentage = reasonableMaxMemorySize / totalMemorySize * 100;
-        return List.of(toMemoryFlag.apply(reasonableMaxRamPercentage),
-                        "-D" + SubstrateOptions.BUILD_MEMORY_USAGE_REASON_TEXT_PROPERTY + "=" + memoryUsageReason);
+    private static double toPercentage(long part, long total) {
+        return part / (double) total * 100;
     }
 
     private static boolean isContainerized() {
@@ -153,7 +270,7 @@ private static boolean isContainerized() {
         return JVM.isContainerized();
     }
 
-    private static double getAvailableMemorySize() {
+    private static long getAvailableMemorySize() {
         return switch (OS.getCurrent()) {
             case LINUX -> getAvailableMemorySizeLinux();
             case DARWIN -> getAvailableMemorySizeDarwin();

substratevm/src/com.oracle.svm.driver/src/com/oracle/svm/driver/NativeImage.java

@@ -340,6 +340,10 @@ private static <T> String oR(OptionKey<T> option) {
     BundleSupport bundleSupport;
     private final ArchiveSupport archiveSupport;
 
+    /**
+     * When running the Native Image Driver on Espresso with SVM, the available VM flags differ from
+     * those on HotSpot. This accounts for that.
+     */
     public record HostFlags(
                     boolean useJVMCINativeLibrary,
                     boolean hasUseJVMCICompiler,
@@ -348,6 +352,28 @@ public record HostFlags(
                     boolean hasExitOnOutOfMemoryError,
                     boolean hasMaximumHeapSizePercent,
                     boolean hasUseParallelGC) {
+
+        public List<String> defaultMemoryFlags() {
+            List<String> flags = new ArrayList<>();
+            if (hasUseParallelGC) {
+                // native image generation is a throughput-oriented task
+                flags.add("-XX:+UseParallelGC");
+            }
+            if (hasGCTimeRatio) {
+                /*
+                 * Optimize for throughput by increasing the goal of the total time for garbage
+                 * collection from 1% to 10% (N=9). This also reduces peak RSS.
+                 */
+                flags.add("-XX:GCTimeRatio=9"); // 1/(1+N) time for GC
+            }
+            if (hasExitOnOutOfMemoryError) {
+                /*
+                 * Let the builder exit on first OutOfMemoryError to have shorter feedback loops.
+                 */
+                flags.add("-XX:+ExitOnOutOfMemoryError");
+            }
+            return flags;
+        }
     }
 
     protected static class BuildConfiguration {
@@ -997,7 +1023,7 @@ static void ensureDirectoryExists(Path dir) {
 
     private void prepareImageBuildArgs() {
         addImageBuilderJavaArgs("-Xss10m");
-        addImageBuilderJavaArgs(MemoryUtil.determineMemoryFlags(config.getHostFlags()));
+        addImageBuilderJavaArgs(config.getHostFlags().defaultMemoryFlags());
 
         /* Prevent JVM that runs the image builder to steal focus. */
         addImageBuilderJavaArgs("-Djava.awt.headless=true");
@@ -1274,6 +1300,17 @@ private int completeImageBuild() {
 
         addImageBuilderJavaArgs(customJavaArgs.toArray(new String[0]));
 
+        List<String> userMemoryFlags = new ArrayList<>();
+        for (String arg : imageBuilderJavaArgs) {
+            if (MemoryUtil.isMemoryFlag(arg)) {
+                userMemoryFlags.add(arg);
+            }
+        }
+        List<String> memoryFlagsToAdd = MemoryUtil.heuristicMemoryFlags(config.getHostFlags(), userMemoryFlags);
+        for (String memoryFlag : memoryFlagsToAdd.reversed()) {
+            imageBuilderJavaArgs.addFirst(memoryFlag);
+        }
+
         /* Perform option consolidation of imageBuilderArgs */
 
         imageBuilderJavaArgs.addAll(getAgentArguments());