Simplify API exposed by commit 71a7632 and add missing documentation

src/java.base/share/classes/java/lang/Thread.java

@@ -225,8 +225,6 @@ public class Thread implements Runnable {
         registerNatives();
     }
 
-    public static final ScopedValue<Executor> VIRTUAL_THREAD_SCHEDULER = ScopedValue.newInstance();
-
     /*
      * Reserved for exclusive use by the JVM. Cannot be moved to the FieldHolder
      * as it needs to be set by the VM for JNI attaching threads, before executing
@@ -1069,6 +1067,11 @@ sealed interface OfVirtual extends Builder
             @Override OfVirtual inheritInheritableThreadLocals(boolean inherit);
             @Override OfVirtual uncaughtExceptionHandler(UncaughtExceptionHandler ueh);
 
+            /**
+             * Sets the scheduler.
+             * @param scheduler
+             * @return this builder
+             */
             OfVirtual scheduler(Executor scheduler);
         }
     }
@@ -1511,10 +1514,9 @@ public static Thread startVirtualThread(Runnable task, Executor scheduler) {
         return thread;
     }
 
-    public static Executor defaultVirtualThreadExecutor() {
-        return VirtualThread.DEFAULT_SCHEDULER;
-    }
-
+    /**
+     * Keeps the current thread pinned until {@linkplain #close() closed}. Returned by {@link #pinCarrierThread()}.
+     */
     public static final class CarrierThreadPin implements AutoCloseable {
         /**
          * {@code null} if the "pinned" thread is a platform thread.
@@ -1544,6 +1546,10 @@ public void close() {
         }
     }
 
+    /**
+     * Disallow the current thread be suspended or preempted until the returned pin is
+     * {@linkplain CarrierThreadPin#close() closed}.
+     */
     public static CarrierThreadPin pinCarrierThread() {
 		if (!(Thread.currentThread() instanceof VirtualThread thread)) {
             return new CarrierThreadPin(null);

src/java.base/share/classes/java/lang/ThreadBuilders.java

@@ -240,9 +240,9 @@ public OfVirtual uncaughtExceptionHandler(UncaughtExceptionHandler ueh) {
 
         @Override
         public OfVirtual scheduler(Executor scheduler) {
-            if (!ContinuationSupport.isSupported())
+            if (scheduler != null && !ContinuationSupport.isSupported())
                 throw new UnsupportedOperationException();
-            this.scheduler = Objects.requireNonNull(scheduler);
+            this.scheduler = scheduler;
             return this;
         }
 

src/java.base/share/classes/java/lang/VirtualThread.java

@@ -68,7 +68,7 @@
 final class VirtualThread extends BaseVirtualThread {
     private static final Unsafe U = Unsafe.getUnsafe();
     private static final ContinuationScope VTHREAD_SCOPE = new ContinuationScope("VirtualThreads");
-    static final Executor DEFAULT_SCHEDULER = createDefaultScheduler();
+    private static final Executor DEFAULT_SCHEDULER = createDefaultScheduler();
     private static final ScheduledExecutorService[] DELAYED_TASK_SCHEDULERS = createDelayedTaskSchedulers();
     private static final int TRACE_PINNING_MODE = tracePinningMode();
 
@@ -151,10 +151,8 @@ static ContinuationScope continuationScope() {
 
     /**
      * Creates a new {@code VirtualThread} to run the given task with the given
-     * scheduler. If the given scheduler is {@code null} and the current thread
-     * is a platform thread then the newly created virtual thread will use the
-     * default scheduler. If given scheduler is {@code null} and the current
-     * thread is a virtual thread then the current thread's scheduler is used.
+     * scheduler. If the given scheduler is {@code null} then the newly created
+     * virtual thread will use the default scheduler.
      *
      * @param scheduler the scheduler or null
      * @param name thread name
@@ -167,7 +165,7 @@ static ContinuationScope continuationScope() {
 
         // choose scheduler if not specified
         if (scheduler == null) {
-            scheduler = VIRTUAL_THREAD_SCHEDULER.orElse(DEFAULT_SCHEDULER);
+            scheduler = DEFAULT_SCHEDULER;
         }
 
         this.scheduler = scheduler;