1 /*
   2  * Copyright (c) 1994, 2022, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.lang.ref.Reference;
  29 import java.lang.reflect.Field;
  30 import java.security.AccessController;
  31 import java.security.AccessControlContext;
  32 import java.security.Permission;
  33 import java.security.PrivilegedAction;
  34 import java.security.ProtectionDomain;
  35 import java.time.Duration;
  36 import java.util.Map;
  37 import java.util.HashMap;
  38 import java.util.Objects;
  39 import java.util.concurrent.ThreadFactory;
  40 import java.util.concurrent.locks.LockSupport;
  41 import java.util.function.Predicate;
  42 import java.util.stream.Stream;
  43 import jdk.internal.event.ThreadSleepEvent;
  44 import jdk.internal.javac.PreviewFeature;
  45 import jdk.internal.misc.PreviewFeatures;
  46 import jdk.internal.misc.StructureViolationExceptions;
  47 import jdk.internal.misc.TerminatingThreadLocal;
  48 import jdk.internal.misc.Unsafe;
  49 import jdk.internal.misc.VM;
  50 import jdk.internal.reflect.CallerSensitive;
  51 import jdk.internal.reflect.Reflection;
  52 import jdk.internal.vm.Continuation;
  53 import jdk.internal.vm.ScopedValueContainer;
  54 import jdk.internal.vm.StackableScope;
  55 import jdk.internal.vm.ThreadContainer;
  56 import jdk.internal.vm.annotation.ForceInline;
  57 import jdk.internal.vm.annotation.Hidden;
  58 import jdk.internal.vm.annotation.IntrinsicCandidate;
  59 import sun.nio.ch.Interruptible;
  60 import sun.security.util.SecurityConstants;
  61 import static java.util.concurrent.TimeUnit.MILLISECONDS;
  62 import static java.util.concurrent.TimeUnit.NANOSECONDS;
  63 
  64 /**
  65  * A <i>thread</i> is a thread of execution in a program. The Java
  66  * virtual machine allows an application to have multiple threads of
  67  * execution running concurrently.
  68  *
  69  * <p> {@code Thread} defines constructors and a {@link Builder} to create threads.
  70  * {@linkplain #start() Starting} a thread schedules it to execute its {@link #run() run}
  71  * method. The newly started thread executes concurrently with the thread that caused
  72  * it to start.
  73  *
  74  * <p> A thread <i>terminates</i> if either its {@code run} method completes normally,
  75  * or if its {@code run} method completes abruptly and the appropriate {@linkplain
  76  * Thread.UncaughtExceptionHandler uncaught exception handler} completes normally or
  77  * abruptly. With no code left to run, the thread has completed execution. The
  78  * {@link #join() join} method can be used to wait for a thread to terminate.
  79  *
  80  * <p> Threads have a unique {@linkplain #threadId() identifier} and a {@linkplain
  81  * #getName() name}. The identifier is generated when a {@code Thread} is created
  82  * and cannot be changed. The thread name can be specified when creating a thread
  83  * or can be {@linkplain #setName(String) changed} at a later time.
  84  *
  85  * <p> Threads support {@link ThreadLocal} variables. These are variables that are
  86  * local to a thread, meaning a thread can have a copy of a variable that is set to
  87  * a value that is independent of the value set by other threads. Thread also supports
  88  * {@link InheritableThreadLocal} variables that are thread local variables that are
  89  * inherited at Thread creation time from the parent Thread. Thread supports a special
  90  * inheritable thread local for the thread {@linkplain #getContextClassLoader()
  91  * context-class-loader}.
  92  *
  93  * <h2><a id="platform-threads">Platform threads</a></h2>
  94  * <p> {@code Thread} supports the creation of <i>platform threads</i> that are
  95  * typically mapped 1:1 to kernel threads scheduled by the operating system.
  96  * Platform threads will usually have a large stack and other resources that are
  97  * maintained by the operating system. Platforms threads are suitable for executing
  98  * all types of tasks but may be a limited resource.
  99  *
 100  * <p> Platform threads get an automatically generated thread name by default.
 101  *
 102  * <p> Platform threads are designated <i>daemon</i> or <i>non-daemon</i> threads.
 103  * When the Java virtual machine starts up, there is usually one non-daemon
 104  * thread (the thread that typically calls the application's {@code main} method).
 105  * The <a href="Runtime.html#shutdown">shutdown sequence</a> begins when all started
 106  * non-daemon threads have terminated. Unstarted non-daemon threads do not prevent
 107  * the shutdown sequence from beginning.
 108  *
 109  * <p> In addition to the daemon status, platform threads have a {@linkplain
 110  * #getPriority() thread priority} and are members of a {@linkplain ThreadGroup
 111  * thread group}.
 112  *
 113  * <h2><a id="virtual-threads">Virtual threads</a></h2>
 114  * <p> {@code Thread} also supports the creation of <i>virtual threads</i>.
 115  * Virtual threads are typically <i>user-mode threads</i> scheduled by the Java
 116  * runtime rather than the operating system. Virtual threads will typically require
 117  * few resources and a single Java virtual machine may support millions of virtual
 118  * threads. Virtual threads are suitable for executing tasks that spend most of
 119  * the time blocked, often waiting for I/O operations to complete. Virtual threads
 120  * are not intended for long running CPU intensive operations.
 121  *
 122  * <p> Virtual threads typically employ a small set of platform threads used as
 123  * <em>carrier threads</em>. Locking and I/O operations are examples of operations
 124  * where a carrier thread may be re-scheduled from one virtual thread to another.
 125  * Code executing in a virtual thread is not aware of the underlying carrier thread.
 126  * The {@linkplain Thread#currentThread()} method, used to obtain a reference
 127  * to the <i>current thread</i>, will always return the {@code Thread} object
 128  * for the virtual thread.
 129  *
 130  * <p> Virtual threads do not have a thread name by default. The {@link #getName()
 131  * getName} method returns the empty string if a thread name is not set.
 132  *
 133  * <p> Virtual threads are daemon threads and so do not prevent the
 134  * <a href="Runtime.html#shutdown">shutdown sequence</a> from beginning.
 135  * Virtual threads have a fixed {@linkplain #getPriority() thread priority}
 136  * that cannot be changed.
 137  *
 138  * <h2>Creating and starting threads</h2>
 139  *
 140  * <p> {@code Thread} defines public constructors for creating platform threads and
 141  * the {@link #start() start} method to schedule threads to execute. {@code Thread}
 142  * may be extended for customization and other advanced reasons although most
 143  * applications should have little need to do this.
 144  *
 145  * <p> {@code Thread} defines a {@link Builder} API for creating and starting both
 146  * platform and virtual threads. The following are examples that use the builder:
 147  * {@snippet :
 148  *   Runnable runnable = ...
 149  *
 150  *   // Start a daemon thread to run a task
 151  *   Thread thread = Thread.ofPlatform().daemon().start(runnable);
 152  *
 153  *   // Create an unstarted thread with name "duke", its start() method
 154  *   // must be invoked to schedule it to execute.
 155  *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
 156  *
 157  *   // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
 158  *   ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();
 159  *
 160  *   // Start a virtual thread to run a task
 161  *   Thread thread = Thread.ofVirtual().start(runnable);
 162  *
 163  *   // A ThreadFactory that creates virtual threads
 164  *   ThreadFactory factory = Thread.ofVirtual().factory();
 165  * }
 166  *
 167  * <h2><a id="inheritance">Inheritance when creating threads</a></h2>
 168  * A {@code Thread} inherits its initial values of {@linkplain InheritableThreadLocal
 169  * inheritable-thread-local} variables (including the context class loader) from
 170  * the parent thread values at the time that the child {@code Thread} is created.
 171  * The 5-param {@linkplain Thread#Thread(ThreadGroup, Runnable, String, long, boolean)
 172  * constructor} can be used to create a thread that does not inherit its initial
 173  * values from the constructing thread. When using a {@code Thread.Builder}, the
 174  * {@link Builder#inheritInheritableThreadLocals(boolean) inheritInheritableThreadLocals}
 175  * method can be used to select if the initial values are inherited.
 176  *
 177  * <p> Platform threads inherit the daemon status, thread priority, and when not
 178  * provided (or not selected by a security manager), the thread group.
 179  *
 180  * <p> Creating a platform thread {@linkplain AccessController#getContext() captures} the
 181  * {@linkplain AccessControlContext caller context} to limit the {@linkplain Permission
 182  * permissions} of the new thread when it executes code that performs a {@linkplain
 183  * AccessController#doPrivileged(PrivilegedAction) privileged action}. The captured
 184  * caller context is the new thread's "Inherited {@link AccessControlContext}". Creating
 185  * a virtual thread does not capture the caller context; virtual threads have no
 186  * permissions when executing code that performs a privileged action.
 187  *
 188  * <p> Unless otherwise specified, passing a {@code null} argument to a constructor
 189  * or method in this class will cause a {@link NullPointerException} to be thrown.
 190  *
 191  * @implNote
 192  * In the JDK Reference Implementation, the virtual thread scheduler may be configured
 193  * with the following system properties:
 194  * <table class="striped">
 195  * <caption style="display:none:">System properties</caption>
 196  *   <thead>
 197  *   <tr>
 198  *     <th scope="col">System property</th>
 199  *     <th scope="col">Description</th>
 200  *   </tr>
 201  *   </thead>
 202  *   <tbody>
 203  *   <tr>
 204  *     <th scope="row">
 205  *       {@systemProperty jdk.virtualThreadScheduler.parallelism}
 206  *     </th>
 207  *     <td> The number of platform threads available for scheduling virtual
 208  *       threads. It defaults to the number of available processors. </td>
 209  *   </tr>
 210  *   <tr>
 211  *     <th scope="row">
 212  *       {@systemProperty jdk.virtualThreadScheduler.maxPoolSize}
 213  *     </th>
 214  *     <td> The maximum number of platform threads available to the scheduler.
 215  *       It defaults to 256. </td>
 216  *   </tr>
 217  *   </tbody>
 218  * </table>
 219  *
 220  * @since   1.0
 221  */
 222 public class Thread implements Runnable {
 223     /* Make sure registerNatives is the first thing <clinit> does. */
 224     private static native void registerNatives();
 225     static {
 226         registerNatives();
 227     }
 228 
 229     /* Reserved for exclusive use by the JVM, maybe move to FieldHolder */
 230     private long eetop;
 231 
 232     // thread id
 233     private final long tid;
 234 
 235     // thread name
 236     private volatile String name;
 237 
 238     // interrupt status (read/written by VM)
 239     volatile boolean interrupted;
 240 
 241     // context ClassLoader
 242     private volatile ClassLoader contextClassLoader;
 243 
 244     // inherited AccessControlContext, this could be moved to FieldHolder
 245     @SuppressWarnings("removal")
 246     private AccessControlContext inheritedAccessControlContext;
 247 
 248     // Additional fields for platform threads.
 249     // All fields, except task, are accessed directly by the VM.
 250     private static class FieldHolder {
 251         final ThreadGroup group;
 252         final Runnable task;
 253         final long stackSize;
 254         volatile int priority;
 255         volatile boolean daemon;
 256         volatile int threadStatus;
 257 
 258         FieldHolder(ThreadGroup group,
 259                     Runnable task,
 260                     long stackSize,
 261                     int priority,
 262                     boolean daemon) {
 263             this.group = group;
 264             this.task = task;
 265             this.stackSize = stackSize;
 266             this.priority = priority;
 267             if (daemon)
 268                 this.daemon = true;
 269         }
 270     }
 271     private final FieldHolder holder;
 272 
 273     /*
 274      * ThreadLocal values pertaining to this thread. This map is maintained
 275      * by the ThreadLocal class. */
 276     ThreadLocal.ThreadLocalMap threadLocals;
 277 
 278     /*
 279      * InheritableThreadLocal values pertaining to this thread. This map is
 280      * maintained by the InheritableThreadLocal class.
 281      */
 282     ThreadLocal.ThreadLocalMap inheritableThreadLocals;
 283 
 284     /*
 285      * Scoped value bindings are maintained by the ScopedValue class.
 286      */
 287     private Object scopedValueBindings;
 288 
 289     // Special value to indicate this is a newly-created Thread
 290     // Note that his must match the declaration in ScopedValue.
 291     private static final Object NEW_THREAD_BINDINGS = Thread.class;
 292 
 293     static Object scopedValueBindings() {
 294         return currentThread().scopedValueBindings;
 295     }
 296 
 297     static void setScopedValueBindings(Object bindings) {
 298         currentThread().scopedValueBindings = bindings;
 299     }
 300 
 301     /**
 302      * Search the stack for the most recent scoped-value bindings.
 303      */
 304     @IntrinsicCandidate
 305     static native Object findScopedValueBindings();
 306 
 307     /**
 308      * Inherit the scoped-value bindings from the given container.
 309      * Invoked when starting a thread.
 310      */
 311     void inheritScopedValueBindings(ThreadContainer container) {
 312         ScopedValueContainer.BindingsSnapshot snapshot;
 313         if (container.owner() != null
 314                 && (snapshot = container.scopedValueBindings()) != null) {
 315 
 316             // bindings established for running/calling an operation
 317             Object bindings = snapshot.scopedValueBindings();
 318             if (currentThread().scopedValueBindings != bindings) {
 319                 StructureViolationExceptions.throwException("Scoped value bindings have changed");
 320             }
 321 
 322             this.scopedValueBindings = bindings;
 323         }
 324     }
 325 
 326     /*
 327      * Lock object for thread interrupt.
 328      */
 329     final Object interruptLock = new Object();
 330 
 331     /**
 332      * The argument supplied to the current call to
 333      * java.util.concurrent.locks.LockSupport.park.
 334      * Set by (private) java.util.concurrent.locks.LockSupport.setBlocker
 335      * Accessed using java.util.concurrent.locks.LockSupport.getBlocker
 336      */
 337     private volatile Object parkBlocker;
 338 
 339     /* The object in which this thread is blocked in an interruptible I/O
 340      * operation, if any.  The blocker's interrupt method should be invoked
 341      * after setting this thread's interrupt status.
 342      */
 343     volatile Interruptible nioBlocker;
 344 
 345     /* Set the blocker field; invoked via jdk.internal.access.SharedSecrets
 346      * from java.nio code
 347      */
 348     static void blockedOn(Interruptible b) {
 349         Thread me = Thread.currentThread();
 350         synchronized (me.interruptLock) {
 351             me.nioBlocker = b;
 352         }
 353     }
 354 
 355     /**
 356      * The minimum priority that a thread can have.
 357      */
 358     public static final int MIN_PRIORITY = 1;
 359 
 360     /**
 361      * The default priority that is assigned to a thread.
 362      */
 363     public static final int NORM_PRIORITY = 5;
 364 
 365     /**
 366      * The maximum priority that a thread can have.
 367      */
 368     public static final int MAX_PRIORITY = 10;
 369 
 370     /*
 371      * Current inner-most continuation.
 372      */
 373     private Continuation cont;
 374 
 375     /**
 376      * Returns the current continuation.
 377      */
 378     Continuation getContinuation() {
 379         return cont;
 380     }
 381 
 382     /**
 383      * Sets the current continuation.
 384      */
 385     void setContinuation(Continuation cont) {
 386         this.cont = cont;
 387     }
 388 
 389     /**
 390      * Returns the Thread object for the current platform thread. If the
 391      * current thread is a virtual thread then this method returns the carrier.
 392      */
 393     @IntrinsicCandidate
 394     static native Thread currentCarrierThread();
 395 
 396     /**
 397      * Returns the Thread object for the current thread.
 398      * @return  the current thread
 399      */
 400     @IntrinsicCandidate
 401     public static native Thread currentThread();
 402 
 403     /**
 404      * Sets the Thread object to be returned by Thread.currentThread().
 405      */
 406     @IntrinsicCandidate
 407     native void setCurrentThread(Thread thread);
 408 
 409     // ScopedValue support:
 410 
 411     @IntrinsicCandidate
 412     static native Object[] scopedValueCache();
 413 
 414     @IntrinsicCandidate
 415     static native void setScopedValueCache(Object[] cache);
 416 
 417     @IntrinsicCandidate
 418     static native void ensureMaterializedForStackWalk(Object o);
 419 
 420     /**
 421      * A hint to the scheduler that the current thread is willing to yield
 422      * its current use of a processor. The scheduler is free to ignore this
 423      * hint.
 424      *
 425      * <p> Yield is a heuristic attempt to improve relative progression
 426      * between threads that would otherwise over-utilise a CPU. Its use
 427      * should be combined with detailed profiling and benchmarking to
 428      * ensure that it actually has the desired effect.
 429      *
 430      * <p> It is rarely appropriate to use this method. It may be useful
 431      * for debugging or testing purposes, where it may help to reproduce
 432      * bugs due to race conditions. It may also be useful when designing
 433      * concurrency control constructs such as the ones in the
 434      * {@link java.util.concurrent.locks} package.
 435      */
 436     public static void yield() {
 437         if (currentThread() instanceof VirtualThread vthread) {
 438             vthread.tryYield();
 439         } else {
 440             yield0();
 441         }
 442     }
 443 
 444     private static native void yield0();
 445 
 446     /**
 447      * Causes the currently executing thread to sleep (temporarily cease
 448      * execution) for the specified number of milliseconds, subject to
 449      * the precision and accuracy of system timers and schedulers. The thread
 450      * does not lose ownership of any monitors.
 451      *
 452      * @param  millis
 453      *         the length of time to sleep in milliseconds
 454      *
 455      * @throws  IllegalArgumentException
 456      *          if the value of {@code millis} is negative
 457      *
 458      * @throws  InterruptedException
 459      *          if any thread has interrupted the current thread. The
 460      *          <i>interrupted status</i> of the current thread is
 461      *          cleared when this exception is thrown.
 462      */
 463     public static void sleep(long millis) throws InterruptedException {
 464         if (millis < 0) {
 465             throw new IllegalArgumentException("timeout value is negative");
 466         }
 467 
 468         if (currentThread() instanceof VirtualThread vthread) {
 469             long nanos = MILLISECONDS.toNanos(millis);
 470             vthread.sleepNanos(nanos);
 471             return;
 472         }
 473 
 474         if (ThreadSleepEvent.isTurnedOn()) {
 475             ThreadSleepEvent event = new ThreadSleepEvent();
 476             try {
 477                 event.time = MILLISECONDS.toNanos(millis);
 478                 event.begin();
 479                 sleep0(millis);
 480             } finally {
 481                 event.commit();
 482             }
 483         } else {
 484             sleep0(millis);
 485         }
 486     }
 487 
 488     private static native void sleep0(long millis) throws InterruptedException;
 489 
 490     /**
 491      * Causes the currently executing thread to sleep (temporarily cease
 492      * execution) for the specified number of milliseconds plus the specified
 493      * number of nanoseconds, subject to the precision and accuracy of system
 494      * timers and schedulers. The thread does not lose ownership of any
 495      * monitors.
 496      *
 497      * @param  millis
 498      *         the length of time to sleep in milliseconds
 499      *
 500      * @param  nanos
 501      *         {@code 0-999999} additional nanoseconds to sleep
 502      *
 503      * @throws  IllegalArgumentException
 504      *          if the value of {@code millis} is negative, or the value of
 505      *          {@code nanos} is not in the range {@code 0-999999}
 506      *
 507      * @throws  InterruptedException
 508      *          if any thread has interrupted the current thread. The
 509      *          <i>interrupted status</i> of the current thread is
 510      *          cleared when this exception is thrown.
 511      */
 512     public static void sleep(long millis, int nanos) throws InterruptedException {
 513         if (millis < 0) {
 514             throw new IllegalArgumentException("timeout value is negative");
 515         }
 516 
 517         if (nanos < 0 || nanos > 999999) {
 518             throw new IllegalArgumentException("nanosecond timeout value out of range");
 519         }
 520 
 521         if (currentThread() instanceof VirtualThread vthread) {
 522             // total sleep time, in nanoseconds
 523             long totalNanos = MILLISECONDS.toNanos(millis);
 524             totalNanos += Math.min(Long.MAX_VALUE - totalNanos, nanos);
 525             vthread.sleepNanos(totalNanos);
 526             return;
 527         }
 528 
 529         if (nanos > 0 && millis < Long.MAX_VALUE) {
 530             millis++;
 531         }
 532         sleep(millis);
 533     }
 534 
 535     /**
 536      * Causes the currently executing thread to sleep (temporarily cease
 537      * execution) for the specified duration, subject to the precision and
 538      * accuracy of system timers and schedulers. This method is a no-op if
 539      * the duration is {@linkplain Duration#isNegative() negative}.
 540      *
 541      * @param  duration
 542      *         the duration to sleep
 543      *
 544      * @throws  InterruptedException
 545      *          if the current thread is interrupted while sleeping. The
 546      *          <i>interrupted status</i> of the current thread is
 547      *          cleared when this exception is thrown.
 548      *
 549      * @since 19
 550      */
 551     public static void sleep(Duration duration) throws InterruptedException {
 552         long nanos = NANOSECONDS.convert(duration);  // MAX_VALUE if > 292 years
 553         if (nanos < 0)
 554             return;
 555 
 556         if (currentThread() instanceof VirtualThread vthread) {
 557             vthread.sleepNanos(nanos);
 558             return;
 559         }
 560 
 561         // convert to milliseconds
 562         long millis = MILLISECONDS.convert(nanos, NANOSECONDS);
 563         if (nanos > NANOSECONDS.convert(millis, MILLISECONDS)) {
 564             millis += 1L;
 565         }
 566         sleep(millis);
 567     }
 568 
 569     /**
 570      * Indicates that the caller is momentarily unable to progress, until the
 571      * occurrence of one or more actions on the part of other activities. By
 572      * invoking this method within each iteration of a spin-wait loop construct,
 573      * the calling thread indicates to the runtime that it is busy-waiting.
 574      * The runtime may take action to improve the performance of invoking
 575      * spin-wait loop constructions.
 576      *
 577      * @apiNote
 578      * As an example consider a method in a class that spins in a loop until
 579      * some flag is set outside of that method. A call to the {@code onSpinWait}
 580      * method should be placed inside the spin loop.
 581      * {@snippet :
 582      *     class EventHandler {
 583      *         volatile boolean eventNotificationNotReceived;
 584      *         void waitForEventAndHandleIt() {
 585      *             while ( eventNotificationNotReceived ) {
 586      *                 Thread.onSpinWait();
 587      *             }
 588      *             readAndProcessEvent();
 589      *         }
 590      *
 591      *         void readAndProcessEvent() {
 592      *             // Read event from some source and process it
 593      *              . . .
 594      *         }
 595      *     }
 596      * }
 597      * <p>
 598      * The code above would remain correct even if the {@code onSpinWait}
 599      * method was not called at all. However on some architectures the Java
 600      * Virtual Machine may issue the processor instructions to address such
 601      * code patterns in a more beneficial way.
 602      *
 603      * @since 9
 604      */
 605     @IntrinsicCandidate
 606     public static void onSpinWait() {}
 607 
 608     /**
 609      * Characteristic value signifying that the thread cannot set values for its
 610      * copy of {@link ThreadLocal thread-locals}.
 611      * See Thread initialization.
 612      */
 613     static final int NO_THREAD_LOCALS = 1 << 1;
 614 
 615     /**
 616      * Characteristic value signifying that initial values for {@link
 617      * InheritableThreadLocal inheritable-thread-locals} are not inherited from
 618      * the constructing thread.
 619      * See Thread initialization.
 620      */
 621     static final int NO_INHERIT_THREAD_LOCALS = 1 << 2;
 622 
 623     /**
 624      * Helper class to generate thread identifiers. The identifiers start at
 625      * 2 as this class cannot be used during early startup to generate the
 626      * identifier for the primordial thread. The counter is off-heap and
 627      * shared with the VM to allow it assign thread identifiers to non-Java
 628      * threads.
 629      * See Thread initialization.
 630      */
 631     private static class ThreadIdentifiers {
 632         private static final Unsafe U;
 633         private static final long NEXT_TID_OFFSET;
 634         static {
 635             U = Unsafe.getUnsafe();
 636             NEXT_TID_OFFSET = Thread.getNextThreadIdOffset();
 637         }
 638         static long next() {
 639             return U.getAndAddLong(null, NEXT_TID_OFFSET, 1);
 640         }
 641     }
 642 
 643     /**
 644      * Returns the context class loader to inherit from the parent thread.
 645      * See Thread initialization.
 646      */
 647     private static ClassLoader contextClassLoader(Thread parent) {
 648         @SuppressWarnings("removal")
 649         SecurityManager sm = System.getSecurityManager();
 650         if (sm == null || isCCLOverridden(parent.getClass())) {
 651             return parent.getContextClassLoader();
 652         } else {
 653             // skip call to getContextClassLoader
 654             ClassLoader cl = parent.contextClassLoader;
 655             return (isSupportedClassLoader(cl)) ? cl : ClassLoader.getSystemClassLoader();
 656         }
 657     }
 658 
 659     /**
 660      * Initializes a platform Thread.
 661      *
 662      * @param g the Thread group, can be null
 663      * @param name the name of the new Thread
 664      * @param characteristics thread characteristics
 665      * @param task the object whose run() method gets called
 666      * @param stackSize the desired stack size for the new thread, or
 667      *        zero to indicate that this parameter is to be ignored.
 668      * @param acc the AccessControlContext to inherit, or
 669      *        AccessController.getContext() if null
 670      */
 671     @SuppressWarnings("removal")
 672     Thread(ThreadGroup g, String name, int characteristics, Runnable task,
 673            long stackSize, AccessControlContext acc) {
 674 
 675         Thread parent = currentThread();
 676         boolean attached = (parent == this);   // primordial or JNI attached
 677 
 678         if (attached) {
 679             if (g == null) {
 680                 throw new InternalError("group cannot be null when attaching");
 681             }
 682             this.holder = new FieldHolder(g, task, stackSize, NORM_PRIORITY, false);
 683         } else {
 684             SecurityManager sm = System.getSecurityManager();
 685             if (g == null) {
 686                 // the security manager can choose the thread group
 687                 if (sm != null) {
 688                     g = sm.getThreadGroup();
 689                 }
 690 
 691                 // default to current thread's group
 692                 if (g == null) {
 693                     g = parent.getThreadGroup();
 694                 }
 695             }
 696 
 697             // permission checks when creating a child Thread
 698             if (sm != null) {
 699                 sm.checkAccess(g);
 700                 if (isCCLOverridden(getClass())) {
 701                     sm.checkPermission(SecurityConstants.SUBCLASS_IMPLEMENTATION_PERMISSION);
 702                 }
 703             }
 704 
 705             int priority = Math.min(parent.getPriority(), g.getMaxPriority());
 706             this.holder = new FieldHolder(g, task, stackSize, priority, parent.isDaemon());
 707         }
 708 
 709         if (attached && VM.initLevel() < 1) {
 710             this.tid = 1;  // primordial thread
 711         } else {
 712             this.tid = ThreadIdentifiers.next();
 713         }
 714         this.name = (name != null) ? name : genThreadName();
 715 
 716         if (acc != null) {
 717             this.inheritedAccessControlContext = acc;
 718         } else {
 719             this.inheritedAccessControlContext = AccessController.getContext();
 720         }
 721 
 722         // thread locals
 723         if (!attached) {
 724             if ((characteristics & NO_THREAD_LOCALS) != 0) {
 725                 this.threadLocals = ThreadLocal.ThreadLocalMap.NOT_SUPPORTED;
 726                 this.inheritableThreadLocals = ThreadLocal.ThreadLocalMap.NOT_SUPPORTED;
 727                 this.contextClassLoader = Constants.NOT_SUPPORTED_CLASSLOADER;
 728             } else if ((characteristics & NO_INHERIT_THREAD_LOCALS) == 0) {
 729                 ThreadLocal.ThreadLocalMap parentMap = parent.inheritableThreadLocals;
 730                 if (parentMap != null
 731                         && parentMap != ThreadLocal.ThreadLocalMap.NOT_SUPPORTED
 732                         && parentMap.size() > 0) {
 733                     this.inheritableThreadLocals = ThreadLocal.createInheritedMap(parentMap);
 734                 }
 735                 ClassLoader parentLoader = contextClassLoader(parent);
 736                 if (VM.isBooted() && !isSupportedClassLoader(parentLoader)) {
 737                     // parent does not support thread locals so no CCL to inherit
 738                     this.contextClassLoader = ClassLoader.getSystemClassLoader();
 739                 } else {
 740                     this.contextClassLoader = parentLoader;
 741                 }
 742             } else if (VM.isBooted()) {
 743                 // default CCL to the system class loader when not inheriting
 744                 this.contextClassLoader = ClassLoader.getSystemClassLoader();
 745             }
 746         }
 747 
 748         // Special value to indicate this is a newly-created Thread
 749         // Note that his must match the declaration in ScopedValue.
 750         this.scopedValueBindings = NEW_THREAD_BINDINGS;
 751     }
 752 
 753     /**
 754      * Initializes a virtual Thread.
 755      *
 756      * @param name thread name, can be null
 757      * @param characteristics thread characteristics
 758      * @param bound true when bound to an OS thread
 759      */
 760     Thread(String name, int characteristics, boolean bound) {
 761         this.tid = ThreadIdentifiers.next();
 762         this.name = (name != null) ? name : "";
 763         this.inheritedAccessControlContext = Constants.NO_PERMISSIONS_ACC;
 764 
 765         // thread locals
 766         if ((characteristics & NO_THREAD_LOCALS) != 0) {
 767             this.threadLocals = ThreadLocal.ThreadLocalMap.NOT_SUPPORTED;
 768             this.inheritableThreadLocals = ThreadLocal.ThreadLocalMap.NOT_SUPPORTED;
 769             this.contextClassLoader = Constants.NOT_SUPPORTED_CLASSLOADER;
 770         } else if ((characteristics & NO_INHERIT_THREAD_LOCALS) == 0) {
 771             Thread parent = currentThread();
 772             ThreadLocal.ThreadLocalMap parentMap = parent.inheritableThreadLocals;
 773             if (parentMap != null
 774                     && parentMap != ThreadLocal.ThreadLocalMap.NOT_SUPPORTED
 775                     && parentMap.size() > 0) {
 776                 this.inheritableThreadLocals = ThreadLocal.createInheritedMap(parentMap);
 777             }
 778             ClassLoader parentLoader = contextClassLoader(parent);
 779             if (isSupportedClassLoader(parentLoader)) {
 780                 this.contextClassLoader = parentLoader;
 781             } else {
 782                 // parent does not support thread locals so no CCL to inherit
 783                 this.contextClassLoader = ClassLoader.getSystemClassLoader();
 784             }
 785         } else {
 786             // default CCL to the system class loader when not inheriting
 787             this.contextClassLoader = ClassLoader.getSystemClassLoader();
 788         }
 789 
 790         // Special value to indicate this is a newly-created Thread
 791         this.scopedValueBindings = NEW_THREAD_BINDINGS;
 792 
 793         // create a FieldHolder object, needed when bound to an OS thread
 794         if (bound) {
 795             ThreadGroup g = Constants.VTHREAD_GROUP;
 796             int pri = NORM_PRIORITY;
 797             this.holder = new FieldHolder(g, null, -1, pri, true);
 798         } else {
 799             this.holder = null;
 800         }
 801     }
 802 
 803     /**
 804      * Returns a builder for creating a platform {@code Thread} or {@code ThreadFactory}
 805      * that creates platform threads.
 806      *
 807      * <p> <a id="ofplatform-security"><b>Interaction with security manager when
 808      * creating platform threads</b></a>
 809      * <p> Creating a platform thread when there is a security manager set will
 810      * invoke the security manager's {@link SecurityManager#checkAccess(ThreadGroup)
 811      * checkAccess(ThreadGroup)} method with the thread's thread group.
 812      * If the thread group has not been set with the {@link
 813      * Builder.OfPlatform#group(ThreadGroup) OfPlatform.group} method then the
 814      * security manager's {@link SecurityManager#getThreadGroup() getThreadGroup}
 815      * method will be invoked first to select the thread group. If the security
 816      * manager {@code getThreadGroup} method returns {@code null} then the thread
 817      * group of the constructing thread is used.
 818      *
 819      * @apiNote The following are examples using the builder:
 820      * {@snippet :
 821      *   // Start a daemon thread to run a task
 822      *   Thread thread = Thread.ofPlatform().daemon().start(runnable);
 823      *
 824      *   // Create an unstarted thread with name "duke", its start() method
 825      *   // must be invoked to schedule it to execute.
 826      *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
 827      *
 828      *   // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
 829      *   ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();
 830      * }
 831      *
 832      * @return A builder for creating {@code Thread} or {@code ThreadFactory} objects.
 833      * @since 19
 834      */
 835     @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
 836     public static Builder.OfPlatform ofPlatform() {
 837         return new ThreadBuilders.PlatformThreadBuilder();
 838     }
 839 
 840     /**
 841      * Returns a builder for creating a virtual {@code Thread} or {@code ThreadFactory}
 842      * that creates virtual threads.
 843      *
 844      * @apiNote The following are examples using the builder:
 845      * {@snippet :
 846      *   // Start a virtual thread to run a task.
 847      *   Thread thread = Thread.ofVirtual().start(runnable);
 848      *
 849      *   // A ThreadFactory that creates virtual threads
 850      *   ThreadFactory factory = Thread.ofVirtual().factory();
 851      * }
 852      *
 853      * @return A builder for creating {@code Thread} or {@code ThreadFactory} objects.
 854      * @throws UnsupportedOperationException if preview features are not enabled
 855      * @since 19
 856      */
 857     @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
 858     public static Builder.OfVirtual ofVirtual() {
 859         PreviewFeatures.ensureEnabled();
 860         return new ThreadBuilders.VirtualThreadBuilder();
 861     }
 862 
 863     /**
 864      * A builder for {@link Thread} and {@link ThreadFactory} objects.
 865      *
 866      * <p> {@code Builder} defines methods to set {@code Thread} properties such
 867      * as the thread {@link #name(String) name}. This includes properties that would
 868      * otherwise be <a href="Thread.html#inheritance">inherited</a>. Once set, a
 869      * {@code Thread} or {@code ThreadFactory} is created with the following methods:
 870      *
 871      * <ul>
 872      *     <li> The {@linkplain #unstarted(Runnable) unstarted} method creates a new
 873      *          <em>unstarted</em> {@code Thread} to run a task. The {@code Thread}'s
 874      *          {@link Thread#start() start} method must be invoked to schedule the
 875      *          thread to execute.
 876      *     <li> The {@linkplain #start(Runnable) start} method creates a new {@code
 877      *          Thread} to run a task and schedules the thread to execute.
 878      *     <li> The {@linkplain #factory() factory} method creates a {@code ThreadFactory}.
 879      * </ul>
 880      *
 881      * <p> A {@code Thread.Builder} is not thread safe. The {@code ThreadFactory}
 882      * returned by the builder's {@code factory()} method is thread safe.
 883      *
 884      * <p> Unless otherwise specified, passing a null argument to a method in
 885      * this interface causes a {@code NullPointerException} to be thrown.
 886      *
 887      * @see Thread#ofPlatform()
 888      * @see Thread#ofVirtual()
 889      * @since 19
 890      */
 891     @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
 892     public sealed interface Builder
 893             permits Builder.OfPlatform,
 894                     Builder.OfVirtual,
 895                     ThreadBuilders.BaseThreadBuilder {
 896 
 897 
 898         /**
 899          * Sets the thread name.
 900          * @param name thread name
 901          * @return this builder
 902          */
 903         Builder name(String name);
 904 
 905         /**
 906          * Sets the thread name to be the concatenation of a string prefix and
 907          * the string representation of a counter value. The counter's initial
 908          * value is {@code start}. It is incremented after a {@code Thread} is
 909          * created with this builder so that the next thread is named with
 910          * the new counter value. A {@code ThreadFactory} created with this
 911          * builder is seeded with the current value of the counter. The {@code
 912          * ThreadFactory} increments its copy of the counter after {@link
 913          * ThreadFactory#newThread(Runnable) newThread} is used to create a
 914          * {@code Thread}.
 915          *
 916          * @apiNote
 917          * The following example creates a builder that is invoked twice to start
 918          * two threads named "{@code worker-0}" and "{@code worker-1}".
 919          * {@snippet :
 920          *   Thread.Builder builder = Thread.ofPlatform().name("worker-", 0);
 921          *   Thread t1 = builder.start(task1);   // name "worker-0"
 922          *   Thread t2 = builder.start(task2);   // name "worker-1"
 923          * }
 924          *
 925          * @param prefix thread name prefix
 926          * @param start the starting value of the counter
 927          * @return this builder
 928          * @throws IllegalArgumentException if start is negative
 929          */
 930         Builder name(String prefix, long start);
 931 
 932         /**
 933          * Sets whether the thread is allowed to set values for its copy of {@linkplain
 934          * ThreadLocal thread-local} variables. The default is to allow. If not allowed,
 935          * then any attempt by the thread to set a value for a thread-local with the
 936          * {@link ThreadLocal#set(Object)} method throws {@code
 937          * UnsupportedOperationException}. Any attempt to set the thread's context
 938          * class loader with {@link Thread#setContextClassLoader(ClassLoader)
 939          * setContextClassLoader} also throws. The {@link ThreadLocal#get()} method
 940          * always returns the {@linkplain ThreadLocal#initialValue() initial-value}
 941          * when thread locals are not allowed.
 942          *
 943          * @apiNote This method is intended for cases where there are a large number of
 944          * threads and where potentially unbounded memory usage due to thread locals is
 945          * a concern. Disallowing a thread to set its copy of thread-local variables
 946          * creates the potential for exceptions at run-time so great care is required
 947          * when the thread is used to invoke arbitrary code.
 948          *
 949          * @param allow {@code true} to allow, {@code false} to disallow
 950          * @return this builder
 951          */
 952         Builder allowSetThreadLocals(boolean allow);
 953 
 954         /**
 955          * Sets whether the thread inherits the initial values of {@linkplain
 956          * InheritableThreadLocal inheritable-thread-local} variables from the
 957          * constructing thread. The default is to inherit.
 958          *
 959          * <p> The initial values of {@code InheritableThreadLocal}s are never inherited
 960          * when {@link #allowSetThreadLocals(boolean)} is used to disallow the thread
 961          * to have its own copy of thread-local variables.
 962          *
 963          * @param inherit {@code true} to inherit, {@code false} to not inherit
 964          * @return this builder
 965          */
 966         Builder inheritInheritableThreadLocals(boolean inherit);
 967 
 968         /**
 969          * Sets the uncaught exception handler.
 970          * @param ueh uncaught exception handler
 971          * @return this builder
 972          */
 973         Builder uncaughtExceptionHandler(UncaughtExceptionHandler ueh);
 974 
 975         /**
 976          * Creates a new {@code Thread} from the current state of the builder to
 977          * run the given task. The {@code Thread}'s {@link Thread#start() start}
 978          * method must be invoked to schedule the thread to execute.
 979          *
 980          * @param task the object to run when the thread executes
 981          * @return a new unstarted Thread
 982          * @throws SecurityException if denied by the security manager
 983          *         (See <a href="Thread.html#ofplatform-security">Interaction with
 984          *         security manager when creating platform threads</a>)
 985          *
 986          * @see <a href="Thread.html#inheritance">Inheritance when creating threads</a>
 987          */
 988         Thread unstarted(Runnable task);
 989 
 990         /**
 991          * Creates a new {@code Thread} from the current state of the builder and
 992          * schedules it to execute.
 993          *
 994          * @param task the object to run when the thread executes
 995          * @return a new started Thread
 996          * @throws SecurityException if denied by the security manager
 997          *         (See <a href="Thread.html#ofplatform-security">Interaction with
 998          *         security manager when creating platform threads</a>)
 999          *
1000          * @see <a href="Thread.html#inheritance">Inheritance when creating threads</a>
1001          */
1002         Thread start(Runnable task);
1003 
1004         /**
1005          * Returns a {@code ThreadFactory} to create threads from the current
1006          * state of the builder. The returned thread factory is safe for use by
1007          * multiple concurrent threads.
1008          *
1009          * @return a thread factory to create threads
1010          */
1011         ThreadFactory factory();
1012 
1013         /**
1014          * A builder for creating a platform {@link Thread} or {@link ThreadFactory}
1015          * that creates platform threads.
1016          *
1017          * <p> Unless otherwise specified, passing a null argument to a method in
1018          * this interface causes a {@code NullPointerException} to be thrown.
1019          *
1020          * @see Thread#ofPlatform()
1021          * @since 19
1022          */
1023         @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
1024         sealed interface OfPlatform extends Builder
1025                 permits ThreadBuilders.PlatformThreadBuilder {
1026 
1027             @Override OfPlatform name(String name);
1028 
1029             /**
1030              * @throws IllegalArgumentException {@inheritDoc}
1031              */
1032             @Override OfPlatform name(String prefix, long start);
1033 
1034             @Override OfPlatform allowSetThreadLocals(boolean allow);
1035             @Override OfPlatform inheritInheritableThreadLocals(boolean inherit);
1036             @Override OfPlatform uncaughtExceptionHandler(UncaughtExceptionHandler ueh);
1037 
1038             /**
1039              * Sets the thread group.
1040              * @param group the thread group
1041              * @return this builder
1042              */
1043             OfPlatform group(ThreadGroup group);
1044 
1045             /**
1046              * Sets the daemon status.
1047              * @param on {@code true} to create daemon threads
1048              * @return this builder
1049              */
1050             OfPlatform daemon(boolean on);
1051 
1052             /**
1053              * Sets the daemon status to {@code true}.
1054              * @implSpec The default implementation invokes {@linkplain #daemon(boolean)} with
1055              * a value of {@code true}.
1056              * @return this builder
1057              */
1058             default OfPlatform daemon() {
1059                 return daemon(true);
1060             }
1061 
1062             /**
1063              * Sets the thread priority.
1064              * @param priority priority
1065              * @return this builder
1066              * @throws IllegalArgumentException if the priority is less than
1067              *        {@link Thread#MIN_PRIORITY} or greater than {@link Thread#MAX_PRIORITY}
1068              */
1069             OfPlatform priority(int priority);
1070 
1071             /**
1072              * Sets the desired stack size.
1073              *
1074              * <p> The stack size is the approximate number of bytes of address space
1075              * that the Java virtual machine is to allocate for the thread's stack. The
1076              * effect is highly platform dependent and the Java virtual machine is free
1077              * to treat the {@code stackSize} parameter as a "suggestion". If the value
1078              * is unreasonably low for the platform then a platform specific minimum
1079              * may be used. If the value is unreasonably high then a platform specific
1080              * maximum may be used. A value of zero is always ignored.
1081              *
1082              * @param stackSize the desired stack size
1083              * @return this builder
1084              * @throws IllegalArgumentException if the stack size is negative
1085              */
1086             OfPlatform stackSize(long stackSize);
1087         }
1088 
1089         /**
1090          * A builder for creating a virtual {@link Thread} or {@link ThreadFactory}
1091          * that creates virtual threads.
1092          *
1093          * <p> Unless otherwise specified, passing a null argument to a method in
1094          * this interface causes a {@code NullPointerException} to be thrown.
1095          *
1096          * @see Thread#ofVirtual()
1097          * @since 19
1098          */
1099         @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
1100         sealed interface OfVirtual extends Builder
1101                 permits ThreadBuilders.VirtualThreadBuilder {
1102 
1103             @Override OfVirtual name(String name);
1104 
1105             /**
1106              * @throws IllegalArgumentException {@inheritDoc}
1107              */
1108             @Override OfVirtual name(String prefix, long start);
1109 
1110             @Override OfVirtual allowSetThreadLocals(boolean allow);
1111             @Override OfVirtual inheritInheritableThreadLocals(boolean inherit);
1112             @Override OfVirtual uncaughtExceptionHandler(UncaughtExceptionHandler ueh);
1113         }
1114     }
1115 
1116     /**
1117      * Throws CloneNotSupportedException as a Thread can not be meaningfully
1118      * cloned. Construct a new Thread instead.
1119      *
1120      * @throws  CloneNotSupportedException
1121      *          always
1122      */
1123     @Override
1124     protected Object clone() throws CloneNotSupportedException {
1125         throw new CloneNotSupportedException();
1126     }
1127 
1128     /**
1129      * Helper class for auto-numbering platform threads. The numbers start at
1130      * 0 and are separate from the thread identifier for historical reasons.
1131      */
1132     private static class ThreadNumbering {
1133         private static final Unsafe U;
1134         private static final Object NEXT_BASE;
1135         private static final long NEXT_OFFSET;
1136         static {
1137             U = Unsafe.getUnsafe();
1138             try {
1139                 Field nextField = ThreadNumbering.class.getDeclaredField("next");
1140                 NEXT_BASE = U.staticFieldBase(nextField);
1141                 NEXT_OFFSET = U.staticFieldOffset(nextField);
1142             } catch (NoSuchFieldException e) {
1143                 throw new ExceptionInInitializerError(e);
1144             }
1145         }
1146         private static volatile int next;
1147         static int next() {
1148             return U.getAndAddInt(NEXT_BASE, NEXT_OFFSET, 1);
1149         }
1150     }
1151 
1152     /**
1153      * Generates a thread name of the form {@code Thread-<n>}.
1154      */
1155     static String genThreadName() {
1156         return "Thread-" + ThreadNumbering.next();
1157     }
1158 
1159     /**
1160      * Throws NullPointerException if the name is null. Avoids use of
1161      * Objects.requireNonNull in early startup.
1162      */
1163     private static String checkName(String name) {
1164         if (name == null)
1165             throw new NullPointerException("'name' is null");
1166         return name;
1167     }
1168 
1169     /**
1170      * Initializes a new platform {@code Thread}. This constructor has the same
1171      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1172      * {@code (null, null, gname)}, where {@code gname} is a newly generated
1173      * name. Automatically generated names are of the form
1174      * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.
1175      *
1176      * <p> This constructor is only useful when extending {@code Thread} to
1177      * override the {@link #run()} method.
1178      *
1179      * @see <a href="#inheritance">Inheritance when creating threads</a>
1180      */
1181     public Thread() {
1182         this(null, null, 0, null, 0, null);
1183     }
1184 
1185     /**
1186      * Initializes a new platform {@code Thread}. This constructor has the same
1187      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1188      * {@code (null, task, gname)}, where {@code gname} is a newly generated
1189      * name. Automatically generated names are of the form
1190      * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.
1191      *
1192      * <p> For a non-null task, invoking this constructor directly is equivalent to:
1193      * <pre>{@code Thread.ofPlatform().unstarted(task); }</pre>
1194      *
1195      * @param  task
1196      *         the object whose {@code run} method is invoked when this thread
1197      *         is started. If {@code null}, this classes {@code run} method does
1198      *         nothing.
1199      *
1200      * @see <a href="#inheritance">Inheritance when creating threads</a>
1201      */
1202     public Thread(Runnable task) {
1203         this(null, null, 0, task, 0, null);
1204     }
1205 
1206     /**
1207      * Creates a new Thread that inherits the given AccessControlContext
1208      * but thread-local variables are not inherited.
1209      * This is not a public constructor.
1210      */
1211     Thread(Runnable task, @SuppressWarnings("removal") AccessControlContext acc) {
1212         this(null, null, 0, task, 0, acc);
1213     }
1214 
1215     /**
1216      * Initializes a new platform {@code Thread}. This constructor has the same
1217      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1218      * {@code (group, task, gname)}, where {@code gname} is a newly generated
1219      * name. Automatically generated names are of the form
1220      * {@code "Thread-"+}<i>n</i>, where <i>n</i> is an integer.
1221      *
1222      * <p> For a non-null group and task, invoking this constructor directly is
1223      * equivalent to:
1224      * <pre>{@code Thread.ofPlatform().group(group).unstarted(task); }</pre>
1225      *
1226      * @param  group
1227      *         the thread group. If {@code null} and there is a security
1228      *         manager, the group is determined by {@linkplain
1229      *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.
1230      *         If there is not a security manager or {@code
1231      *         SecurityManager.getThreadGroup()} returns {@code null}, the group
1232      *         is set to the current thread's thread group.
1233      *
1234      * @param  task
1235      *         the object whose {@code run} method is invoked when this thread
1236      *         is started. If {@code null}, this thread's run method is invoked.
1237      *
1238      * @throws  SecurityException
1239      *          if the current thread cannot create a thread in the specified
1240      *          thread group
1241      *
1242      * @see <a href="#inheritance">Inheritance when creating threads</a>
1243      */
1244     public Thread(ThreadGroup group, Runnable task) {
1245         this(group, null, 0, task, 0, null);
1246     }
1247 
1248     /**
1249      * Initializes a new platform {@code Thread}. This constructor has the same
1250      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1251      * {@code (null, null, name)}.
1252      *
1253      * <p> This constructor is only useful when extending {@code Thread} to
1254      * override the {@link #run()} method.
1255      *
1256      * @param   name
1257      *          the name of the new thread
1258      *
1259      * @see <a href="#inheritance">Inheritance when creating threads</a>
1260      */
1261     public Thread(String name) {
1262         this(null, checkName(name), 0, null, 0, null);
1263     }
1264 
1265     /**
1266      * Initializes a new platform {@code Thread}. This constructor has the same
1267      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1268      * {@code (group, null, name)}.
1269      *
1270      * <p> This constructor is only useful when extending {@code Thread} to
1271      * override the {@link #run()} method.
1272      *
1273      * @param  group
1274      *         the thread group. If {@code null} and there is a security
1275      *         manager, the group is determined by {@linkplain
1276      *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.
1277      *         If there is not a security manager or {@code
1278      *         SecurityManager.getThreadGroup()} returns {@code null}, the group
1279      *         is set to the current thread's thread group.
1280      *
1281      * @param  name
1282      *         the name of the new thread
1283      *
1284      * @throws  SecurityException
1285      *          if the current thread cannot create a thread in the specified
1286      *          thread group
1287      *
1288      * @see <a href="#inheritance">Inheritance when creating threads</a>
1289      */
1290     public Thread(ThreadGroup group, String name) {
1291         this(group, checkName(name), 0, null, 0, null);
1292     }
1293 
1294     /**
1295      * Initializes a new platform {@code Thread}. This constructor has the same
1296      * effect as {@linkplain #Thread(ThreadGroup,Runnable,String) Thread}
1297      * {@code (null, task, name)}.
1298      *
1299      * <p> For a non-null task and name, invoking this constructor directly is
1300      * equivalent to:
1301      * <pre>{@code Thread.ofPlatform().name(name).unstarted(task); }</pre>
1302      *
1303      * @param  task
1304      *         the object whose {@code run} method is invoked when this thread
1305      *         is started. If {@code null}, this thread's run method is invoked.
1306      *
1307      * @param  name
1308      *         the name of the new thread
1309      *
1310      * @see <a href="#inheritance">Inheritance when creating threads</a>
1311      */
1312     public Thread(Runnable task, String name) {
1313         this(null, checkName(name), 0, task, 0, null);
1314     }
1315 
1316     /**
1317      * Initializes a new platform {@code Thread} so that it has {@code task}
1318      * as its run object, has the specified {@code name} as its name,
1319      * and belongs to the thread group referred to by {@code group}.
1320      *
1321      * <p>If there is a security manager, its
1322      * {@link SecurityManager#checkAccess(ThreadGroup) checkAccess}
1323      * method is invoked with the ThreadGroup as its argument.
1324      *
1325      * <p>In addition, its {@code checkPermission} method is invoked with
1326      * the {@code RuntimePermission("enableContextClassLoaderOverride")}
1327      * permission when invoked directly or indirectly by the constructor
1328      * of a subclass which overrides the {@code getContextClassLoader}
1329      * or {@code setContextClassLoader} methods.
1330      *
1331      * <p>The priority of the newly created thread is the smaller of
1332      * priority of the thread creating it and the maximum permitted
1333      * priority of the thread group. The method {@linkplain #setPriority
1334      * setPriority} may be used to change the priority to a new value.
1335      *
1336      * <p>The newly created thread is initially marked as being a daemon
1337      * thread if and only if the thread creating it is currently marked
1338      * as a daemon thread. The method {@linkplain #setDaemon setDaemon}
1339      * may be used to change whether or not a thread is a daemon.
1340      *
1341      * <p>For a non-null group, task, and name, invoking this constructor directly
1342      * is equivalent to:
1343      * <pre>{@code Thread.ofPlatform().group(group).name(name).unstarted(task); }</pre>
1344      *
1345      * @param  group
1346      *         the thread group. If {@code null} and there is a security
1347      *         manager, the group is determined by {@linkplain
1348      *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.
1349      *         If there is not a security manager or {@code
1350      *         SecurityManager.getThreadGroup()} returns {@code null}, the group
1351      *         is set to the current thread's thread group.
1352      *
1353      * @param  task
1354      *         the object whose {@code run} method is invoked when this thread
1355      *         is started. If {@code null}, this thread's run method is invoked.
1356      *
1357      * @param  name
1358      *         the name of the new thread
1359      *
1360      * @throws  SecurityException
1361      *          if the current thread cannot create a thread in the specified
1362      *          thread group or cannot override the context class loader methods.
1363      *
1364      * @see <a href="#inheritance">Inheritance when creating threads</a>
1365      */
1366     public Thread(ThreadGroup group, Runnable task, String name) {
1367         this(group, checkName(name), 0, task, 0, null);
1368     }
1369 
1370     /**
1371      * Initializes a new platform {@code Thread} so that it has {@code task}
1372      * as its run object, has the specified {@code name} as its name,
1373      * and belongs to the thread group referred to by {@code group}, and has
1374      * the specified <i>stack size</i>.
1375      *
1376      * <p>This constructor is identical to {@link
1377      * #Thread(ThreadGroup,Runnable,String)} with the exception of the fact
1378      * that it allows the thread stack size to be specified.  The stack size
1379      * is the approximate number of bytes of address space that the virtual
1380      * machine is to allocate for this thread's stack.  <b>The effect of the
1381      * {@code stackSize} parameter, if any, is highly platform dependent.</b>
1382      *
1383      * <p>On some platforms, specifying a higher value for the
1384      * {@code stackSize} parameter may allow a thread to achieve greater
1385      * recursion depth before throwing a {@link StackOverflowError}.
1386      * Similarly, specifying a lower value may allow a greater number of
1387      * threads to exist concurrently without throwing an {@link
1388      * OutOfMemoryError} (or other internal error).  The details of
1389      * the relationship between the value of the {@code stackSize} parameter
1390      * and the maximum recursion depth and concurrency level are
1391      * platform-dependent.  <b>On some platforms, the value of the
1392      * {@code stackSize} parameter may have no effect whatsoever.</b>
1393      *
1394      * <p>The virtual machine is free to treat the {@code stackSize}
1395      * parameter as a suggestion.  If the specified value is unreasonably low
1396      * for the platform, the virtual machine may instead use some
1397      * platform-specific minimum value; if the specified value is unreasonably
1398      * high, the virtual machine may instead use some platform-specific
1399      * maximum.  Likewise, the virtual machine is free to round the specified
1400      * value up or down as it sees fit (or to ignore it completely).
1401      *
1402      * <p>Specifying a value of zero for the {@code stackSize} parameter will
1403      * cause this constructor to behave exactly like the
1404      * {@code Thread(ThreadGroup, Runnable, String)} constructor.
1405      *
1406      * <p><i>Due to the platform-dependent nature of the behavior of this
1407      * constructor, extreme care should be exercised in its use.
1408      * The thread stack size necessary to perform a given computation will
1409      * likely vary from one JRE implementation to another.  In light of this
1410      * variation, careful tuning of the stack size parameter may be required,
1411      * and the tuning may need to be repeated for each JRE implementation on
1412      * which an application is to run.</i>
1413      *
1414      * <p>Implementation note: Java platform implementers are encouraged to
1415      * document their implementation's behavior with respect to the
1416      * {@code stackSize} parameter.
1417      *
1418      * <p>For a non-null group, task, and name, invoking this constructor directly
1419      * is equivalent to:
1420      * <pre>{@code Thread.ofPlatform().group(group).name(name).stackSize(stackSize).unstarted(task); }</pre>
1421      *
1422      * @param  group
1423      *         the thread group. If {@code null} and there is a security
1424      *         manager, the group is determined by {@linkplain
1425      *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.
1426      *         If there is not a security manager or {@code
1427      *         SecurityManager.getThreadGroup()} returns {@code null}, the group
1428      *         is set to the current thread's thread group.
1429      *
1430      * @param  task
1431      *         the object whose {@code run} method is invoked when this thread
1432      *         is started. If {@code null}, this thread's run method is invoked.
1433      *
1434      * @param  name
1435      *         the name of the new thread
1436      *
1437      * @param  stackSize
1438      *         the desired stack size for the new thread, or zero to indicate
1439      *         that this parameter is to be ignored.
1440      *
1441      * @throws  SecurityException
1442      *          if the current thread cannot create a thread in the specified
1443      *          thread group
1444      *
1445      * @since 1.4
1446      * @see <a href="#inheritance">Inheritance when creating threads</a>
1447      */
1448     public Thread(ThreadGroup group, Runnable task, String name, long stackSize) {
1449         this(group, checkName(name), 0, task, stackSize, null);
1450     }
1451 
1452     /**
1453      * Initializes a new platform {@code Thread} so that it has {@code task}
1454      * as its run object, has the specified {@code name} as its name,
1455      * belongs to the thread group referred to by {@code group}, has
1456      * the specified {@code stackSize}, and inherits initial values for
1457      * {@linkplain InheritableThreadLocal inheritable thread-local} variables
1458      * if {@code inheritThreadLocals} is {@code true}.
1459      *
1460      * <p> This constructor is identical to {@link
1461      * #Thread(ThreadGroup,Runnable,String,long)} with the added ability to
1462      * suppress, or not, the inheriting of initial values for inheritable
1463      * thread-local variables from the constructing thread. This allows for
1464      * finer grain control over inheritable thread-locals. Care must be taken
1465      * when passing a value of {@code false} for {@code inheritThreadLocals},
1466      * as it may lead to unexpected behavior if the new thread executes code
1467      * that expects a specific thread-local value to be inherited.
1468      *
1469      * <p> Specifying a value of {@code true} for the {@code inheritThreadLocals}
1470      * parameter will cause this constructor to behave exactly like the
1471      * {@code Thread(ThreadGroup, Runnable, String, long)} constructor.
1472      *
1473      * <p> For a non-null group, task, and name, invoking this constructor directly
1474      * is equivalent to:
1475      * <pre>{@code Thread.ofPlatform()
1476      *      .group(group)
1477      *      .name(name)
1478      *      .stackSize(stackSize)
1479      *      .inheritInheritableThreadLocals(inheritInheritableThreadLocals)
1480      *      .unstarted(task); }</pre>
1481      *
1482      * @param  group
1483      *         the thread group. If {@code null} and there is a security
1484      *         manager, the group is determined by {@linkplain
1485      *         SecurityManager#getThreadGroup SecurityManager.getThreadGroup()}.
1486      *         If there is not a security manager or {@code
1487      *         SecurityManager.getThreadGroup()} returns {@code null}, the group
1488      *         is set to the current thread's thread group.
1489      *
1490      * @param  task
1491      *         the object whose {@code run} method is invoked when this thread
1492      *         is started. If {@code null}, this thread's run method is invoked.
1493      *
1494      * @param  name
1495      *         the name of the new thread
1496      *
1497      * @param  stackSize
1498      *         the desired stack size for the new thread, or zero to indicate
1499      *         that this parameter is to be ignored
1500      *
1501      * @param  inheritInheritableThreadLocals
1502      *         if {@code true}, inherit initial values for inheritable
1503      *         thread-locals from the constructing thread, otherwise no initial
1504      *         values are inherited
1505      *
1506      * @throws  SecurityException
1507      *          if the current thread cannot create a thread in the specified
1508      *          thread group
1509      *
1510      * @since 9
1511      * @see <a href="#inheritance">Inheritance when creating threads</a>
1512      */
1513     public Thread(ThreadGroup group, Runnable task, String name,
1514                   long stackSize, boolean inheritInheritableThreadLocals) {
1515         this(group, checkName(name),
1516                 (inheritInheritableThreadLocals ? 0 : NO_INHERIT_THREAD_LOCALS),
1517                 task, stackSize, null);
1518     }
1519 
1520     /**
1521      * Creates a virtual thread to execute a task and schedules it to execute.
1522      *
1523      * <p> This method is equivalent to:
1524      * <pre>{@code Thread.ofVirtual().start(task); }</pre>
1525      *
1526      * @param task the object to run when the thread executes
1527      * @return a new, and started, virtual thread
1528      * @throws UnsupportedOperationException if preview features are not enabled
1529      * @see <a href="#inheritance">Inheritance when creating threads</a>
1530      * @since 19
1531      */
1532     @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
1533     public static Thread startVirtualThread(Runnable task) {
1534         Objects.requireNonNull(task);
1535         PreviewFeatures.ensureEnabled();
1536         var thread = ThreadBuilders.newVirtualThread(null, null, 0, task);
1537         thread.start();
1538         return thread;
1539     }
1540 
1541     /**
1542      * Returns {@code true} if this thread is a virtual thread. A virtual thread
1543      * is scheduled by the Java virtual machine rather than the operating system.
1544      *
1545      * @return {@code true} if this thread is a virtual thread
1546      *
1547      * @since 19
1548      */
1549     @PreviewFeature(feature = PreviewFeature.Feature.VIRTUAL_THREADS)
1550     public final boolean isVirtual() {
1551         return (this instanceof BaseVirtualThread);
1552     }
1553 
1554     /**
1555      * Schedules this thread to begin execution. The thread will execute
1556      * independently of the current thread.
1557      *
1558      * <p> A thread can be started at most once. In particular, a thread can not
1559      * be restarted after it has terminated.
1560      *
1561      * @throws IllegalThreadStateException if the thread was already started
1562      */
1563     public void start() {
1564         synchronized (this) {
1565             // zero status corresponds to state "NEW".
1566             if (holder.threadStatus != 0)
1567                 throw new IllegalThreadStateException();
1568             start0();
1569         }
1570     }
1571 
1572     /**
1573      * Schedules this thread to begin execution in the given thread container.
1574      * @throws IllegalStateException if the container is shutdown or closed
1575      * @throws IllegalThreadStateException if the thread has already been started
1576      */
1577     void start(ThreadContainer container) {
1578         synchronized (this) {
1579             // zero status corresponds to state "NEW".
1580             if (holder.threadStatus != 0)
1581                 throw new IllegalThreadStateException();
1582 
1583             // bind thread to container
1584             setThreadContainer(container);
1585 
1586             // start thread
1587             boolean started = false;
1588             container.onStart(this);  // may throw
1589             try {
1590                 // scoped values may be inherited
1591                 inheritScopedValueBindings(container);
1592 
1593                 start0();
1594                 started = true;
1595             } finally {
1596                 if (!started) {
1597                     container.onExit(this);
1598                 }
1599             }
1600         }
1601     }
1602 
1603     private native void start0();
1604 
1605     /**
1606      * This method is run by the thread when it executes. Subclasses of {@code
1607      * Thread} may override this method.
1608      *
1609      * <p> This method is not intended to be invoked directly. If this thread is a
1610      * platform thread created with a {@link Runnable} task then invoking this method
1611      * will invoke the task's {@code run} method. If this thread is a virtual thread
1612      * then invoking this method directly does nothing.
1613      *
1614      * @implSpec The default implementation executes the {@link Runnable} task that
1615      * the {@code Thread} was created with. If the thread was created without a task
1616      * then this method does nothing.
1617      */
1618     @Override
1619     public void run() {
1620         Runnable task = holder.task;
1621         if (task != null) {
1622             Object bindings = scopedValueBindings();
1623             runWith(bindings, task);
1624         }
1625     }
1626 
1627     /**
1628      * The VM recognizes this method as special, so any changes to the
1629      * name or signature require corresponding changes in
1630      * JVM_FindScopedValueBindings().
1631      */
1632     @Hidden
1633     @ForceInline
1634     private void runWith(Object bindings, Runnable op) {
1635         ensureMaterializedForStackWalk(bindings);
1636         op.run();
1637         Reference.reachabilityFence(bindings);
1638     }
1639 
1640     /**
1641      * Null out reference after Thread termination.
1642      */
1643     void clearReferences() {
1644         threadLocals = null;
1645         inheritableThreadLocals = null;
1646         inheritedAccessControlContext = null;
1647         if (uncaughtExceptionHandler != null)
1648             uncaughtExceptionHandler = null;
1649         if (nioBlocker != null)
1650             nioBlocker = null;
1651     }
1652 
1653     /**
1654      * This method is called by the VM to give a Thread
1655      * a chance to clean up before it actually exits.
1656      */
1657     private void exit() {
1658         // pop any remaining scopes from the stack, this may block
1659         if (headStackableScopes != null) {
1660             StackableScope.popAll();
1661         }
1662 
1663         // notify container that thread is exiting
1664         ThreadContainer container = threadContainer();
1665         if (container != null) {
1666             container.onExit(this);
1667         }
1668 
1669         try {
1670             if (threadLocals != null && TerminatingThreadLocal.REGISTRY.isPresent()) {
1671                 TerminatingThreadLocal.threadTerminated();
1672             }
1673         } finally {
1674             clearReferences();
1675         }
1676     }
1677 
1678     /**
1679      * Throws {@code UnsupportedOperationException}.
1680      *
1681      * @throws  UnsupportedOperationException always
1682      *
1683      * @deprecated This method was originally specified to "stop" a victim
1684      *       thread by causing the victim thread to throw a {@link ThreadDeath}.
1685      *       It was inherently unsafe. Stopping a thread caused it to unlock
1686      *       all of the monitors that it had locked (as a natural consequence
1687      *       of the {@code ThreadDeath} exception propagating up the stack). If
1688      *       any of the objects previously protected by these monitors were in
1689      *       an inconsistent state, the damaged objects became visible to
1690      *       other threads, potentially resulting in arbitrary behavior.
1691      *       Usages of {@code stop} should be replaced by code that simply
1692      *       modifies some variable to indicate that the target thread should
1693      *       stop running.  The target thread should check this variable
1694      *       regularly, and return from its run method in an orderly fashion
1695      *       if the variable indicates that it is to stop running.  If the
1696      *       target thread waits for long periods (on a condition variable,
1697      *       for example), the {@code interrupt} method should be used to
1698      *       interrupt the wait.
1699      *       For more information, see
1700      *       <a href="{@docRoot}/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
1701      *       are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
1702      */
1703     @Deprecated(since="1.2", forRemoval=true)
1704     public final void stop() {
1705         throw new UnsupportedOperationException();
1706     }
1707 
1708     /**
1709      * Interrupts this thread.
1710      *
1711      * <p> Unless the current thread is interrupting itself, which is
1712      * always permitted, the {@link #checkAccess() checkAccess} method
1713      * of this thread is invoked, which may cause a {@link
1714      * SecurityException} to be thrown.
1715      *
1716      * <p> If this thread is blocked in an invocation of the {@link
1717      * Object#wait() wait()}, {@link Object#wait(long) wait(long)}, or {@link
1718      * Object#wait(long, int) wait(long, int)} methods of the {@link Object}
1719      * class, or of the {@link #join()}, {@link #join(long)}, {@link
1720      * #join(long, int)}, {@link #sleep(long)}, or {@link #sleep(long, int)}
1721      * methods of this class, then its interrupt status will be cleared and it
1722      * will receive an {@link InterruptedException}.
1723      *
1724      * <p> If this thread is blocked in an I/O operation upon an {@link
1725      * java.nio.channels.InterruptibleChannel InterruptibleChannel}
1726      * then the channel will be closed, the thread's interrupt
1727      * status will be set, and the thread will receive a {@link
1728      * java.nio.channels.ClosedByInterruptException}.
1729      *
1730      * <p> If this thread is blocked in a {@link java.nio.channels.Selector}
1731      * then the thread's interrupt status will be set and it will return
1732      * immediately from the selection operation, possibly with a non-zero
1733      * value, just as if the selector's {@link
1734      * java.nio.channels.Selector#wakeup wakeup} method were invoked.
1735      *
1736      * <p> If none of the previous conditions hold then this thread's interrupt
1737      * status will be set. </p>
1738      *
1739      * <p> Interrupting a thread that is not alive need not have any effect.
1740      *
1741      * @implNote In the JDK Reference Implementation, interruption of a thread
1742      * that is not alive still records that the interrupt request was made and
1743      * will report it via {@link #interrupted} and {@link #isInterrupted()}.
1744      *
1745      * @throws  SecurityException
1746      *          if the current thread cannot modify this thread
1747      *
1748      * @revised 6.0, 14
1749      */
1750     public void interrupt() {
1751         if (this != Thread.currentThread()) {
1752             checkAccess();
1753 
1754             // thread may be blocked in an I/O operation
1755             synchronized (interruptLock) {
1756                 Interruptible b = nioBlocker;
1757                 if (b != null) {
1758                     interrupted = true;
1759                     interrupt0();  // inform VM of interrupt
1760                     b.interrupt(this);
1761                     return;
1762                 }
1763             }
1764         }
1765         interrupted = true;
1766         interrupt0();  // inform VM of interrupt
1767     }
1768 
1769     /**
1770      * Tests whether the current thread has been interrupted.  The
1771      * <i>interrupted status</i> of the thread is cleared by this method.  In
1772      * other words, if this method were to be called twice in succession, the
1773      * second call would return false (unless the current thread were
1774      * interrupted again, after the first call had cleared its interrupted
1775      * status and before the second call had examined it).
1776      *
1777      * @return  {@code true} if the current thread has been interrupted;
1778      *          {@code false} otherwise.
1779      * @see #isInterrupted()
1780      * @revised 6.0, 14
1781      */
1782     public static boolean interrupted() {
1783         return currentThread().getAndClearInterrupt();
1784     }
1785 
1786     /**
1787      * Tests whether this thread has been interrupted.  The <i>interrupted
1788      * status</i> of the thread is unaffected by this method.
1789      *
1790      * @return  {@code true} if this thread has been interrupted;
1791      *          {@code false} otherwise.
1792      * @see     #interrupted()
1793      * @revised 6.0, 14
1794      */
1795     public boolean isInterrupted() {
1796         return interrupted;
1797     }
1798 
1799     final void setInterrupt() {
1800         // assert Thread.currentCarrierThread() == this;
1801         if (!interrupted) {
1802             interrupted = true;
1803             interrupt0();  // inform VM of interrupt
1804         }
1805     }
1806 
1807     final void clearInterrupt() {
1808         // assert Thread.currentCarrierThread() == this;
1809         if (interrupted) {
1810             interrupted = false;
1811             clearInterruptEvent();
1812         }
1813     }
1814 
1815     boolean getAndClearInterrupt() {
1816         boolean oldValue = interrupted;
1817         // We may have been interrupted the moment after we read the field,
1818         // so only clear the field if we saw that it was set and will return
1819         // true; otherwise we could lose an interrupt.
1820         if (oldValue) {
1821             interrupted = false;
1822             clearInterruptEvent();
1823         }
1824         return oldValue;
1825     }
1826 
1827     /**
1828      * Tests if this thread is alive. A thread is alive if it has
1829      * been started and has not yet terminated.
1830      *
1831      * @return  {@code true} if this thread is alive;
1832      *          {@code false} otherwise.
1833      */
1834     public final boolean isAlive() {
1835         return alive();
1836     }
1837 
1838     /**
1839      * Returns true if this thread is alive.
1840      * This method is non-final so it can be overridden.
1841      */
1842     boolean alive() {
1843         return isAlive0();
1844     }
1845     private native boolean isAlive0();
1846 
1847     /**
1848      * Throws {@code UnsupportedOperationException}.
1849      *
1850      * @throws  UnsupportedOperationException always
1851      *
1852      * @deprecated This method was originally specified to suspend a thread.
1853      *     It was inherently deadlock-prone. If the target thread held a lock on
1854      *     a monitor protecting a critical system resource when it was suspended,
1855      *     no thread could access the resource until the target thread was resumed.
1856      *     If the thread intending to resume the target thread attempted to lock
1857      *     the monitor prior to calling {@code resume}, deadlock would result.
1858      *     Such deadlocks typically manifested themselves as "frozen" processes.
1859      *     For more information, see
1860      *     <a href="{@docRoot}/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
1861      *     are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
1862      */
1863     @Deprecated(since="1.2", forRemoval=true)
1864     public final void suspend() {
1865         throw new UnsupportedOperationException();
1866     }
1867 
1868     /**
1869      * Throws {@code UnsupportedOperationException}.
1870      *
1871      * @throws  UnsupportedOperationException always
1872      *
1873      * @deprecated This method was originally specified to resume a thread
1874      *     suspended with {@link #suspend()}. Suspending a thread was
1875      *     inherently deadlock-prone.
1876      *     For more information, see
1877      *     <a href="{@docRoot}/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html">Why
1878      *     are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.
1879      */
1880     @Deprecated(since="1.2", forRemoval=true)
1881     public final void resume() {
1882         throw new UnsupportedOperationException();
1883     }
1884 
1885     /**
1886      * Changes the priority of this thread.
1887      *
1888      * For platform threads, the priority is set to the smaller of the specified
1889      * {@code newPriority} and the maximum permitted priority of the thread's
1890      * {@linkplain ThreadGroup thread group}.
1891      *
1892      * The priority of a virtual thread is always {@link Thread#NORM_PRIORITY}
1893      * and {@code newPriority} is ignored.
1894      *
1895      * @param newPriority the new thread priority
1896      * @throws  IllegalArgumentException if the priority is not in the
1897      *          range {@code MIN_PRIORITY} to {@code MAX_PRIORITY}.
1898      * @throws  SecurityException
1899      *          if {@link #checkAccess} determines that the current
1900      *          thread cannot modify this thread
1901      * @see #setPriority(int)
1902      * @see ThreadGroup#getMaxPriority()
1903      */
1904     public final void setPriority(int newPriority) {
1905         checkAccess();
1906         if (newPriority > MAX_PRIORITY || newPriority < MIN_PRIORITY) {
1907             throw new IllegalArgumentException();
1908         }
1909         if (!isVirtual()) {
1910             priority(newPriority);
1911         }
1912     }
1913 
1914     void priority(int newPriority) {
1915         ThreadGroup g = holder.group;
1916         if (g != null) {
1917             int maxPriority = g.getMaxPriority();
1918             if (newPriority > maxPriority) {
1919                 newPriority = maxPriority;
1920             }
1921             setPriority0(holder.priority = newPriority);
1922         }
1923     }
1924 
1925     /**
1926      * Returns this thread's priority.
1927      *
1928      * <p> The priority of a virtual thread is always {@link Thread#NORM_PRIORITY}.
1929      *
1930      * @return  this thread's priority.
1931      * @see     #setPriority
1932      */
1933     public final int getPriority() {
1934         if (isVirtual()) {
1935             return Thread.NORM_PRIORITY;
1936         } else {
1937             return holder.priority;
1938         }
1939     }
1940 
1941     /**
1942      * Changes the name of this thread to be equal to the argument {@code name}.
1943      * <p>
1944      * First the {@code checkAccess} method of this thread is called
1945      * with no arguments. This may result in throwing a
1946      * {@code SecurityException}.
1947      *
1948      * @implNote In the JDK Reference Implementation, if this thread is the
1949      * current thread, and it's a platform thread that was not attached to the
1950      * VM with the Java Native Interface
1951      * <a href="{@docRoot}/../specs/jni/invocation.html#attachcurrentthread">
1952      * AttachCurrentThread</a> function, then this method will set the operating
1953      * system thread name. This may be useful for debugging and troubleshooting
1954      * purposes.
1955      *
1956      * @param      name   the new name for this thread.
1957      * @throws     SecurityException  if the current thread cannot modify this
1958      *             thread.
1959      * @see        #getName
1960      * @see        #checkAccess()
1961      */
1962     public final synchronized void setName(String name) {
1963         checkAccess();
1964         if (name == null) {
1965             throw new NullPointerException("name cannot be null");
1966         }
1967         this.name = name;
1968         if (!isVirtual() && Thread.currentThread() == this) {
1969             setNativeName(name);
1970         }
1971     }
1972 
1973     /**
1974      * Returns this thread's name.
1975      *
1976      * @return  this thread's name.
1977      * @see     #setName(String)
1978      */
1979     public final String getName() {
1980         return name;
1981     }
1982 
1983     /**
1984      * Returns the thread's thread group or {@code null} if the thread has
1985      * terminated.
1986      *
1987      * <p> The thread group returned for a virtual thread is the special
1988      * <a href="ThreadGroup.html#virtualthreadgroup"><em>ThreadGroup for
1989      * virtual threads</em></a>.
1990      *
1991      * @return  this thread's thread group or {@code null}
1992      */
1993     public final ThreadGroup getThreadGroup() {
1994         if (isTerminated()) {
1995             return null;
1996         } else {
1997             return isVirtual() ? virtualThreadGroup() : holder.group;
1998         }
1999     }
2000 
2001     /**
2002      * Returns an estimate of the number of {@linkplain #isAlive() live}
2003      * platform threads in the current thread's thread group and its subgroups.
2004      * Virtual threads are not included in the estimate.
2005      *
2006      * <p> The value returned is only an estimate because the number of
2007      * threads may change dynamically while this method traverses internal
2008      * data structures, and might be affected by the presence of certain
2009      * system threads. This method is intended primarily for debugging
2010      * and monitoring purposes.
2011      *
2012      * @return  an estimate of the number of live platform threads in the
2013      *          current thread's thread group and in any other thread group
2014      *          that has the current thread's thread group as an ancestor
2015      */
2016     public static int activeCount() {
2017         return currentThread().getThreadGroup().activeCount();
2018     }
2019 
2020     /**
2021      * Copies into the specified array every {@linkplain #isAlive() live}
2022      * platform thread in the current thread's thread group and its subgroups.
2023      * This method simply invokes the {@link java.lang.ThreadGroup#enumerate(Thread[])}
2024      * method of the current thread's thread group. Virtual threads are
2025      * not enumerated by this method.
2026      *
2027      * <p> An application might use the {@linkplain #activeCount activeCount}
2028      * method to get an estimate of how big the array should be, however
2029      * <i>if the array is too short to hold all the threads, the extra threads
2030      * are silently ignored.</i>  If it is critical to obtain every live
2031      * thread in the current thread's thread group and its subgroups, the
2032      * invoker should verify that the returned int value is strictly less
2033      * than the length of {@code tarray}.
2034      *
2035      * <p> Due to the inherent race condition in this method, it is recommended
2036      * that the method only be used for debugging and monitoring purposes.
2037      *
2038      * @param  tarray
2039      *         an array into which to put the list of threads
2040      *
2041      * @return  the number of threads put into the array
2042      *
2043      * @throws  SecurityException
2044      *          if {@link java.lang.ThreadGroup#checkAccess} determines that
2045      *          the current thread cannot access its thread group
2046      */
2047     public static int enumerate(Thread[] tarray) {
2048         return currentThread().getThreadGroup().enumerate(tarray);
2049     }
2050 
2051     /**
2052      * Throws {@code UnsupportedOperationException}.
2053      *
2054      * @return     nothing
2055      *
2056      * @deprecated This method was originally designed to count the number of
2057      *             stack frames but the results were never well-defined and it
2058      *             depended on thread-suspension.
2059      *             This method is subject to removal in a future version of Java SE.
2060      * @see        StackWalker
2061      */
2062     @Deprecated(since="1.2", forRemoval=true)
2063     public int countStackFrames() {
2064         throw new UnsupportedOperationException();
2065     }
2066 
2067     /**
2068      * Waits at most {@code millis} milliseconds for this thread to terminate.
2069      * A timeout of {@code 0} means to wait forever.
2070      * This method returns immediately, without waiting, if the thread has not
2071      * been {@link #start() started}.
2072      *
2073      * @implNote
2074      * For platform threads, the implementation uses a loop of {@code this.wait}
2075      * calls conditioned on {@code this.isAlive}. As a thread terminates the
2076      * {@code this.notifyAll} method is invoked. It is recommended that
2077      * applications not use {@code wait}, {@code notify}, or
2078      * {@code notifyAll} on {@code Thread} instances.
2079      *
2080      * @param  millis
2081      *         the time to wait in milliseconds
2082      *
2083      * @throws  IllegalArgumentException
2084      *          if the value of {@code millis} is negative
2085      *
2086      * @throws  InterruptedException
2087      *          if any thread has interrupted the current thread. The
2088      *          <i>interrupted status</i> of the current thread is
2089      *          cleared when this exception is thrown.
2090      */
2091     public final void join(long millis) throws InterruptedException {
2092         if (millis < 0)
2093             throw new IllegalArgumentException("timeout value is negative");
2094 
2095         if (this instanceof VirtualThread vthread) {
2096             if (isAlive()) {
2097                 long nanos = MILLISECONDS.toNanos(millis);
2098                 vthread.joinNanos(nanos);
2099             }
2100             return;
2101         }
2102 
2103         synchronized (this) {
2104             if (millis > 0) {
2105                 if (isAlive()) {
2106                     final long startTime = System.nanoTime();
2107                     long delay = millis;
2108                     do {
2109                         wait(delay);
2110                     } while (isAlive() && (delay = millis -
2111                              NANOSECONDS.toMillis(System.nanoTime() - startTime)) > 0);
2112                 }
2113             } else {
2114                 while (isAlive()) {
2115                     wait(0);
2116                 }
2117             }
2118         }
2119     }
2120 
2121     /**
2122      * Waits at most {@code millis} milliseconds plus
2123      * {@code nanos} nanoseconds for this thread to terminate.
2124      * If both arguments are {@code 0}, it means to wait forever.
2125      * This method returns immediately, without waiting, if the thread has not
2126      * been {@link #start() started}.
2127      *
2128      * @implNote
2129      * For platform threads, the implementation uses a loop of {@code this.wait}
2130      * calls conditioned on {@code this.isAlive}. As a thread terminates the
2131      * {@code this.notifyAll} method is invoked. It is recommended that
2132      * applications not use {@code wait}, {@code notify}, or
2133      * {@code notifyAll} on {@code Thread} instances.
2134      *
2135      * @param  millis
2136      *         the time to wait in milliseconds
2137      *
2138      * @param  nanos
2139      *         {@code 0-999999} additional nanoseconds to wait
2140      *
2141      * @throws  IllegalArgumentException
2142      *          if the value of {@code millis} is negative, or the value
2143      *          of {@code nanos} is not in the range {@code 0-999999}
2144      *
2145      * @throws  InterruptedException
2146      *          if any thread has interrupted the current thread. The
2147      *          <i>interrupted status</i> of the current thread is
2148      *          cleared when this exception is thrown.
2149      */
2150     public final void join(long millis, int nanos) throws InterruptedException {
2151         if (millis < 0) {
2152             throw new IllegalArgumentException("timeout value is negative");
2153         }
2154 
2155         if (nanos < 0 || nanos > 999999) {
2156             throw new IllegalArgumentException("nanosecond timeout value out of range");
2157         }
2158 
2159         if (this instanceof VirtualThread vthread) {
2160             if (isAlive()) {
2161                 // convert arguments to a total in nanoseconds
2162                 long totalNanos = MILLISECONDS.toNanos(millis);
2163                 totalNanos += Math.min(Long.MAX_VALUE - totalNanos, nanos);
2164                 vthread.joinNanos(totalNanos);
2165             }
2166             return;
2167         }
2168 
2169         if (nanos > 0 && millis < Long.MAX_VALUE) {
2170             millis++;
2171         }
2172         join(millis);
2173     }
2174 
2175     /**
2176      * Waits for this thread to terminate.
2177      *
2178      * <p> An invocation of this method behaves in exactly the same
2179      * way as the invocation
2180      *
2181      * <blockquote>
2182      * {@linkplain #join(long) join}{@code (0)}
2183      * </blockquote>
2184      *
2185      * @throws  InterruptedException
2186      *          if any thread has interrupted the current thread. The
2187      *          <i>interrupted status</i> of the current thread is
2188      *          cleared when this exception is thrown.
2189      */
2190     public final void join() throws InterruptedException {
2191         join(0);
2192     }
2193 
2194     /**
2195      * Waits for this thread to terminate for up to the given waiting duration.
2196      *
2197      * <p> This method does not wait if the duration to wait is less than or
2198      * equal to zero. In this case, the method just tests if the thread has
2199      * terminated.
2200      *
2201      * @param   duration
2202      *          the maximum duration to wait
2203      *
2204      * @return  {@code true} if the thread has terminated, {@code false} if the
2205      *          thread has not terminated
2206      *
2207      * @throws  InterruptedException
2208      *          if the current thread is interrupted while waiting.
2209      *          The <i>interrupted status</i> of the current thread is cleared
2210      *          when this exception is thrown.
2211      *
2212      * @throws  IllegalThreadStateException
2213      *          if this thread has not been started.
2214      *
2215      * @since 19
2216      */
2217     public final boolean join(Duration duration) throws InterruptedException {
2218         long nanos = NANOSECONDS.convert(duration); // MAX_VALUE if > 292 years
2219 
2220         Thread.State state = threadState();
2221         if (state == State.NEW)
2222             throw new IllegalThreadStateException("Thread not started");
2223         if (state == State.TERMINATED)
2224             return true;
2225         if (nanos <= 0)
2226             return false;
2227 
2228         if (this instanceof VirtualThread vthread) {
2229             return vthread.joinNanos(nanos);
2230         }
2231 
2232         // convert to milliseconds
2233         long millis = MILLISECONDS.convert(nanos, NANOSECONDS);
2234         if (nanos > NANOSECONDS.convert(millis, MILLISECONDS)) {
2235             millis += 1L;
2236         }
2237         join(millis);
2238         return isTerminated();
2239     }
2240 
2241     /**
2242      * Prints a stack trace of the current thread to the standard error stream.
2243      * This method is useful for debugging.
2244      */
2245     public static void dumpStack() {
2246         new Exception("Stack trace").printStackTrace();
2247     }
2248 
2249     /**
2250      * Marks this thread as either a <i>daemon</i> or <i>non-daemon</i> thread.
2251      * The <a href="Runtime.html#shutdown">shutdown sequence</a> begins when all
2252      * started non-daemon threads have terminated.
2253      *
2254      * <p> The daemon status of a virtual thread is always {@code true} and cannot be
2255      * changed by this method to {@code false}.
2256      *
2257      * <p> This method must be invoked before the thread is started. The behavior
2258      * of this method when the thread has terminated is not specified.
2259      *
2260      * @param  on
2261      *         if {@code true}, marks this thread as a daemon thread
2262      *
2263      * @throws  IllegalArgumentException
2264      *          if this is a virtual thread and {@code on} is false
2265      * @throws  IllegalThreadStateException
2266      *          if this thread is {@linkplain #isAlive alive}
2267      * @throws  SecurityException
2268      *          if {@link #checkAccess} determines that the current
2269      *          thread cannot modify this thread
2270      */
2271     public final void setDaemon(boolean on) {
2272         checkAccess();
2273         if (isVirtual() && !on)
2274             throw new IllegalArgumentException("'false' not legal for virtual threads");
2275         if (isAlive())
2276             throw new IllegalThreadStateException();
2277         if (!isVirtual())
2278             daemon(on);
2279     }
2280 
2281     void daemon(boolean on) {
2282         holder.daemon = on;
2283     }
2284 
2285     /**
2286      * Tests if this thread is a daemon thread.
2287      * The daemon status of a virtual thread is always {@code true}.
2288      *
2289      * @return  {@code true} if this thread is a daemon thread;
2290      *          {@code false} otherwise.
2291      * @see     #setDaemon(boolean)
2292      */
2293     public final boolean isDaemon() {
2294         if (isVirtual()) {
2295             return true;
2296         } else {
2297             return holder.daemon;
2298         }
2299     }
2300 
2301     /**
2302      * Determines if the currently running thread has permission to
2303      * modify this thread.
2304      * <p>
2305      * If there is a security manager, its {@code checkAccess} method
2306      * is called with this thread as its argument. This may result in
2307      * throwing a {@code SecurityException}.
2308      *
2309      * @throws  SecurityException  if the current thread is not allowed to
2310      *          access this thread.
2311      * @see        SecurityManager#checkAccess(Thread)
2312      * @deprecated This method is only useful in conjunction with
2313      *       {@linkplain SecurityManager the Security Manager}, which is
2314      *       deprecated and subject to removal in a future release.
2315      *       Consequently, this method is also deprecated and subject to
2316      *       removal. There is no replacement for the Security Manager or this
2317      *       method.
2318      */
2319     @Deprecated(since="17", forRemoval=true)
2320     public final void checkAccess() {
2321         @SuppressWarnings("removal")
2322         SecurityManager security = System.getSecurityManager();
2323         if (security != null) {
2324             security.checkAccess(this);
2325         }
2326     }
2327 
2328     /**
2329      * Returns a string representation of this thread. The string representation
2330      * will usually include the thread's {@linkplain #threadId() identifier} and
2331      * name. The default implementation for platform threads includes the thread's
2332      * identifier, name, priority, and the name of the thread group.
2333      *
2334      * @return  a string representation of this thread.
2335      */
2336     public String toString() {
2337         StringBuilder sb = new StringBuilder("Thread[#");
2338         sb.append(threadId());
2339         sb.append(",");
2340         sb.append(getName());
2341         sb.append(",");
2342         sb.append(getPriority());
2343         sb.append(",");
2344         ThreadGroup group = getThreadGroup();
2345         if (group != null)
2346             sb.append(group.getName());
2347         sb.append("]");
2348         return sb.toString();
2349     }
2350 
2351     /**
2352      * Returns the context {@code ClassLoader} for this thread.
2353      * The context {@code ClassLoader} may be set by the creator of the thread
2354      * for use by code running in this thread when loading classes and resources.
2355      * If not {@linkplain #setContextClassLoader set}, the default is to inherit
2356      * the context class loader from the parent thread.
2357      *
2358      * <p> The context {@code ClassLoader} of the primordial thread is typically
2359      * set to the class loader used to load the application.
2360      *
2361      * @return  the context {@code ClassLoader} for this thread, or {@code null}
2362      *          indicating the system class loader (or, failing that, the
2363      *          bootstrap class loader)
2364      *
2365      * @throws  SecurityException
2366      *          if a security manager is present, and the caller's class loader
2367      *          is not {@code null} and is not the same as or an ancestor of the
2368      *          context class loader, and the caller does not have the
2369      *          {@link RuntimePermission}{@code ("getClassLoader")}
2370      *
2371      * @since 1.2
2372      */
2373     @CallerSensitive
2374     public ClassLoader getContextClassLoader() {
2375         ClassLoader cl = this.contextClassLoader;
2376         if (cl == null)
2377             return null;
2378         if (!isSupportedClassLoader(cl))
2379             cl = ClassLoader.getSystemClassLoader();
2380         @SuppressWarnings("removal")
2381         SecurityManager sm = System.getSecurityManager();
2382         if (sm != null) {
2383             Class<?> caller = Reflection.getCallerClass();
2384             ClassLoader.checkClassLoaderPermission(cl, caller);
2385         }
2386         return cl;
2387     }
2388 
2389     /**
2390      * Sets the context {@code ClassLoader} for this thread.
2391      *
2392      * <p> The context {@code ClassLoader} may be set by the creator of the thread
2393      * for use by code running in this thread when loading classes and resources.
2394      *
2395      * <p> The context {@code ClassLoader} cannot be set when the thread is
2396      * {@linkplain Thread.Builder#allowSetThreadLocals(boolean) not allowed} to have
2397      * its own copy of thread local variables.
2398      *
2399      * <p> If a security manager is present, its {@link
2400      * SecurityManager#checkPermission(java.security.Permission) checkPermission}
2401      * method is invoked with a {@link RuntimePermission RuntimePermission}{@code
2402      * ("setContextClassLoader")} permission to see if setting the context
2403      * ClassLoader is permitted.
2404      *
2405      * @param  cl
2406      *         the context ClassLoader for this Thread, or null  indicating the
2407      *         system class loader (or, failing that, the bootstrap class loader)
2408      *
2409      * @throws  UnsupportedOperationException if this thread is not allowed
2410      *          to set values for its copy of thread-local variables
2411      *
2412      * @throws  SecurityException
2413      *          if the current thread cannot set the context ClassLoader
2414      *
2415      * @since 1.2
2416      */
2417     public void setContextClassLoader(ClassLoader cl) {
2418         @SuppressWarnings("removal")
2419         SecurityManager sm = System.getSecurityManager();
2420         if (sm != null) {
2421             sm.checkPermission(new RuntimePermission("setContextClassLoader"));
2422         }
2423         if (!isSupportedClassLoader(contextClassLoader)) {
2424             throw new UnsupportedOperationException(
2425                 "The context class loader cannot be set");
2426         }
2427         contextClassLoader = cl;
2428     }
2429 
2430     /**
2431      * Returns true if the given ClassLoader is a "supported" class loader. All
2432      * class loaders, except ClassLoaders.NOT_SUPPORTED, are considered supported.
2433      * This method allows the initialization of ClassLoaders to be delayed until
2434      * it is required.
2435      */
2436     private static boolean isSupportedClassLoader(ClassLoader loader) {
2437         if (loader == null)
2438             return true;
2439         if (loader == jdk.internal.loader.ClassLoaders.appClassLoader())
2440             return true;
2441         return loader != Constants.NOT_SUPPORTED_CLASSLOADER;
2442     }
2443 
2444     /**
2445      * Returns {@code true} if and only if the current thread holds the
2446      * monitor lock on the specified object.
2447      *
2448      * <p>This method is designed to allow a program to assert that
2449      * the current thread already holds a specified lock:
2450      * <pre>
2451      *     assert Thread.holdsLock(obj);
2452      * </pre>
2453      *
2454      * @param  obj the object on which to test lock ownership
2455      * @return {@code true} if the current thread holds the monitor lock on
2456      *         the specified object.
2457      * @since 1.4
2458      */
2459     public static native boolean holdsLock(Object obj);
2460 
2461     private static final StackTraceElement[] EMPTY_STACK_TRACE
2462         = new StackTraceElement[0];
2463 
2464     /**
2465      * Returns an array of stack trace elements representing the stack dump
2466      * of this thread.  This method will return a zero-length array if
2467      * this thread has not started, has started but has not yet been
2468      * scheduled to run by the system, or has terminated.
2469      * If the returned array is of non-zero length then the first element of
2470      * the array represents the top of the stack, which is the most recent
2471      * method invocation in the sequence.  The last element of the array
2472      * represents the bottom of the stack, which is the least recent method
2473      * invocation in the sequence.
2474      *
2475      * <p>If there is a security manager, and this thread is not
2476      * the current thread, then the security manager's
2477      * {@code checkPermission} method is called with a
2478      * {@code RuntimePermission("getStackTrace")} permission
2479      * to see if it's ok to get the stack trace.
2480      *
2481      * <p>Some virtual machines may, under some circumstances, omit one
2482      * or more stack frames from the stack trace.  In the extreme case,
2483      * a virtual machine that has no stack trace information concerning
2484      * this thread is permitted to return a zero-length array from this
2485      * method.
2486      *
2487      * @return an array of {@code StackTraceElement},
2488      * each represents one stack frame.
2489      *
2490      * @throws SecurityException
2491      *        if a security manager exists and its
2492      *        {@code checkPermission} method doesn't allow
2493      *        getting the stack trace of thread.
2494      * @see Throwable#getStackTrace
2495      *
2496      * @since 1.5
2497      */
2498     public StackTraceElement[] getStackTrace() {
2499         if (this != Thread.currentThread()) {
2500             // check for getStackTrace permission
2501             @SuppressWarnings("removal")
2502             SecurityManager security = System.getSecurityManager();
2503             if (security != null) {
2504                 security.checkPermission(SecurityConstants.GET_STACK_TRACE_PERMISSION);
2505             }
2506             // optimization so we do not call into the vm for threads that
2507             // have not yet started or have terminated
2508             if (!isAlive()) {
2509                 return EMPTY_STACK_TRACE;
2510             }
2511             StackTraceElement[] stackTrace = asyncGetStackTrace();
2512             return (stackTrace != null) ? stackTrace : EMPTY_STACK_TRACE;
2513         } else {
2514             return (new Exception()).getStackTrace();
2515         }
2516     }
2517 
2518     /**
2519      * Returns an array of stack trace elements representing the stack dump of
2520      * this thread. Returns null if the stack trace cannot be obtained. In
2521      * the default implementation, null is returned if the thread is a virtual
2522      * thread that is not mounted or the thread is a platform thread that has
2523      * terminated.
2524      */
2525     StackTraceElement[] asyncGetStackTrace() {
2526         Object stackTrace = getStackTrace0();
2527         if (stackTrace == null) {
2528             return null;
2529         }
2530         StackTraceElement[] stes = (StackTraceElement[]) stackTrace;
2531         if (stes.length == 0) {
2532             return null;
2533         } else {
2534             return StackTraceElement.of(stes);
2535         }
2536     }
2537 
2538     private native Object getStackTrace0();
2539 
2540     /**
2541      * Returns a map of stack traces for all live platform threads. The map
2542      * does not include virtual threads.
2543      * The map keys are threads and each map value is an array of
2544      * {@code StackTraceElement} that represents the stack dump
2545      * of the corresponding {@code Thread}.
2546      * The returned stack traces are in the format specified for
2547      * the {@link #getStackTrace getStackTrace} method.
2548      *
2549      * <p>The threads may be executing while this method is called.
2550      * The stack trace of each thread only represents a snapshot and
2551      * each stack trace may be obtained at different time.  A zero-length
2552      * array will be returned in the map value if the virtual machine has
2553      * no stack trace information about a thread.
2554      *
2555      * <p>If there is a security manager, then the security manager's
2556      * {@code checkPermission} method is called with a
2557      * {@code RuntimePermission("getStackTrace")} permission as well as
2558      * {@code RuntimePermission("modifyThreadGroup")} permission
2559      * to see if it is ok to get the stack trace of all threads.
2560      *
2561      * @return a {@code Map} from {@code Thread} to an array of
2562      * {@code StackTraceElement} that represents the stack trace of
2563      * the corresponding thread.
2564      *
2565      * @throws SecurityException
2566      *        if a security manager exists and its
2567      *        {@code checkPermission} method doesn't allow
2568      *        getting the stack trace of thread.
2569      * @see #getStackTrace
2570      * @see Throwable#getStackTrace
2571      *
2572      * @since 1.5
2573      */
2574     public static Map<Thread, StackTraceElement[]> getAllStackTraces() {
2575         // check for getStackTrace permission
2576         @SuppressWarnings("removal")
2577         SecurityManager security = System.getSecurityManager();
2578         if (security != null) {
2579             security.checkPermission(SecurityConstants.GET_STACK_TRACE_PERMISSION);
2580             security.checkPermission(SecurityConstants.MODIFY_THREADGROUP_PERMISSION);
2581         }
2582 
2583         // Get a snapshot of the list of all threads
2584         Thread[] threads = getThreads();
2585         StackTraceElement[][] traces = dumpThreads(threads);
2586         Map<Thread, StackTraceElement[]> m = HashMap.newHashMap(threads.length);
2587         for (int i = 0; i < threads.length; i++) {
2588             StackTraceElement[] stackTrace = traces[i];
2589             if (stackTrace != null) {
2590                 m.put(threads[i], stackTrace);
2591             }
2592             // else terminated so we don't put it in the map
2593         }
2594         return m;
2595     }
2596 
2597     /** cache of subclass security audit results */
2598     private static class Caches {
2599         /** cache of subclass security audit results */
2600         static final ClassValue<Boolean> subclassAudits =
2601             new ClassValue<>() {
2602                 @Override
2603                 protected Boolean computeValue(Class<?> type) {
2604                     return auditSubclass(type);
2605                 }
2606             };
2607     }
2608 
2609     /**
2610      * Verifies that this (possibly subclass) instance can be constructed
2611      * without violating security constraints: the subclass must not override
2612      * security-sensitive non-final methods, or else the
2613      * "enableContextClassLoaderOverride" RuntimePermission is checked.
2614      */
2615     private static boolean isCCLOverridden(Class<?> cl) {
2616         if (cl == Thread.class)
2617             return false;
2618 
2619         return Caches.subclassAudits.get(cl);
2620     }
2621 
2622     /**
2623      * Performs reflective checks on given subclass to verify that it doesn't
2624      * override security-sensitive non-final methods.  Returns true if the
2625      * subclass overrides any of the methods, false otherwise.
2626      */
2627     private static boolean auditSubclass(final Class<?> subcl) {
2628         @SuppressWarnings("removal")
2629         Boolean result = AccessController.doPrivileged(
2630             new PrivilegedAction<>() {
2631                 public Boolean run() {
2632                     for (Class<?> cl = subcl;
2633                          cl != Thread.class;
2634                          cl = cl.getSuperclass())
2635                     {
2636                         try {
2637                             cl.getDeclaredMethod("getContextClassLoader", new Class<?>[0]);
2638                             return Boolean.TRUE;
2639                         } catch (NoSuchMethodException ex) {
2640                         }
2641                         try {
2642                             Class<?>[] params = {ClassLoader.class};
2643                             cl.getDeclaredMethod("setContextClassLoader", params);
2644                             return Boolean.TRUE;
2645                         } catch (NoSuchMethodException ex) {
2646                         }
2647                     }
2648                     return Boolean.FALSE;
2649                 }
2650             }
2651         );
2652         return result.booleanValue();
2653     }
2654 
2655     /**
2656      * Return an array of all live threads.
2657      */
2658     static Thread[] getAllThreads() {
2659         return getThreads();
2660     }
2661 
2662     private static native StackTraceElement[][] dumpThreads(Thread[] threads);
2663     private static native Thread[] getThreads();
2664 
2665     /**
2666      * Returns the identifier of this Thread.  The thread ID is a positive
2667      * {@code long} number generated when this thread was created.
2668      * The thread ID is unique and remains unchanged during its lifetime.
2669      *
2670      * @return this thread's ID
2671      *
2672      * @deprecated This method is not final and may be overridden to return a
2673      * value that is not the thread ID. Use {@link #threadId()} instead.
2674      *
2675      * @since 1.5
2676      */
2677     @Deprecated(since="19")
2678     public long getId() {
2679         return threadId();
2680     }
2681 
2682     /**
2683      * Returns the identifier of this Thread.  The thread ID is a positive
2684      * {@code long} number generated when this thread was created.
2685      * The thread ID is unique and remains unchanged during its lifetime.
2686      *
2687      * @return this thread's ID
2688      * @since 19
2689      */
2690     public final long threadId() {
2691         return tid;
2692     }
2693 
2694     /**
2695      * A thread state.  A thread can be in one of the following states:
2696      * <ul>
2697      * <li>{@link #NEW}<br>
2698      *     A thread that has not yet started is in this state.
2699      *     </li>
2700      * <li>{@link #RUNNABLE}<br>
2701      *     A thread executing in the Java virtual machine is in this state.
2702      *     </li>
2703      * <li>{@link #BLOCKED}<br>
2704      *     A thread that is blocked waiting for a monitor lock
2705      *     is in this state.
2706      *     </li>
2707      * <li>{@link #WAITING}<br>
2708      *     A thread that is waiting indefinitely for another thread to
2709      *     perform a particular action is in this state.
2710      *     </li>
2711      * <li>{@link #TIMED_WAITING}<br>
2712      *     A thread that is waiting for another thread to perform an action
2713      *     for up to a specified waiting time is in this state.
2714      *     </li>
2715      * <li>{@link #TERMINATED}<br>
2716      *     A thread that has exited is in this state.
2717      *     </li>
2718      * </ul>
2719      *
2720      * <p>
2721      * A thread can be in only one state at a given point in time.
2722      * These states are virtual machine states which do not reflect
2723      * any operating system thread states.
2724      *
2725      * @since   1.5
2726      * @see #getState
2727      */
2728     public enum State {
2729         /**
2730          * Thread state for a thread which has not yet started.
2731          */
2732         NEW,
2733 
2734         /**
2735          * Thread state for a runnable thread.  A thread in the runnable
2736          * state is executing in the Java virtual machine but it may
2737          * be waiting for other resources from the operating system
2738          * such as processor.
2739          */
2740         RUNNABLE,
2741 
2742         /**
2743          * Thread state for a thread blocked waiting for a monitor lock.
2744          * A thread in the blocked state is waiting for a monitor lock
2745          * to enter a synchronized block/method or
2746          * reenter a synchronized block/method after calling
2747          * {@link Object#wait() Object.wait}.
2748          */
2749         BLOCKED,
2750 
2751         /**
2752          * Thread state for a waiting thread.
2753          * A thread is in the waiting state due to calling one of the
2754          * following methods:
2755          * <ul>
2756          *   <li>{@link Object#wait() Object.wait} with no timeout</li>
2757          *   <li>{@link #join() Thread.join} with no timeout</li>
2758          *   <li>{@link LockSupport#park() LockSupport.park}</li>
2759          * </ul>
2760          *
2761          * <p>A thread in the waiting state is waiting for another thread to
2762          * perform a particular action.
2763          *
2764          * For example, a thread that has called {@code Object.wait()}
2765          * on an object is waiting for another thread to call
2766          * {@code Object.notify()} or {@code Object.notifyAll()} on
2767          * that object. A thread that has called {@code Thread.join()}
2768          * is waiting for a specified thread to terminate.
2769          */
2770         WAITING,
2771 
2772         /**
2773          * Thread state for a waiting thread with a specified waiting time.
2774          * A thread is in the timed waiting state due to calling one of
2775          * the following methods with a specified positive waiting time:
2776          * <ul>
2777          *   <li>{@link #sleep Thread.sleep}</li>
2778          *   <li>{@link Object#wait(long) Object.wait} with timeout</li>
2779          *   <li>{@link #join(long) Thread.join} with timeout</li>
2780          *   <li>{@link LockSupport#parkNanos LockSupport.parkNanos}</li>
2781          *   <li>{@link LockSupport#parkUntil LockSupport.parkUntil}</li>
2782          * </ul>
2783          */
2784         TIMED_WAITING,
2785 
2786         /**
2787          * Thread state for a terminated thread.
2788          * The thread has completed execution.
2789          */
2790         TERMINATED;
2791     }
2792 
2793     /**
2794      * Returns the state of this thread.
2795      * This method is designed for use in monitoring of the system state,
2796      * not for synchronization control.
2797      *
2798      * @return this thread's state.
2799      * @since 1.5
2800      */
2801     public State getState() {
2802         return threadState();
2803     }
2804 
2805     /**
2806      * Returns the state of this thread.
2807      * This method can be used instead of getState as getState is not final and
2808      * so can be overridden to run arbitrary code.
2809      */
2810     State threadState() {
2811         return jdk.internal.misc.VM.toThreadState(holder.threadStatus);
2812     }
2813 
2814     /**
2815      * Returns true if the thread has terminated.
2816      */
2817     boolean isTerminated() {
2818         return threadState() == State.TERMINATED;
2819     }
2820 
2821     /**
2822      * Interface for handlers invoked when a {@code Thread} abruptly
2823      * terminates due to an uncaught exception.
2824      * <p>When a thread is about to terminate due to an uncaught exception
2825      * the Java Virtual Machine will query the thread for its
2826      * {@code UncaughtExceptionHandler} using
2827      * {@link #getUncaughtExceptionHandler} and will invoke the handler's
2828      * {@code uncaughtException} method, passing the thread and the
2829      * exception as arguments.
2830      * If a thread has not had its {@code UncaughtExceptionHandler}
2831      * explicitly set, then its {@code ThreadGroup} object acts as its
2832      * {@code UncaughtExceptionHandler}. If the {@code ThreadGroup} object
2833      * has no
2834      * special requirements for dealing with the exception, it can forward
2835      * the invocation to the {@linkplain #getDefaultUncaughtExceptionHandler
2836      * default uncaught exception handler}.
2837      *
2838      * @see #setDefaultUncaughtExceptionHandler
2839      * @see #setUncaughtExceptionHandler
2840      * @see ThreadGroup#uncaughtException
2841      * @since 1.5
2842      */
2843     @FunctionalInterface
2844     public interface UncaughtExceptionHandler {
2845         /**
2846          * Method invoked when the given thread terminates due to the
2847          * given uncaught exception.
2848          * <p>Any exception thrown by this method will be ignored by the
2849          * Java Virtual Machine.
2850          * @param t the thread
2851          * @param e the exception
2852          */
2853         void uncaughtException(Thread t, Throwable e);
2854     }
2855 
2856     // null unless explicitly set
2857     private volatile UncaughtExceptionHandler uncaughtExceptionHandler;
2858 
2859     // null unless explicitly set
2860     private static volatile UncaughtExceptionHandler defaultUncaughtExceptionHandler;
2861 
2862     /**
2863      * Set the default handler invoked when a thread abruptly terminates
2864      * due to an uncaught exception, and no other handler has been defined
2865      * for that thread.
2866      *
2867      * <p>Uncaught exception handling is controlled first by the thread, then
2868      * by the thread's {@link ThreadGroup} object and finally by the default
2869      * uncaught exception handler. If the thread does not have an explicit
2870      * uncaught exception handler set, and the thread's thread group
2871      * (including parent thread groups)  does not specialize its
2872      * {@code uncaughtException} method, then the default handler's
2873      * {@code uncaughtException} method will be invoked.
2874      * <p>By setting the default uncaught exception handler, an application
2875      * can change the way in which uncaught exceptions are handled (such as
2876      * logging to a specific device, or file) for those threads that would
2877      * already accept whatever &quot;default&quot; behavior the system
2878      * provided.
2879      *
2880      * <p>Note that the default uncaught exception handler should not usually
2881      * defer to the thread's {@code ThreadGroup} object, as that could cause
2882      * infinite recursion.
2883      *
2884      * @param ueh the object to use as the default uncaught exception handler.
2885      * If {@code null} then there is no default handler.
2886      *
2887      * @throws SecurityException if a security manager is present and it denies
2888      *         {@link RuntimePermission}{@code ("setDefaultUncaughtExceptionHandler")}
2889      *
2890      * @see #setUncaughtExceptionHandler
2891      * @see #getUncaughtExceptionHandler
2892      * @see ThreadGroup#uncaughtException
2893      * @since 1.5
2894      */
2895     public static void setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler ueh) {
2896         @SuppressWarnings("removal")
2897         SecurityManager sm = System.getSecurityManager();
2898         if (sm != null) {
2899             sm.checkPermission(
2900                 new RuntimePermission("setDefaultUncaughtExceptionHandler"));
2901         }
2902         defaultUncaughtExceptionHandler = ueh;
2903     }
2904 
2905     /**
2906      * Returns the default handler invoked when a thread abruptly terminates
2907      * due to an uncaught exception. If the returned value is {@code null},
2908      * there is no default.
2909      * @since 1.5
2910      * @see #setDefaultUncaughtExceptionHandler
2911      * @return the default uncaught exception handler for all threads
2912      */
2913     public static UncaughtExceptionHandler getDefaultUncaughtExceptionHandler(){
2914         return defaultUncaughtExceptionHandler;
2915     }
2916 
2917     /**
2918      * Returns the handler invoked when this thread abruptly terminates
2919      * due to an uncaught exception. If this thread has not had an
2920      * uncaught exception handler explicitly set then this thread's
2921      * {@code ThreadGroup} object is returned, unless this thread
2922      * has terminated, in which case {@code null} is returned.
2923      * @since 1.5
2924      * @return the uncaught exception handler for this thread
2925      */
2926     public UncaughtExceptionHandler getUncaughtExceptionHandler() {
2927         if (isTerminated()) {
2928             // uncaughtExceptionHandler may be set to null after thread terminates
2929             return null;
2930         } else {
2931             UncaughtExceptionHandler ueh = uncaughtExceptionHandler;
2932             return (ueh != null) ? ueh : getThreadGroup();
2933         }
2934     }
2935 
2936     /**
2937      * Set the handler invoked when this thread abruptly terminates
2938      * due to an uncaught exception.
2939      * <p>A thread can take full control of how it responds to uncaught
2940      * exceptions by having its uncaught exception handler explicitly set.
2941      * If no such handler is set then the thread's {@code ThreadGroup}
2942      * object acts as its handler.
2943      * @param ueh the object to use as this thread's uncaught exception
2944      * handler. If {@code null} then this thread has no explicit handler.
2945      * @throws  SecurityException  if the current thread is not allowed to
2946      *          modify this thread.
2947      * @see #setDefaultUncaughtExceptionHandler
2948      * @see ThreadGroup#uncaughtException
2949      * @since 1.5
2950      */
2951     public void setUncaughtExceptionHandler(UncaughtExceptionHandler ueh) {
2952         checkAccess();
2953         uncaughtExceptionHandler(ueh);
2954     }
2955 
2956     void uncaughtExceptionHandler(UncaughtExceptionHandler ueh) {
2957         uncaughtExceptionHandler = ueh;
2958     }
2959 
2960     /**
2961      * Dispatch an uncaught exception to the handler. This method is
2962      * called when a thread terminates with an exception.
2963      */
2964     void dispatchUncaughtException(Throwable e) {
2965         getUncaughtExceptionHandler().uncaughtException(this, e);
2966     }
2967 
2968     /**
2969      * Holder class for constants.
2970      */
2971     @SuppressWarnings("removal")
2972     private static class Constants {
2973         // Thread group for virtual threads.
2974         static final ThreadGroup VTHREAD_GROUP;
2975 
2976         // AccessControlContext that doesn't support any permissions.
2977         @SuppressWarnings("removal")
2978         static final AccessControlContext NO_PERMISSIONS_ACC;
2979 
2980         // Placeholder TCCL when thread locals not supported
2981         static final ClassLoader NOT_SUPPORTED_CLASSLOADER;
2982 
2983         static {
2984             var getThreadGroup  = new PrivilegedAction<ThreadGroup>() {
2985                 @Override
2986                 public ThreadGroup run() {
2987                     ThreadGroup parent = Thread.currentCarrierThread().getThreadGroup();
2988                     for (ThreadGroup p; (p = parent.getParent()) != null; )
2989                         parent = p;
2990                     return parent;
2991                 }
2992             };
2993             @SuppressWarnings("removal")
2994             ThreadGroup root = AccessController.doPrivileged(getThreadGroup);
2995             VTHREAD_GROUP = new ThreadGroup(root, "VirtualThreads", MAX_PRIORITY, false);
2996 
2997             NO_PERMISSIONS_ACC = new AccessControlContext(new ProtectionDomain[] {
2998                 new ProtectionDomain(null, null)
2999             });
3000 
3001             var createClassLoader = new PrivilegedAction<ClassLoader>() {
3002                 @Override
3003                 public ClassLoader run() {
3004                     return new ClassLoader(null) { };
3005                 }
3006             };
3007             @SuppressWarnings("removal")
3008             ClassLoader loader = AccessController.doPrivileged(createClassLoader);
3009             NOT_SUPPORTED_CLASSLOADER = loader;
3010         }
3011     }
3012 
3013     /**
3014      * Returns the special ThreadGroup for virtual threads.
3015      */
3016     static ThreadGroup virtualThreadGroup() {
3017         return Constants.VTHREAD_GROUP;
3018     }
3019 
3020     // The following three initially uninitialized fields are exclusively
3021     // managed by class java.util.concurrent.ThreadLocalRandom. These
3022     // fields are used to build the high-performance PRNGs in the
3023     // concurrent code.
3024 
3025     /** The current seed for a ThreadLocalRandom */
3026     long threadLocalRandomSeed;
3027 
3028     /** Probe hash value; nonzero if threadLocalRandomSeed initialized */
3029     int threadLocalRandomProbe;
3030 
3031     /** Secondary seed isolated from public ThreadLocalRandom sequence */
3032     int threadLocalRandomSecondarySeed;
3033 
3034     /** The thread container that this thread is in */
3035     private volatile ThreadContainer container;  // @Stable candidate?
3036     ThreadContainer threadContainer() {
3037         return container;
3038     }
3039     void setThreadContainer(ThreadContainer container) {
3040         // assert this.container == null;
3041         this.container = container;
3042     }
3043 
3044     /** The top of this stack of stackable scopes owned by this thread */
3045     private volatile StackableScope headStackableScopes;
3046     StackableScope headStackableScopes() {
3047         return headStackableScopes;
3048     }
3049     static void setHeadStackableScope(StackableScope scope) {
3050         currentThread().headStackableScopes = scope;
3051     }
3052 
3053     /* Some private helper methods */
3054     private native void setPriority0(int newPriority);
3055     private native void interrupt0();
3056     private static native void clearInterruptEvent();
3057     private native void setNativeName(String name);
3058 
3059     // The address of the next thread identifier, see ThreadIdentifiers.
3060     private static native long getNextThreadIdOffset();
3061 }