Minor cleanups and improvements, and documentation.

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/thread/Continuation.java

@@ -76,7 +76,7 @@ public void setIP(CodePointer ip) {
 
     void enter() {
         int stateBefore = StackOverflowCheck.singleton().getState();
-        VMError.guarantee(!StackOverflowCheck.singleton().isYellowZoneAvailable(), "Stack overflow checks must be active when entering a continuation");
+        VMError.guarantee(!StackOverflowCheck.singleton().isYellowZoneAvailable());
 
         boolean isContinue = ip.isNonNull();
         if (isContinue) {
@@ -153,7 +153,7 @@ Integer yield() {
         ip = leafIP;
 
         KnownIntrinsics.farReturn(0, rootSP, rootIP, false);
-        throw VMError.shouldNotReachHere("value should be returned by `farReturn`");
+        throw VMError.shouldNotReachHere();
     }
 
     public boolean isStarted() {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/thread/JavaThreads.java

@@ -86,6 +86,28 @@
 
 import sun.misc.Unsafe;
 
+/**
+ * Implements operations on {@linkplain Target_java_lang_Thread Java threads}, which are on a higher
+ * abstraction level than {@link IsolateThread}s. This class distinguishes these types of threads:
+ *
+ * <ul>
+ * <li><em>Platform threads</em> are typical Java threads which correspond to an OS thread.</li>
+ * <li><em>Virtual threads</em> are light-weight threads that exist as Java objects, but are not
+ * associated with an OS thread. They are temporarily mounted (scheduled) on one or several,
+ * potentially different, platform threads.</li>
+ * <li><em>Carrier thread</em> is the term for the platform thread on which a virtual thread is
+ * currently mounted (if it is mounted). Typically there is a pool of potential carrier threads
+ * which are available to execute virtual threads.</li>
+ * </ul>
+ *
+ * Methods with <em>platform</em> or <em>carrier</em> in their names must be called <em>only</em>
+ * for that type of thread. Methods without that designation distinguish between the thread types
+ * and choose the appropriate action.
+ *
+ * @see VirtualThreads
+ * @see <a href="https://openjdk.java.net/projects/loom/">Wiki and source code of Project Loom on
+ *      which concepts of virtual threads, carrier threads, etc. are modeled</a>
+ */
 public abstract class JavaThreads {
     @Fold
     public static JavaThreads singleton() {
@@ -261,10 +283,10 @@ static boolean platformGetAndClearInterrupt(Thread thread) {
         assert !isVirtual(thread);
         /*
          * As we don't use a lock, it is possible to observe any kinds of races with other threads
-         * that try to set interrupted to true. However, those races don't cause any correctness
-         * issues as we only reset interrupted to false if we observed that it was true earlier.
-         * There also can't be any problematic races with other calls to isInterrupted as
-         * clearInterrupted may only be true if this method is being executed by the current thread.
+         * that try to set the interrupted status to true. However, those races don't cause any
+         * correctness issues as we only reset it to false if we observed that it was true earlier.
+         * There also can't be any problematic races with other calls to check the interrupt status
+         * because it is cleared only by the current thread.
          */
         return getAndWriteInterruptedFlag(thread, false);
     }

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/thread/LoomVirtualThreads.java

@@ -34,10 +34,12 @@
 import com.oracle.svm.core.util.VMError;
 
 /**
- * Code specific to virtual threads is part of the {@link Thread} methods, e.g. {@code yield} or
- * {@code sleep}, and the implementation for platform threads generally in {@code yield0} or
- * {@code sleep0}, so we only substitute this platform thread code in
- * {@link Target_java_lang_Thread}, and never expect these methods to be reachable.
+ * In a Project Loom JDK, code specific to virtual threads is part of the {@link Thread} methods,
+ * e.g. {@code yield} or {@code sleep}, and the implementation for platform threads is generally in
+ * methods named {@code yield0} or {@code sleep0}, so we only substitute that platform thread code
+ * in {@link Target_java_lang_Thread}, and generally do not expect these methods to be reachable.
+ *
+ * @see <a href="https://openjdk.java.net/projects/loom/">Project Loom (Wiki, code, etc.)</a>
  */
 final class LoomVirtualThreads implements VirtualThreads {
     private static Target_java_lang_VirtualThread cast(Thread thread) {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/thread/SubstrateVirtualThread.java

@@ -25,6 +25,7 @@
 package com.oracle.svm.core.thread;
 
 // Checkstyle: stop
+
 import static java.util.concurrent.TimeUnit.NANOSECONDS;
 
 import java.util.Locale;
@@ -37,6 +38,7 @@
 import java.util.concurrent.TimeUnit;
 
 import org.graalvm.compiler.serviceprovider.GraalUnsafeAccess;
+import org.graalvm.nativeimage.IsolateThread;
 
 import com.oracle.svm.core.annotate.Alias;
 import com.oracle.svm.core.annotate.TargetClass;
@@ -52,6 +54,13 @@
 
 // Checkstyle: allow synchronization
 
+/**
+ * Implementation of {@link Thread} that does not correspond to an {@linkplain IsolateThread OS
+ * thread} and instead gets mounted (scheduled to run) on a <em>platform thread</em> (OS thread),
+ * which, until when it is unmounted again, is called its <em>carrier thread</em>.
+ *
+ * This class is based on Project Loom's {@code java.lang.VirtualThread}.
+ */
 final class SubstrateVirtualThread extends Thread {
     private static final Unsafe U = GraalUnsafeAccess.getUnsafe();
     private static final ScheduledExecutorService UNPARKER = createDelayedTaskScheduler();
@@ -97,7 +106,11 @@ final class SubstrateVirtualThread extends Thread {
     // carrier thread when mounted
     private volatile Thread carrierThread;
 
-    // number of active pinnings to the carrier thread
+    /**
+     * Number of active {@linkplain #pin() pinnings} of this virtual thread to its current carrier
+     * thread, which prevent it from yielding and therefore unmounting. This is typically needed
+     * when using or acquiring resources that are associated with the carrier thread.
+     */
     private short pins;
 
     // termination object when joining, created lazily if needed

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/thread/VirtualThreads.java

@@ -29,6 +29,7 @@
 import org.graalvm.compiler.api.replacements.Fold;
 import org.graalvm.nativeimage.ImageSingletons;
 
+/** Operations on virtual threads. */
 public interface VirtualThreads {
     @Fold
     static VirtualThreads get() {