[GR-67940] Update documentation.

PullRequest: graal/21583

Author: cstancu

substratevm/src/com.oracle.graal.pointsto/src/com/oracle/graal/pointsto/infrastructure/SubstitutionProcessor.java

@@ -24,10 +24,22 @@
  */
 package com.oracle.graal.pointsto.infrastructure;
 
+import com.oracle.graal.pointsto.meta.AnalysisUniverse;
+
 import jdk.vm.ci.meta.ResolvedJavaField;
 import jdk.vm.ci.meta.ResolvedJavaMethod;
 import jdk.vm.ci.meta.ResolvedJavaType;
 
+/**
+ * A substitution processor is a facility that allows modifying code elements coming from class
+ * files without modifying the class files. It is queried by the {@link AnalysisUniverse} when
+ * creating the analysis model of a hosted element (type, method, field) to check if a substitution
+ * is available. How a substitution processor is implemented, i.e., when a processor decides to
+ * replace an element and how that element is constructed, is not specified. The substitution
+ * processors form a chain, created via {@link #chainUpInOrder(SubstitutionProcessor...)} and
+ * {@link #extendsTheChain(SubstitutionProcessor, SubstitutionProcessor[])} utility methods, and are
+ * queried in the order in which they were installed.
+ */
 public abstract class SubstitutionProcessor {
 
     /**
@@ -40,10 +52,24 @@ public ResolvedJavaType lookup(ResolvedJavaType type) {
         return type;
     }
 
+    /**
+     * Get the substitution of an original field.
+     *
+     * @param field the original field
+     * @return the substitution field, or the original field if it isn't covered by this
+     *         substitution
+     */
     public ResolvedJavaField lookup(ResolvedJavaField field) {
         return field;
     }
 
+    /**
+     * Get the substitution of an original method.
+     *
+     * @param method the original method
+     * @return the substitution method, or the original method if it isn't covered by this
+     *         substitution
+     */
     public ResolvedJavaMethod lookup(ResolvedJavaMethod method) {
         return method;
     }
@@ -80,7 +106,7 @@ public static SubstitutionProcessor chainUpInOrder(SubstitutionProcessor... proc
         return current;
     }
 
-    public static SubstitutionProcessor chain(SubstitutionProcessor first, SubstitutionProcessor second) {
+    private static SubstitutionProcessor chain(SubstitutionProcessor first, SubstitutionProcessor second) {
         if (first == IDENTITY) {
             return second;
         } else if (second == IDENTITY) {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/Uninterruptible.java

@@ -66,7 +66,7 @@
  * semantics. Covariant return types are not allowed when overriding a method, i.e., the base method
  * and the override must have the exact same declared return type. Covariant return types require a
  * synthetic bridge method that is generated automatically by the Java compiler, and not all Java
- * compilers put the {@link Uninterruptible} annotation on the bridge metod too (for example ECJ).
+ * compilers put the {@link Uninterruptible} annotation on the bridge method too (for example ECJ).
  * For consistency reasons, synthetic methods are therefore never treated as uninterruptible.
  * <p>
  * Annotated methods give a terse {@link #reason} why they are annotated. Often the reason is that

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/classinitialization/ClassInitializationInfo.java

@@ -51,7 +51,7 @@
 
 /**
  * Information about the runtime class initialization state of a {@link DynamicHub class}, and
- * {@link #slowPath(ClassInitializationInfo, DynamicHub)} implementation} of class initialization
+ * {@link #slowPath(ClassInitializationInfo, DynamicHub) implementation} of class initialization
  * according to the Java VM specification.
  * <p>
  * The information is not directly stored in {@link DynamicHub} because 1) the class initialization

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/jdk/Resources.java

@@ -129,6 +129,7 @@ public static Resources[] layeredSingletons() {
      * {see com.oracle.svm.hosted.ModuleLayerFeature}.
      */
     private final EconomicMap<ModuleResourceKey, ConditionalRuntimeValue<ResourceStorageEntryBase>> resources = ImageHeapMap.createNonLayeredMap();
+    /** Regexp patterns used to match names of resources to be included in the image. */
     private final EconomicMap<RequestedPattern, RuntimeConditionSet> requestedPatterns = ImageHeapMap.createNonLayeredMap();
 
     /**
@@ -152,7 +153,7 @@ public static Resources[] layeredSingletons() {
     @Platforms(Platform.HOSTED_ONLY.class) //
     private final Set<String> previousLayerPatterns;
 
-    public record RequestedPattern(String module, String resource) {
+    public record RequestedPattern(String module, String pattern) {
     }
 
     public interface ModuleResourceKey {
@@ -437,6 +438,7 @@ public void registerIncludePattern(ConfigurationCondition condition, String modu
         }
     }
 
+    @Platforms(Platform.HOSTED_ONLY.class)
     private void addPattern(RequestedPattern pattern, RuntimeConditionSet condition) {
         if (!previousLayerPatterns.contains(pattern.toString())) {
             requestedPatterns.put(pattern, condition);
@@ -451,7 +453,7 @@ private void addPattern(RequestedPattern pattern, RuntimeConditionSet condition)
 
     /*
      * This handles generated include patterns which start and end with \Q and \E. The actual
-     * resource name is located inbetween those tags.
+     * resource name is located in between those tags.
      */
     @Platforms(Platform.HOSTED_ONLY.class)
     private static String handleEscapedCharacters(String pattern) {
@@ -574,7 +576,7 @@ private static boolean missingResourceMatchesIncludePattern(String resourceName,
             MapCursor<RequestedPattern, RuntimeConditionSet> cursor = r.requestedPatterns.getEntries();
             while (cursor.advance()) {
                 RequestedPattern moduleResourcePair = cursor.getKey();
-                if (Objects.equals(moduleName, moduleResourcePair.module) && matchResource(moduleResourcePair.resource, resourceName) && cursor.getValue().satisfied()) {
+                if (Objects.equals(moduleName, moduleResourcePair.module) && matchResource(moduleResourcePair.pattern, resourceName) && cursor.getValue().satisfied()) {
                     return true;
                 }
             }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/layeredimagesingleton/ApplicationLayerOnlyImageSingleton.java

@@ -27,11 +27,18 @@
 import org.graalvm.nativeimage.ImageSingletons;
 
 import com.oracle.svm.core.SubstrateOptions;
+import com.oracle.svm.core.graal.nodes.LoadImageSingletonNode;
 import com.oracle.svm.core.option.HostedOptionValues;
 
 /**
  * Identifies a singleton for which all lookups refer to a single singleton which will be created in
  * the application layer. See {@link LayeredImageSingleton} for full explanation.
+ * <p>
+ * Referring to fields of an {@link ApplicationLayerOnlyImageSingleton} object from a code compiled
+ * in a shared layer, i.e., even before the value of the field can be known, is safe because an
+ * {@link ApplicationLayerOnlyImageSingleton} will never be constant-folded in a shared layer. It is
+ * instead implemented via {@link LoadImageSingletonNode} which is lowered to a singleton table
+ * read.
  */
 public interface ApplicationLayerOnlyImageSingleton extends LayeredImageSingleton {
 

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/threadlocal/FastThreadLocalFactory.java

@@ -33,12 +33,14 @@
 import org.graalvm.word.WordBase;
 
 /**
- * This class contains factory methods to create fast thread local variables. A thread local
+ * This class contains factory methods to create {@link FastThreadLocal} variables. A thread local
  * variable is represented as an object, with different classes for primitive {@code int} (class
  * {@link FastThreadLocalInt}), primitive {@code long} (class {@link FastThreadLocalLong}),
  * {@link Object} (class {@link FastThreadLocalObject}), and {@link WordBase word} (class
  * {@link FastThreadLocalWord}) values. Access to such thread local variables is significantly
- * faster than regular Java {@link ThreadLocal} variables. However, there are several restrictions:
+ * faster than regular Java {@link ThreadLocal} variables. This is achieved by determining all the
+ * {@link FastThreadLocal} values and their size at build time and reserving space in the
+ * {@link IsolateThread} data structure. However, there are several restrictions:
  * <ul>
  * <li>The thread local object must be created during native image generation. Otherwise, the size
  * of the {@link IsolateThread} data structure would not be a compile time constant.</li>
@@ -63,6 +65,9 @@
  * The implementation of fast thread local variables and the way the data is stored is
  * implementation specific and transparent for users of it. However, the access is fast and never
  * requires object allocation.
+ * <p>
+ * See also {@link VMThreadLocalInfo} for additional information about how a {@link FastThreadLocal}
+ * is handled during build time.
  */
 @Platforms(Platform.HOSTED_ONLY.class)
 public final class FastThreadLocalFactory {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/threadlocal/VMThreadLocalInfo.java

@@ -28,13 +28,16 @@
 
 import java.util.function.IntSupplier;
 
+import org.graalvm.nativeimage.IsolateThread;
 import org.graalvm.nativeimage.Platform;
 import org.graalvm.nativeimage.Platforms;
 import org.graalvm.word.LocationIdentity;
 import org.graalvm.word.WordBase;
 
 import com.oracle.svm.core.BuildPhaseProvider.ReadyForCompilation;
 import com.oracle.svm.core.config.ConfigurationValues;
+import com.oracle.svm.core.graal.thread.LoadVMThreadLocalNode;
+import com.oracle.svm.core.graal.thread.StoreVMThreadLocalNode;
 import com.oracle.svm.core.heap.UnknownPrimitiveField;
 
 import jdk.vm.ci.meta.JavaKind;
@@ -74,7 +77,18 @@ public static Class<?> getValueClass(Class<? extends FastThreadLocal> threadLoca
     public final boolean allowFloatingReads;
     public final String name;
 
+    /**
+     * Offset of this thread local variable from its holder thread {@link IsolateThread} data
+     * structure. It is a compile time constant, determined by collecting and sorting all thread
+     * locals, and used during lowering of {@link FastThreadLocal} specific operations, e.g.,
+     * {@link LoadVMThreadLocalNode}, {@link StoreVMThreadLocalNode} and others.
+     */
     @UnknownPrimitiveField(availability = ReadyForCompilation.class) public int offset;
+    /**
+     * How many bytes does this thread local need for storage. Just like the {@link #offset} this is
+     * a compile-time constant, determined by taking into account the {@link #storageKind} or via
+     * the {@link #sizeSupplier}, and it is used to lay out the thread locals in memory.
+     */
     @UnknownPrimitiveField(availability = ReadyForCompilation.class) public int sizeInBytes;
 
     @Platforms(Platform.HOSTED_ONLY.class)

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/util/ImageHeapMap.java

@@ -38,12 +38,17 @@
 
 /**
  * A thread-safe map implementation that optimizes its run time representation for space efficiency.
- * 
- * At image build time the map is implemented as a {@link ConcurrentHashMap} wrapped into an
- * {@link EconomicMap}. The ImageHeapMapFeature intercepts each build time map and transforms it
- * into an actual memory-efficient {@link EconomicMap} backed by a flat object array during
- * analysis. The later image building stages see only the {@link EconomicMap}.
- * 
+ * <p>
+ * At image build time the map is implemented as a {@link ConcurrentHashMap} or
+ * {@link ConcurrentIdentityHashMap} wrapped into an {@link EconomicMapWrap}. The
+ * ImageHeapCollectionFeature intercepts each build time map and transforms it into an actual
+ * memory-efficient {@link EconomicMap} backed by a flat object array during analysis. The later
+ * image building stages see only the {@link EconomicMap}.
+ * <p>
+ * Additionally, in layered builds, at run time this map can be part of a
+ * {@link LayeredImageHeapMap} structure, i.e., conceptually a linked list of {@link EconomicMap}s
+ * that spans across multiple layers.
+ * <p>
  * This map implementation allows thread-safe collection of data at image build time and storing it
  * into a space efficient data structure at run time.
  */
@@ -54,27 +59,43 @@ private ImageHeapMap() {
     }
 
     /**
-     * Create a hosted representation of an {@link ImageHeapMap}: a {@link ConcurrentHashMap}
-     * wrapped into an {@link EconomicMap}. At run time this will be an actual memory-efficient
-     * {@link EconomicMap} backed by a flat object array.
+     * In non-layered builds this creates a regular {@link ImageHeapMap} (see above).
+     * <p>
+     * In layered builds this creates a map that expands across layers. During the current layer
+     * build this is a {@link ConcurrentHashMap} wrapped by an {@link EconomicMapWrap}. At run time
+     * it is part of a {@link LayeredImageHeapMap} structure, i.e., conceptually a linked list of
+     * {@link EconomicMap}s that spans across multiple layers.
      */
     @Platforms(Platform.HOSTED_ONLY.class) //
     public static <K, V> EconomicMap<K, V> create(String key) {
         return create(Equivalence.DEFAULT, key);
     }
 
-    @Platforms(Platform.HOSTED_ONLY.class) //
-    public static <K, V> EconomicMap<K, V> createNonLayeredMap() {
-        return createNonLayeredMap(Equivalence.DEFAULT);
-    }
-
+    /**
+     * Same as {@link #create(String)}, but if the {@code strategy} is {@link Equivalence#IDENTITY}
+     * the hosted map is a {@link ConcurrentIdentityHashMap}.
+     */
     @Platforms(Platform.HOSTED_ONLY.class) //
     public static <K, V> EconomicMap<K, V> create(Equivalence strategy, String key) {
         assert key != null : "The key should not be null if the map needs to be automatically layered";
         VMError.guarantee(!BuildPhaseProvider.isAnalysisFinished(), "Trying to create an ImageHeapMap after analysis.");
         return HostedImageHeapMap.create(strategy, key, true);
     }
 
+    /**
+     * Create an {@link ImageHeapMap}. At build time it is a {@link ConcurrentHashMap} wrapped into
+     * an {@link EconomicMapWrap}. At run time this will be an actual memory-efficient
+     * {@link EconomicMap} backed by a flat object array.
+     */
+    @Platforms(Platform.HOSTED_ONLY.class) //
+    public static <K, V> EconomicMap<K, V> createNonLayeredMap() {
+        return createNonLayeredMap(Equivalence.DEFAULT);
+    }
+
+    /**
+     * Same as {@link #createNonLayeredMap()}, but if the {@code strategy} is
+     * {@link Equivalence#IDENTITY} the hosted map is a {@link ConcurrentIdentityHashMap}.
+     */
     @Platforms(Platform.HOSTED_ONLY.class) //
     public static <K, V> EconomicMap<K, V> createNonLayeredMap(Equivalence strategy) {
         VMError.guarantee(!BuildPhaseProvider.isAnalysisFinished(), "Trying to create an ImageHeapMap after analysis.");
@@ -115,12 +136,10 @@ public EconomicMap<Object, Object> getRuntimeMap() {
             return runtimeMap;
         }
 
-        public static <K, V> HostedImageHeapMap<K, V> create(Equivalence strategy, String key, boolean needLayeredMap) {
+        public static <K, V> HostedImageHeapMap<K, V> create(Equivalence strategy, String key, boolean isLayeredMap) {
             Map<K, V> hostedMap = (strategy == Equivalence.IDENTITY) ? new ConcurrentIdentityHashMap<>() : new ConcurrentHashMap<>();
             EconomicMap<Object, Object> currentLayerMap = EconomicMap.create(strategy);
-            if (!needLayeredMap || !ImageLayerBuildingSupport.buildingImageLayer()) {
-                return new HostedImageHeapMap<>(hostedMap, currentLayerMap, currentLayerMap);
-            } else {
+            if (ImageLayerBuildingSupport.buildingImageLayer() && isLayeredMap) {
                 LayeredImageHeapMap<Object, Object> runtimeMap = new LayeredImageHeapMap<>(strategy, key);
                 var previousMap = LayeredImageHeapMapStore.currentLayer().getImageHeapMapStore().put(key, currentLayerMap);
                 if (previousMap != null) {
@@ -132,6 +151,8 @@ public static <K, V> HostedImageHeapMap<K, V> create(Equivalence strategy, Strin
                     singleton.registerPreviousLayerHostedImageHeapMap(hostedImageHeapMap);
                 }
                 return hostedImageHeapMap;
+            } else {
+                return new HostedImageHeapMap<>(hostedMap, currentLayerMap, currentLayerMap);
             }
         }
     }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/util/LayeredImageHeapMapStore.java

@@ -37,6 +37,12 @@
 import com.oracle.svm.core.layeredimagesingleton.MultiLayeredImageSingleton;
 import com.oracle.svm.core.layeredimagesingleton.UnsavedSingleton;
 
+/**
+ * Per layer store for the {@link LayeredImageHeapMap}s. There exists one
+ * {@link LayeredImageHeapMapStore} per layer and each entry in the underlying
+ * {@link #imageHeapMapStore} corresponds to a specific {@link LayeredImageHeapMap}, identified by
+ * its {@link LayeredImageHeapMap#getMapKey()}.
+ */
 public class LayeredImageHeapMapStore implements MultiLayeredImageSingleton, UnsavedSingleton {
     private final Map<String, EconomicMap<Object, Object>> imageHeapMapStore = new HashMap<>();
 

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/substitute/AnnotationSubstitutionProcessor.java

@@ -48,7 +48,6 @@
 import java.util.function.Predicate;
 import java.util.function.Supplier;
 
-import com.oracle.svm.hosted.SVMHost;
 import org.graalvm.nativeimage.AnnotationAccess;
 import org.graalvm.nativeimage.ImageSingletons;
 import org.graalvm.nativeimage.Platform;
@@ -58,6 +57,7 @@
 import com.oracle.graal.pointsto.BigBang;
 import com.oracle.graal.pointsto.infrastructure.SubstitutionProcessor;
 import com.oracle.graal.pointsto.meta.AnalysisField;
+import com.oracle.graal.pointsto.meta.AnalysisUniverse;
 import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.SubstrateUtil;
 import com.oracle.svm.core.Uninterruptible;
@@ -84,8 +84,10 @@
 import com.oracle.svm.hosted.ImageClassLoader;
 import com.oracle.svm.hosted.NativeImageGenerator;
 import com.oracle.svm.hosted.NativeImageOptions;
+import com.oracle.svm.hosted.SVMHost;
 import com.oracle.svm.hosted.ameta.FieldValueInterceptionSupport;
 import com.oracle.svm.hosted.classinitialization.ClassInitializationSupport;
+import com.oracle.svm.hosted.meta.HostedUniverse;
 import com.oracle.svm.util.ReflectionUtil;
 import com.oracle.svm.util.ReflectionUtil.ReflectionUtilError;
 
@@ -94,6 +96,28 @@
 import jdk.vm.ci.meta.ResolvedJavaMethod;
 import jdk.vm.ci.meta.ResolvedJavaType;
 
+/**
+ * The main substitution processor for Native Image. The annotations supported by this processor
+ * are:
+ * <ul>
+ * <li>{@link TargetClass}</li>
+ * <li>{@link Substitute}</li>
+ * <li>{@link TargetElement}</li>
+ * <li>{@link Alias}</li>
+ * <li>{@link AnnotateOriginal}</li>
+ * <li>{@link Delete}</li>
+ * <li>{@link Inject}</li>
+ * <li>{@link InjectAccessors}</li>
+ * <li>{@link KeepOriginal}</li>
+ * <li>{@link RecomputeFieldValue}</li>
+ * </ul>
+ * Code tagged with these annotations is preprocessed during Native Image setup when the processor
+ * is {@link AnnotationSubstitutionProcessor#init(FieldValueInterceptionSupport) initialized}. Then,
+ * hosted code corresponding to the substitution code is intercepted and replaced without modifying
+ * the class files during {@link AnalysisUniverse} lookups. See each annotation's JavaDoc for more
+ * details, starting with {@link TargetClass}. See also {@link HostedUniverse} for a comprehensive
+ * description of the substitution layer.
+ */
 public class AnnotationSubstitutionProcessor extends SubstitutionProcessor {
 
     /**
@@ -306,7 +330,7 @@ public void registerUnsafeAccessedFields(BigBang bb) {
     }
 
     public void init(FieldValueInterceptionSupport newFieldValueInterceptionSupport) {
-        /**
+        /*
          * Cannot set this field in the constructor due to cyclic dependencies between the two
          * classes.
          */