Update FastThreadLocal documentation.

Author: cstancu

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.hosted/src/com/oracle/svm/hosted/thread/VMThreadFeature.java

@@ -103,7 +103,7 @@ public void duringSetup(DuringSetupAccess config) {
      * <p>
      * When the {@link IsolateThread} is not passed in as a parameter, we use the
      * {@link LoadVMThreadLocalNode current thread}. We do not need read/write barriers since we
-     * access memory that we manage ourselfs.
+     * access memory that we manage ourselves.
      */
     @Override
     public void registerInvocationPlugins(Providers providers, Plugins plugins, ParsingReason reason) {