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