1 /*
2 * Copyright (c) 2018, 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 package java.lang;
26
27 import java.lang.reflect.Constructor;
28 import java.util.Locale;
29 import java.util.Objects;
30 import java.util.concurrent.CountDownLatch;
31 import java.util.concurrent.Executors;
32 import java.util.concurrent.ForkJoinPool;
33 import java.util.concurrent.ForkJoinTask;
34 import java.util.concurrent.Future;
35 import java.util.concurrent.RejectedExecutionException;
36 import java.util.concurrent.ScheduledExecutorService;
37 import java.util.concurrent.ScheduledThreadPoolExecutor;
38 import java.util.concurrent.TimeUnit;
39 import jdk.internal.event.VirtualThreadEndEvent;
40 import jdk.internal.event.VirtualThreadStartEvent;
41 import jdk.internal.event.VirtualThreadSubmitFailedEvent;
42 import jdk.internal.misc.CarrierThread;
43 import jdk.internal.misc.InnocuousThread;
44 import jdk.internal.misc.Unsafe;
45 import jdk.internal.vm.Continuation;
46 import jdk.internal.vm.ContinuationScope;
47 import jdk.internal.vm.StackableScope;
48 import jdk.internal.vm.ThreadContainer;
49 import jdk.internal.vm.ThreadContainers;
50 import jdk.internal.vm.annotation.ChangesCurrentThread;
51 import jdk.internal.vm.annotation.Hidden;
52 import jdk.internal.vm.annotation.IntrinsicCandidate;
53 import jdk.internal.vm.annotation.JvmtiHideEvents;
54 import jdk.internal.vm.annotation.JvmtiMountTransition;
55 import jdk.internal.vm.annotation.ReservedStackAccess;
56 import sun.nio.ch.Interruptible;
57 import static java.util.concurrent.TimeUnit.*;
58
59 /**
60 * A thread that is scheduled by the Java virtual machine rather than the operating system.
61 */
62 final class VirtualThread extends BaseVirtualThread {
63 private static final Unsafe U = Unsafe.getUnsafe();
64 private static final ContinuationScope VTHREAD_SCOPE = new ContinuationScope("VirtualThreads");
65
66 private static final ForkJoinPool BUILTIN_DEFAULT_SCHEDULER;
67 private static final VirtualThreadScheduler DEFAULT_SCHEDULER;
68 static {
69 // experimental
70 String propValue = System.getProperty("jdk.virtualThreadScheduler.implClass");
71 if (propValue != null) {
72 var builtinScheduler = createBuiltinDefaultScheduler(true);
73 VirtualThreadScheduler defaultScheduler = builtinScheduler.externalView();
74 for (String cn: propValue.split(",")) {
75 defaultScheduler = loadCustomScheduler(defaultScheduler, cn);
76 }
77 BUILTIN_DEFAULT_SCHEDULER = builtinScheduler;
78 DEFAULT_SCHEDULER = defaultScheduler;
79 } else {
80 var builtinScheduler = createBuiltinDefaultScheduler(false);
81 BUILTIN_DEFAULT_SCHEDULER = builtinScheduler;
82 DEFAULT_SCHEDULER = builtinScheduler;
83 }
84 }
85
86 private static final long STATE = U.objectFieldOffset(VirtualThread.class, "state");
87 private static final long PARK_PERMIT = U.objectFieldOffset(VirtualThread.class, "parkPermit");
88 private static final long CARRIER_THREAD = U.objectFieldOffset(VirtualThread.class, "carrierThread");
89 private static final long TERMINATION = U.objectFieldOffset(VirtualThread.class, "termination");
90 private static final long ON_WAITING_LIST = U.objectFieldOffset(VirtualThread.class, "onWaitingList");
91
92 // scheduler and continuation
93 private final VirtualThreadScheduler scheduler;
94 private final Continuation cont;
95 private final Runnable runContinuation;
96
97 // virtual thread state, accessed by VM
98 private volatile int state;
99
100 /*
101 * Virtual thread state transitions:
102 *
103 * NEW -> STARTED // Thread.start, schedule to run
104 * STARTED -> TERMINATED // failed to start
105 * STARTED -> RUNNING // first run
106 * RUNNING -> TERMINATED // done
107 *
108 * RUNNING -> PARKING // Thread parking with LockSupport.park
109 * PARKING -> PARKED // cont.yield successful, parked indefinitely
110 * PARKING -> PINNED // cont.yield failed, parked indefinitely on carrier
111 * PARKED -> UNPARKED // unparked, may be scheduled to continue
112 * PINNED -> RUNNING // unparked, continue execution on same carrier
113 * UNPARKED -> RUNNING // continue execution after park
114 *
115 * RUNNING -> TIMED_PARKING // Thread parking with LockSupport.parkNanos
116 * TIMED_PARKING -> TIMED_PARKED // cont.yield successful, timed-parked
117 * TIMED_PARKING -> TIMED_PINNED // cont.yield failed, timed-parked on carrier
118 * TIMED_PARKED -> UNPARKED // unparked, may be scheduled to continue
119 * TIMED_PINNED -> RUNNING // unparked, continue execution on same carrier
120 *
121 * RUNNING -> BLOCKING // blocking on monitor enter
122 * BLOCKING -> BLOCKED // blocked on monitor enter
123 * BLOCKED -> UNBLOCKED // unblocked, may be scheduled to continue
124 * UNBLOCKED -> RUNNING // continue execution after blocked on monitor enter
125 *
126 * RUNNING -> WAITING // transitional state during wait on monitor
127 * WAITING -> WAIT // waiting on monitor
128 * WAIT -> BLOCKED // notified, waiting to be unblocked by monitor owner
129 * WAIT -> UNBLOCKED // timed-out/interrupted
130 *
131 * RUNNING -> TIMED_WAITING // transition state during timed-waiting on monitor
132 * TIMED_WAITING -> TIMED_WAIT // timed-waiting on monitor
133 * TIMED_WAIT -> BLOCKED // notified, waiting to be unblocked by monitor owner
134 * TIMED_WAIT -> UNBLOCKED // timed-out/interrupted
135 *
136 * RUNNING -> YIELDING // Thread.yield
137 * YIELDING -> YIELDED // cont.yield successful, may be scheduled to continue
138 * YIELDING -> RUNNING // cont.yield failed
139 * YIELDED -> RUNNING // continue execution after Thread.yield
140 */
141 private static final int NEW = 0;
142 private static final int STARTED = 1;
143 private static final int RUNNING = 2; // runnable-mounted
144
145 // untimed and timed parking
146 private static final int PARKING = 3;
147 private static final int PARKED = 4; // unmounted
148 private static final int PINNED = 5; // mounted
149 private static final int TIMED_PARKING = 6;
150 private static final int TIMED_PARKED = 7; // unmounted
151 private static final int TIMED_PINNED = 8; // mounted
152 private static final int UNPARKED = 9; // unmounted but runnable
153
154 // Thread.yield
155 private static final int YIELDING = 10;
156 private static final int YIELDED = 11; // unmounted but runnable
157
158 // monitor enter
159 private static final int BLOCKING = 12;
160 private static final int BLOCKED = 13; // unmounted
161 private static final int UNBLOCKED = 14; // unmounted but runnable
162
163 // monitor wait/timed-wait
164 private static final int WAITING = 15;
165 private static final int WAIT = 16; // waiting in Object.wait
166 private static final int TIMED_WAITING = 17;
167 private static final int TIMED_WAIT = 18; // waiting in timed-Object.wait
168
169 private static final int TERMINATED = 99; // final state
170
171 // can be suspended from scheduling when unmounted
172 private static final int SUSPENDED = 1 << 8;
173
174 // parking permit made available by LockSupport.unpark
175 private volatile boolean parkPermit;
176
177 // blocking permit made available by unblocker thread when another thread exits monitor
178 private volatile boolean blockPermit;
179
180 // true when on the list of virtual threads waiting to be unblocked
181 private volatile boolean onWaitingList;
182
183 // next virtual thread on the list of virtual threads waiting to be unblocked
184 private volatile VirtualThread next;
185
186 // notified by Object.notify/notifyAll while waiting in Object.wait
187 private volatile boolean notified;
188
189 // true when waiting in Object.wait, false for VM internal uninterruptible Object.wait
190 private volatile boolean interruptibleWait;
191
192 // timed-wait support
193 private byte timedWaitSeqNo;
194
195 // timeout for timed-park and timed-wait, only accessed on current/carrier thread
196 private long timeout;
197
198 // timer task for timed-park and timed-wait, only accessed on current/carrier thread
199 private Future<?> timeoutTask;
200
201 // carrier thread when mounted, accessed by VM
202 private volatile Thread carrierThread;
203
204 // termination object when joining, created lazily if needed
205 private volatile CountDownLatch termination;
206
207 /**
208 * Returns the default scheduler.
209 */
210 static VirtualThreadScheduler defaultScheduler() {
211 return DEFAULT_SCHEDULER;
212 }
213
214 /**
215 * Returns true if using a custom default scheduler.
216 */
217 static boolean isCustomDefaultScheduler() {
218 return DEFAULT_SCHEDULER != BUILTIN_DEFAULT_SCHEDULER;
219 }
220
221 /**
222 * Returns the continuation scope used for virtual threads.
223 */
224 static ContinuationScope continuationScope() {
225 return VTHREAD_SCOPE;
226 }
227
228 /**
229 * Return the scheduler for this thread.
230 * @param revealBuiltin true to reveal the built-in default scheduler, false to hide
231 */
232 VirtualThreadScheduler scheduler(boolean revealBuiltin) {
233 if (scheduler instanceof BuiltinDefaultScheduler builtin && !revealBuiltin) {
234 return builtin.externalView();
235 } else {
236 return scheduler;
237 }
238 }
239
240 /**
241 * Creates a new {@code VirtualThread} to run the given task with the given scheduler.
242 *
243 * @param scheduler the scheduler or null for default scheduler
244 * @param name thread name
245 * @param characteristics characteristics
246 * @param task the task to execute
247 */
248 VirtualThread(VirtualThreadScheduler scheduler,
249 String name,
250 int characteristics,
251 Runnable task) {
252 super(name, characteristics, /*bound*/ false);
253 Objects.requireNonNull(task);
254
255 // use default scheduler if not provided
256 if (scheduler == null) {
257 scheduler = DEFAULT_SCHEDULER;
258 }
259
260 this.scheduler = scheduler;
261 this.cont = new VThreadContinuation(this, task);
262 this.runContinuation = this::runContinuation;
263 }
264
265 /**
266 * The continuation that a virtual thread executes.
267 */
268 private static class VThreadContinuation extends Continuation {
269 VThreadContinuation(VirtualThread vthread, Runnable task) {
270 super(VTHREAD_SCOPE, wrap(vthread, task));
271 }
272 @Override
273 protected void onPinned(Continuation.Pinned reason) {
274 }
275 private static Runnable wrap(VirtualThread vthread, Runnable task) {
276 return new Runnable() {
277 @Hidden
278 @JvmtiHideEvents
279 public void run() {
280 vthread.notifyJvmtiStart(); // notify JVMTI
281 try {
282 vthread.run(task);
283 } finally {
284 vthread.notifyJvmtiEnd(); // notify JVMTI
285 }
286 }
287 };
288 }
289 }
290
291 /**
292 * Runs or continues execution on the current thread. The virtual thread is mounted
293 * on the current thread before the task runs or continues. It unmounts when the
294 * task completes or yields.
295 */
296 @ChangesCurrentThread // allow mount/unmount to be inlined
297 private void runContinuation() {
298 // the carrier must be a platform thread
299 if (Thread.currentThread().isVirtual()) {
300 throw new WrongThreadException();
301 }
302
303 // set state to RUNNING
304 int initialState = state();
305 if (initialState == STARTED || initialState == UNPARKED
306 || initialState == UNBLOCKED || initialState == YIELDED) {
307 // newly started or continue after parking/blocking/Thread.yield
308 if (!compareAndSetState(initialState, RUNNING)) {
309 return;
310 }
311 // consume permit when continuing after parking or blocking. If continue
312 // after a timed-park or timed-wait then the timeout task is cancelled.
313 if (initialState == UNPARKED) {
314 cancelTimeoutTask();
315 setParkPermit(false);
316 } else if (initialState == UNBLOCKED) {
317 cancelTimeoutTask();
318 blockPermit = false;
319 }
320 } else {
321 // not runnable
322 return;
323 }
324
325 mount();
326 try {
327 cont.run();
328 } finally {
329 unmount();
330 if (cont.isDone()) {
331 afterDone();
332 } else {
333 afterYield();
334 }
335 }
336 }
337
338 /**
339 * Cancel timeout task when continuing after timed-park or timed-wait.
340 * The timeout task may be executing, or may have already completed.
341 */
342 private void cancelTimeoutTask() {
343 if (timeoutTask != null) {
344 timeoutTask.cancel(false);
345 timeoutTask = null;
346 }
347 }
348
349 /**
350 * Submits the runContinuation task to the scheduler. For the built-in default
351 * scheduler, the task will be pushed to the local queue if possible, otherwise it
352 * will be pushed to an external submission queue.
353 * @param retryOnOOME true to retry indefinitely if OutOfMemoryError is thrown
354 * @throws RejectedExecutionException
355 */
356 private void submitRunContinuation(boolean retryOnOOME) {
357 boolean done = false;
358 while (!done) {
359 try {
360 // Pin the continuation to prevent the virtual thread from unmounting
361 // when submitting a task. For the default scheduler this ensures that
362 // the carrier doesn't change when pushing a task. For other schedulers
363 // it avoids deadlock that could arise due to carriers and virtual
364 // threads contending for a lock.
365 if (currentThread().isVirtual()) {
366 Continuation.pin();
367 try {
368 scheduler.onContinue(this, runContinuation);
369 } finally {
370 Continuation.unpin();
371 }
372 } else {
373 scheduler.onContinue(this, runContinuation);
374 }
375 done = true;
376 } catch (RejectedExecutionException ree) {
377 submitFailed(ree);
378 throw ree;
379 } catch (OutOfMemoryError e) {
380 if (retryOnOOME) {
381 U.park(false, 100_000_000); // 100ms
382 } else {
383 throw e;
384 }
385 }
386 }
387 }
388
389 /**
390 * Submits the runContinuation task to the scheduler. For the default scheduler,
391 * and calling it on a worker thread, the task will be pushed to the local queue,
392 * otherwise it will be pushed to an external submission queue.
393 * If OutOfMemoryError is thrown then the submit will be retried until it succeeds.
394 * @throws RejectedExecutionException
395 */
396 private void submitRunContinuation() {
397 submitRunContinuation(true);
398 }
399
400 /**
401 * Invoked from a carrier thread to lazy submit the runContinuation task to the
402 * carrier's local queue if the queue is empty. If not empty, or invoked by a thread
403 * for a custom scheduler, then it just submits the task to the scheduler.
404 * If OutOfMemoryError is thrown then the submit will be retried until it succeeds.
405 * @throws RejectedExecutionException
406 * @see ForkJoinPool#lazySubmit(ForkJoinTask)
407 */
408 private void lazySubmitRunContinuation() {
409 assert !currentThread().isVirtual();
410 if (currentThread() instanceof CarrierThread ct && ct.getQueuedTaskCount() == 0) {
411 try {
412 ct.getPool().lazySubmit(ForkJoinTask.adapt(runContinuation));
413 } catch (RejectedExecutionException ree) {
414 submitFailed(ree);
415 throw ree;
416 } catch (OutOfMemoryError e) {
417 submitRunContinuation();
418 }
419 } else {
420 submitRunContinuation();
421 }
422 }
423
424 /**
425 * Invoked from a carrier thread to externally submit the runContinuation task to the
426 * scheduler. If invoked by a thread for a custom scheduler, then it just submits the
427 * task to the scheduler.
428 * If OutOfMemoryError is thrown then the submit will be retried until it succeeds.
429 * @throws RejectedExecutionException
430 * @see ForkJoinPool#externalSubmit(ForkJoinTask)
431 */
432 private void externalSubmitRunContinuation() {
433 assert !currentThread().isVirtual();
434 if (currentThread() instanceof CarrierThread ct) {
435 try {
436 ct.getPool().externalSubmit(ForkJoinTask.adapt(runContinuation));
437 } catch (RejectedExecutionException ree) {
438 submitFailed(ree);
439 throw ree;
440 } catch (OutOfMemoryError e) {
441 submitRunContinuation();
442 }
443 } else {
444 submitRunContinuation();
445 }
446 }
447
448 /**
449 * Invoked from Thread.start to externally submit the runContinuation task to the
450 * scheduler. If this virtual thread is scheduled by the built-in default scheduler,
451 * and this method is called from a virtual thread scheduled by the built-in default
452 * scheduler, then it uses externalSubmit to ensure that the task is pushed to an
453 * external submission queue rather than the local queue.
454 * @throws RejectedExecutionException
455 * @throws OutOfMemoryError
456 * @see ForkJoinPool#externalSubmit(ForkJoinTask)
457 */
458 private void externalSubmitRunContinuationOrThrow() {
459 try {
460 if (currentThread().isVirtual()) {
461 // Pin the continuation to prevent the virtual thread from unmounting
462 // when submitting a task. This avoids deadlock that could arise due to
463 // carriers and virtual threads contending for a lock.
464 Continuation.pin();
465 try {
466 if (scheduler == BUILTIN_DEFAULT_SCHEDULER
467 && currentCarrierThread() instanceof CarrierThread ct) {
468 ct.getPool().externalSubmit(ForkJoinTask.adapt(runContinuation));
469 } else {
470 scheduler.onStart(this, runContinuation);
471 }
472 } finally {
473 Continuation.unpin();
474 }
475 } else {
476 scheduler.onStart(this, runContinuation);
477 }
478 } catch (RejectedExecutionException ree) {
479 submitFailed(ree);
480 throw ree;
481 }
482 }
483
484 /**
485 * If enabled, emits a JFR VirtualThreadSubmitFailedEvent.
486 */
487 private void submitFailed(RejectedExecutionException ree) {
488 var event = new VirtualThreadSubmitFailedEvent();
489 if (event.isEnabled()) {
490 event.javaThreadId = threadId();
491 event.exceptionMessage = ree.getMessage();
492 event.commit();
493 }
494 }
495
496 /**
497 * Runs a task in the context of this virtual thread.
498 */
499 private void run(Runnable task) {
500 assert Thread.currentThread() == this && state == RUNNING;
501
502 // emit JFR event if enabled
503 if (VirtualThreadStartEvent.isTurnedOn()) {
504 var event = new VirtualThreadStartEvent();
505 event.javaThreadId = threadId();
506 event.commit();
507 }
508
509 Object bindings = Thread.scopedValueBindings();
510 try {
511 runWith(bindings, task);
512 } catch (Throwable exc) {
513 dispatchUncaughtException(exc);
514 } finally {
515 // pop any remaining scopes from the stack, this may block
516 StackableScope.popAll();
517
518 // emit JFR event if enabled
519 if (VirtualThreadEndEvent.isTurnedOn()) {
520 var event = new VirtualThreadEndEvent();
521 event.javaThreadId = threadId();
522 event.commit();
523 }
524 }
525 }
526
527 /**
528 * Mounts this virtual thread onto the current platform thread. On
529 * return, the current thread is the virtual thread.
530 */
531 @ChangesCurrentThread
532 @ReservedStackAccess
533 private void mount() {
534 // notify JVMTI before mount
535 notifyJvmtiMount(/*hide*/true);
536
537 // sets the carrier thread
538 Thread carrier = Thread.currentCarrierThread();
539 setCarrierThread(carrier);
540
541 // sync up carrier thread interrupt status if needed
542 if (interrupted) {
543 carrier.setInterrupt();
544 } else if (carrier.isInterrupted()) {
545 synchronized (interruptLock) {
546 // need to recheck interrupt status
547 if (!interrupted) {
548 carrier.clearInterrupt();
549 }
550 }
551 }
552
553 // set Thread.currentThread() to return this virtual thread
554 carrier.setCurrentThread(this);
555 }
556
557 /**
558 * Unmounts this virtual thread from the carrier. On return, the
559 * current thread is the current platform thread.
560 */
561 @ChangesCurrentThread
562 @ReservedStackAccess
563 private void unmount() {
564 assert !Thread.holdsLock(interruptLock);
565
566 // set Thread.currentThread() to return the platform thread
567 Thread carrier = this.carrierThread;
568 carrier.setCurrentThread(carrier);
569
570 // break connection to carrier thread, synchronized with interrupt
571 synchronized (interruptLock) {
572 setCarrierThread(null);
573 }
574 carrier.clearInterrupt();
575
576 // notify JVMTI after unmount
577 notifyJvmtiUnmount(/*hide*/false);
578 }
579
580 /**
581 * Invokes Continuation.yield, notifying JVMTI (if enabled) to hide frames until
582 * the continuation continues.
583 */
584 @Hidden
585 private boolean yieldContinuation() {
586 notifyJvmtiUnmount(/*hide*/true);
587 try {
588 return Continuation.yield(VTHREAD_SCOPE);
589 } finally {
590 notifyJvmtiMount(/*hide*/false);
591 }
592 }
593
594 /**
595 * Invoked in the context of the carrier thread after the Continuation yields when
596 * parking, blocking on monitor enter, Object.wait, or Thread.yield.
597 */
598 private void afterYield() {
599 assert carrierThread == null;
600
601 // re-adjust parallelism if the virtual thread yielded when compensating
602 if (currentThread() instanceof CarrierThread ct) {
603 ct.endBlocking();
604 }
605
606 int s = state();
607
608 // LockSupport.park/parkNanos
609 if (s == PARKING || s == TIMED_PARKING) {
610 int newState;
611 if (s == PARKING) {
612 setState(newState = PARKED);
613 } else {
614 // schedule unpark
615 long timeout = this.timeout;
616 assert timeout > 0;
617 timeoutTask = schedule(this::parkTimeoutExpired, timeout, NANOSECONDS);
618 setState(newState = TIMED_PARKED);
619 }
620
621 // may have been unparked while parking
622 if (parkPermit && compareAndSetState(newState, UNPARKED)) {
623 // lazy submit if local queue is empty
624 lazySubmitRunContinuation();
625 }
626 return;
627 }
628
629 // Thread.yield
630 if (s == YIELDING) {
631 setState(YIELDED);
632
633 // external submit if there are no tasks in the local task queue
634 if (currentThread() instanceof CarrierThread ct && ct.getQueuedTaskCount() == 0) {
635 externalSubmitRunContinuation();
636 } else {
637 submitRunContinuation();
638 }
639 return;
640 }
641
642 // blocking on monitorenter
643 if (s == BLOCKING) {
644 setState(BLOCKED);
645
646 // may have been unblocked while blocking
647 if (blockPermit && compareAndSetState(BLOCKED, UNBLOCKED)) {
648 // lazy submit if local queue is empty
649 lazySubmitRunContinuation();
650 }
651 return;
652 }
653
654 // Object.wait
655 if (s == WAITING || s == TIMED_WAITING) {
656 int newState;
657 boolean interruptible = interruptibleWait;
658 if (s == WAITING) {
659 setState(newState = WAIT);
660 } else {
661 // For timed-wait, a timeout task is scheduled to execute. The timeout
662 // task will change the thread state to UNBLOCKED and submit the thread
663 // to the scheduler. A sequence number is used to ensure that the timeout
664 // task only unblocks the thread for this timed-wait. We synchronize with
665 // the timeout task to coordinate access to the sequence number and to
666 // ensure the timeout task doesn't execute until the thread has got to
667 // the TIMED_WAIT state.
668 long timeout = this.timeout;
669 assert timeout > 0;
670 synchronized (timedWaitLock()) {
671 byte seqNo = ++timedWaitSeqNo;
672 timeoutTask = schedule(() -> waitTimeoutExpired(seqNo), timeout, MILLISECONDS);
673 setState(newState = TIMED_WAIT);
674 }
675 }
676
677 // may have been notified while in transition to wait state
678 if (notified && compareAndSetState(newState, BLOCKED)) {
679 // may have even been unblocked already
680 if (blockPermit && compareAndSetState(BLOCKED, UNBLOCKED)) {
681 submitRunContinuation();
682 }
683 return;
684 }
685
686 // may have been interrupted while in transition to wait state
687 if (interruptible && interrupted && compareAndSetState(newState, UNBLOCKED)) {
688 submitRunContinuation();
689 return;
690 }
691 return;
692 }
693
694 assert false;
695 }
696
697 /**
698 * Invoked after the continuation completes.
699 */
700 private void afterDone() {
701 afterDone(true);
702 }
703
704 /**
705 * Invoked after the continuation completes (or start failed). Sets the thread
706 * state to TERMINATED and notifies anyone waiting for the thread to terminate.
707 *
708 * @param notifyContainer true if its container should be notified
709 */
710 private void afterDone(boolean notifyContainer) {
711 assert carrierThread == null;
712 setState(TERMINATED);
713
714 // notify anyone waiting for this virtual thread to terminate
715 CountDownLatch termination = this.termination;
716 if (termination != null) {
717 assert termination.getCount() == 1;
718 termination.countDown();
719 }
720
721 // notify container
722 if (notifyContainer) {
723 threadContainer().remove(this);
724 }
725
726 // clear references to thread locals
727 clearReferences();
728 }
729
730 /**
731 * Schedules this {@code VirtualThread} to execute.
732 *
733 * @throws IllegalStateException if the container is shutdown or closed
734 * @throws IllegalThreadStateException if the thread has already been started
735 * @throws RejectedExecutionException if the scheduler cannot accept a task
736 */
737 @Override
738 void start(ThreadContainer container) {
739 if (!compareAndSetState(NEW, STARTED)) {
740 throw new IllegalThreadStateException("Already started");
741 }
742
743 // bind thread to container
744 assert threadContainer() == null;
745 setThreadContainer(container);
746
747 // start thread
748 boolean addedToContainer = false;
749 boolean started = false;
750 try {
751 container.add(this); // may throw
752 addedToContainer = true;
753
754 // scoped values may be inherited
755 inheritScopedValueBindings(container);
756
757 // submit task to run thread, using externalSubmit if possible
758 externalSubmitRunContinuationOrThrow();
759 started = true;
760 } finally {
761 if (!started) {
762 afterDone(addedToContainer);
763 }
764 }
765 }
766
767 @Override
768 public void start() {
769 start(ThreadContainers.root());
770 }
771
772 @Override
773 public void run() {
774 // do nothing
775 }
776
777 /**
778 * Parks until unparked or interrupted. If already unparked then the parking
779 * permit is consumed and this method completes immediately (meaning it doesn't
780 * yield). It also completes immediately if the interrupt status is set.
781 */
782 @Override
783 void park() {
784 assert Thread.currentThread() == this;
785
786 // complete immediately if parking permit available or interrupted
787 if (getAndSetParkPermit(false) || interrupted)
788 return;
789
790 // park the thread
791 boolean yielded = false;
792 setState(PARKING);
793 try {
794 yielded = yieldContinuation();
795 } catch (OutOfMemoryError e) {
796 // park on carrier
797 } finally {
798 assert (Thread.currentThread() == this) && (yielded == (state() == RUNNING));
799 if (!yielded) {
800 assert state() == PARKING;
801 setState(RUNNING);
802 }
803 }
804
805 // park on the carrier thread when pinned
806 if (!yielded) {
807 parkOnCarrierThread(false, 0);
808 }
809 }
810
811 /**
812 * Parks up to the given waiting time or until unparked or interrupted.
813 * If already unparked then the parking permit is consumed and this method
814 * completes immediately (meaning it doesn't yield). It also completes immediately
815 * if the interrupt status is set or the waiting time is {@code <= 0}.
816 *
817 * @param nanos the maximum number of nanoseconds to wait.
818 */
819 @Override
820 void parkNanos(long nanos) {
821 assert Thread.currentThread() == this;
822
823 // complete immediately if parking permit available or interrupted
824 if (getAndSetParkPermit(false) || interrupted)
825 return;
826
827 // park the thread for the waiting time
828 if (nanos > 0) {
829 long startTime = System.nanoTime();
830
831 // park the thread, afterYield will schedule the thread to unpark
832 boolean yielded = false;
833 timeout = nanos;
834 setState(TIMED_PARKING);
835 try {
836 yielded = yieldContinuation();
837 } catch (OutOfMemoryError e) {
838 // park on carrier
839 } finally {
840 assert (Thread.currentThread() == this) && (yielded == (state() == RUNNING));
841 if (!yielded) {
842 assert state() == TIMED_PARKING;
843 setState(RUNNING);
844 }
845 }
846
847 // park on carrier thread for remaining time when pinned (or OOME)
848 if (!yielded) {
849 long remainingNanos = nanos - (System.nanoTime() - startTime);
850 parkOnCarrierThread(true, remainingNanos);
851 }
852 }
853 }
854
855 /**
856 * Parks the current carrier thread up to the given waiting time or until
857 * unparked or interrupted. If the virtual thread is interrupted then the
858 * interrupt status will be propagated to the carrier thread.
859 * @param timed true for a timed park, false for untimed
860 * @param nanos the waiting time in nanoseconds
861 */
862 private void parkOnCarrierThread(boolean timed, long nanos) {
863 assert state() == RUNNING;
864
865 setState(timed ? TIMED_PINNED : PINNED);
866 try {
867 if (!parkPermit) {
868 if (!timed) {
869 U.park(false, 0);
870 } else if (nanos > 0) {
871 U.park(false, nanos);
872 }
873 }
874 } finally {
875 setState(RUNNING);
876 }
877
878 // consume parking permit
879 setParkPermit(false);
880
881 // JFR jdk.VirtualThreadPinned event
882 postPinnedEvent("LockSupport.park");
883 }
884
885 /**
886 * Call into VM when pinned to record a JFR jdk.VirtualThreadPinned event.
887 * Recording the event in the VM avoids having JFR event recorded in Java
888 * with the same name, but different ID, to events recorded by the VM.
889 */
890 @Hidden
891 private static native void postPinnedEvent(String op);
892
893 /**
894 * Re-enables this virtual thread for scheduling. If this virtual thread is parked
895 * then its task is scheduled to continue, otherwise its next call to {@code park} or
896 * {@linkplain #parkNanos(long) parkNanos} is guaranteed not to block.
897 * @throws RejectedExecutionException if the scheduler cannot accept a task
898 */
899 @Override
900 void unpark() {
901 if (!getAndSetParkPermit(true) && currentThread() != this) {
902 int s = state();
903
904 // unparked while parked
905 if ((s == PARKED || s == TIMED_PARKED) && compareAndSetState(s, UNPARKED)) {
906 submitRunContinuation();
907 return;
908 }
909
910 // unparked while parked when pinned
911 if (s == PINNED || s == TIMED_PINNED) {
912 // unpark carrier thread when pinned
913 disableSuspendAndPreempt();
914 try {
915 synchronized (carrierThreadAccessLock()) {
916 Thread carrier = carrierThread;
917 if (carrier != null && ((s = state()) == PINNED || s == TIMED_PINNED)) {
918 U.unpark(carrier);
919 }
920 }
921 } finally {
922 enableSuspendAndPreempt();
923 }
924 return;
925 }
926 }
927 }
928
929 /**
930 * Invoked by unblocker thread to unblock this virtual thread.
931 */
932 private void unblock() {
933 assert !Thread.currentThread().isVirtual();
934 blockPermit = true;
935 if (state() == BLOCKED && compareAndSetState(BLOCKED, UNBLOCKED)) {
936 submitRunContinuation();
937 }
938 }
939
940 /**
941 * Invoked by FJP worker thread or STPE thread when park timeout expires.
942 */
943 private void parkTimeoutExpired() {
944 assert !VirtualThread.currentThread().isVirtual();
945 if (!getAndSetParkPermit(true)
946 && (state() == TIMED_PARKED)
947 && compareAndSetState(TIMED_PARKED, UNPARKED)) {
948 lazySubmitRunContinuation();
949 }
950 }
951
952 /**
953 * Invoked by FJP worker thread or STPE thread when wait timeout expires.
954 * If the virtual thread is in timed-wait then this method will unblock the thread
955 * and submit its task so that it continues and attempts to reenter the monitor.
956 * This method does nothing if the thread has been woken by notify or interrupt.
957 */
958 private void waitTimeoutExpired(byte seqNo) {
959 assert !Thread.currentThread().isVirtual();
960 for (;;) {
961 boolean unblocked = false;
962 synchronized (timedWaitLock()) {
963 if (seqNo != timedWaitSeqNo) {
964 // this timeout task is for a past timed-wait
965 return;
966 }
967 int s = state();
968 if (s == TIMED_WAIT) {
969 unblocked = compareAndSetState(TIMED_WAIT, UNBLOCKED);
970 } else if (s != (TIMED_WAIT | SUSPENDED)) {
971 // notified or interrupted, no longer waiting
972 return;
973 }
974 }
975 if (unblocked) {
976 lazySubmitRunContinuation();
977 return;
978 }
979 // need to retry when thread is suspended in time-wait
980 Thread.yield();
981 }
982 }
983
984 /**
985 * Attempts to yield the current virtual thread (Thread.yield).
986 */
987 void tryYield() {
988 assert Thread.currentThread() == this;
989 setState(YIELDING);
990 boolean yielded = false;
991 try {
992 yielded = yieldContinuation(); // may throw
993 } finally {
994 assert (Thread.currentThread() == this) && (yielded == (state() == RUNNING));
995 if (!yielded) {
996 assert state() == YIELDING;
997 setState(RUNNING);
998 }
999 }
1000 }
1001
1002 /**
1003 * Sleep the current thread for the given sleep time (in nanoseconds). If
1004 * nanos is 0 then the thread will attempt to yield.
1005 *
1006 * @implNote This implementation parks the thread for the given sleeping time
1007 * and will therefore be observed in PARKED state during the sleep. Parking
1008 * will consume the parking permit so this method makes available the parking
1009 * permit after the sleep. This may be observed as a spurious, but benign,
1010 * wakeup when the thread subsequently attempts to park.
1011 *
1012 * @param nanos the maximum number of nanoseconds to sleep
1013 * @throws InterruptedException if interrupted while sleeping
1014 */
1015 void sleepNanos(long nanos) throws InterruptedException {
1016 assert Thread.currentThread() == this && nanos >= 0;
1017 if (getAndClearInterrupt())
1018 throw new InterruptedException();
1019 if (nanos == 0) {
1020 tryYield();
1021 } else {
1022 // park for the sleep time
1023 try {
1024 long remainingNanos = nanos;
1025 long startNanos = System.nanoTime();
1026 while (remainingNanos > 0) {
1027 parkNanos(remainingNanos);
1028 if (getAndClearInterrupt()) {
1029 throw new InterruptedException();
1030 }
1031 remainingNanos = nanos - (System.nanoTime() - startNanos);
1032 }
1033 } finally {
1034 // may have been unparked while sleeping
1035 setParkPermit(true);
1036 }
1037 }
1038 }
1039
1040 /**
1041 * Waits up to {@code nanos} nanoseconds for this virtual thread to terminate.
1042 * A timeout of {@code 0} means to wait forever.
1043 *
1044 * @throws InterruptedException if interrupted while waiting
1045 * @return true if the thread has terminated
1046 */
1047 boolean joinNanos(long nanos) throws InterruptedException {
1048 if (state() == TERMINATED)
1049 return true;
1050
1051 // ensure termination object exists, then re-check state
1052 CountDownLatch termination = getTermination();
1053 if (state() == TERMINATED)
1054 return true;
1055
1056 // wait for virtual thread to terminate
1057 if (nanos == 0) {
1058 termination.await();
1059 } else {
1060 boolean terminated = termination.await(nanos, NANOSECONDS);
1061 if (!terminated) {
1062 // waiting time elapsed
1063 return false;
1064 }
1065 }
1066 assert state() == TERMINATED;
1067 return true;
1068 }
1069
1070 @Override
1071 void blockedOn(Interruptible b) {
1072 disableSuspendAndPreempt();
1073 try {
1074 super.blockedOn(b);
1075 } finally {
1076 enableSuspendAndPreempt();
1077 }
1078 }
1079
1080 @Override
1081 public void interrupt() {
1082 if (Thread.currentThread() != this) {
1083 // if current thread is a virtual thread then prevent it from being
1084 // suspended or unmounted when entering or holding interruptLock
1085 Interruptible blocker;
1086 disableSuspendAndPreempt();
1087 try {
1088 synchronized (interruptLock) {
1089 interrupted = true;
1090 blocker = nioBlocker();
1091 if (blocker != null) {
1092 blocker.interrupt(this);
1093 }
1094
1095 // interrupt carrier thread if mounted
1096 Thread carrier = carrierThread;
1097 if (carrier != null) carrier.setInterrupt();
1098 }
1099 } finally {
1100 enableSuspendAndPreempt();
1101 }
1102
1103 // notify blocker after releasing interruptLock
1104 if (blocker != null) {
1105 blocker.postInterrupt();
1106 }
1107
1108 // make available parking permit, unpark thread if parked
1109 unpark();
1110
1111 // if thread is waiting in Object.wait then schedule to try to reenter
1112 int s = state();
1113 if ((s == WAIT || s == TIMED_WAIT) && compareAndSetState(s, UNBLOCKED)) {
1114 submitRunContinuation();
1115 }
1116
1117 } else {
1118 interrupted = true;
1119 carrierThread.setInterrupt();
1120 setParkPermit(true);
1121 }
1122 }
1123
1124 @Override
1125 public boolean isInterrupted() {
1126 return interrupted;
1127 }
1128
1129 @Override
1130 boolean getAndClearInterrupt() {
1131 assert Thread.currentThread() == this;
1132 boolean oldValue = interrupted;
1133 if (oldValue) {
1134 disableSuspendAndPreempt();
1135 try {
1136 synchronized (interruptLock) {
1137 interrupted = false;
1138 carrierThread.clearInterrupt();
1139 }
1140 } finally {
1141 enableSuspendAndPreempt();
1142 }
1143 }
1144 return oldValue;
1145 }
1146
1147 @Override
1148 Thread.State threadState() {
1149 int s = state();
1150 switch (s & ~SUSPENDED) {
1151 case NEW:
1152 return Thread.State.NEW;
1153 case STARTED:
1154 // return NEW if thread container not yet set
1155 if (threadContainer() == null) {
1156 return Thread.State.NEW;
1157 } else {
1158 return Thread.State.RUNNABLE;
1159 }
1160 case UNPARKED:
1161 case UNBLOCKED:
1162 case YIELDED:
1163 // runnable, not mounted
1164 return Thread.State.RUNNABLE;
1165 case RUNNING:
1166 // if mounted then return state of carrier thread
1167 if (Thread.currentThread() != this) {
1168 disableSuspendAndPreempt();
1169 try {
1170 synchronized (carrierThreadAccessLock()) {
1171 Thread carrierThread = this.carrierThread;
1172 if (carrierThread != null) {
1173 return carrierThread.threadState();
1174 }
1175 }
1176 } finally {
1177 enableSuspendAndPreempt();
1178 }
1179 }
1180 // runnable, mounted
1181 return Thread.State.RUNNABLE;
1182 case PARKING:
1183 case TIMED_PARKING:
1184 case WAITING:
1185 case TIMED_WAITING:
1186 case YIELDING:
1187 // runnable, in transition
1188 return Thread.State.RUNNABLE;
1189 case PARKED:
1190 case PINNED:
1191 case WAIT:
1192 return Thread.State.WAITING;
1193 case TIMED_PARKED:
1194 case TIMED_PINNED:
1195 case TIMED_WAIT:
1196 return Thread.State.TIMED_WAITING;
1197 case BLOCKING:
1198 case BLOCKED:
1199 return Thread.State.BLOCKED;
1200 case TERMINATED:
1201 return Thread.State.TERMINATED;
1202 default:
1203 throw new InternalError();
1204 }
1205 }
1206
1207 @Override
1208 boolean alive() {
1209 int s = state;
1210 return (s != NEW && s != TERMINATED);
1211 }
1212
1213 @Override
1214 boolean isTerminated() {
1215 return (state == TERMINATED);
1216 }
1217
1218 @Override
1219 StackTraceElement[] asyncGetStackTrace() {
1220 StackTraceElement[] stackTrace;
1221 do {
1222 stackTrace = (carrierThread != null)
1223 ? super.asyncGetStackTrace() // mounted
1224 : tryGetStackTrace(); // unmounted
1225 if (stackTrace == null) {
1226 Thread.yield();
1227 }
1228 } while (stackTrace == null);
1229 return stackTrace;
1230 }
1231
1232 /**
1233 * Returns the stack trace for this virtual thread if it is unmounted.
1234 * Returns null if the thread is mounted or in transition.
1235 */
1236 private StackTraceElement[] tryGetStackTrace() {
1237 int initialState = state() & ~SUSPENDED;
1238 switch (initialState) {
1239 case NEW, STARTED, TERMINATED -> {
1240 return new StackTraceElement[0]; // unmounted, empty stack
1241 }
1242 case RUNNING, PINNED, TIMED_PINNED -> {
1243 return null; // mounted
1244 }
1245 case PARKED, TIMED_PARKED, BLOCKED, WAIT, TIMED_WAIT -> {
1246 // unmounted, not runnable
1247 }
1248 case UNPARKED, UNBLOCKED, YIELDED -> {
1249 // unmounted, runnable
1250 }
1251 case PARKING, TIMED_PARKING, BLOCKING, YIELDING, WAITING, TIMED_WAITING -> {
1252 return null; // in transition
1253 }
1254 default -> throw new InternalError("" + initialState);
1255 }
1256
1257 // thread is unmounted, prevent it from continuing
1258 int suspendedState = initialState | SUSPENDED;
1259 if (!compareAndSetState(initialState, suspendedState)) {
1260 return null;
1261 }
1262
1263 // get stack trace and restore state
1264 StackTraceElement[] stack;
1265 try {
1266 stack = cont.getStackTrace();
1267 } finally {
1268 assert state == suspendedState;
1269 setState(initialState);
1270 }
1271 boolean resubmit = switch (initialState) {
1272 case UNPARKED, UNBLOCKED, YIELDED -> {
1273 // resubmit as task may have run while suspended
1274 yield true;
1275 }
1276 case PARKED, TIMED_PARKED -> {
1277 // resubmit if unparked while suspended
1278 yield parkPermit && compareAndSetState(initialState, UNPARKED);
1279 }
1280 case BLOCKED -> {
1281 // resubmit if unblocked while suspended
1282 yield blockPermit && compareAndSetState(BLOCKED, UNBLOCKED);
1283 }
1284 case WAIT, TIMED_WAIT -> {
1285 // resubmit if notified or interrupted while waiting (Object.wait)
1286 // waitTimeoutExpired will retry if the timed expired when suspended
1287 yield (notified || interrupted) && compareAndSetState(initialState, UNBLOCKED);
1288 }
1289 default -> throw new InternalError();
1290 };
1291 if (resubmit) {
1292 submitRunContinuation();
1293 }
1294 return stack;
1295 }
1296
1297 @Override
1298 public String toString() {
1299 StringBuilder sb = new StringBuilder("VirtualThread[#");
1300 sb.append(threadId());
1301 String name = getName();
1302 if (!name.isEmpty()) {
1303 sb.append(",");
1304 sb.append(name);
1305 }
1306 sb.append("]/");
1307
1308 // add the carrier state and thread name when mounted
1309 boolean mounted;
1310 if (Thread.currentThread() == this) {
1311 mounted = appendCarrierInfo(sb);
1312 } else {
1313 disableSuspendAndPreempt();
1314 try {
1315 synchronized (carrierThreadAccessLock()) {
1316 mounted = appendCarrierInfo(sb);
1317 }
1318 } finally {
1319 enableSuspendAndPreempt();
1320 }
1321 }
1322
1323 // add virtual thread state when not mounted
1324 if (!mounted) {
1325 String stateAsString = threadState().toString();
1326 sb.append(stateAsString.toLowerCase(Locale.ROOT));
1327 }
1328
1329 return sb.toString();
1330 }
1331
1332 /**
1333 * Appends the carrier state and thread name to the string buffer if mounted.
1334 * @return true if mounted, false if not mounted
1335 */
1336 private boolean appendCarrierInfo(StringBuilder sb) {
1337 assert Thread.currentThread() == this || Thread.holdsLock(carrierThreadAccessLock());
1338 Thread carrier = carrierThread;
1339 if (carrier != null) {
1340 String stateAsString = carrier.threadState().toString();
1341 sb.append(stateAsString.toLowerCase(Locale.ROOT));
1342 sb.append('@');
1343 sb.append(carrier.getName());
1344 return true;
1345 } else {
1346 return false;
1347 }
1348 }
1349
1350 @Override
1351 public int hashCode() {
1352 return (int) threadId();
1353 }
1354
1355 @Override
1356 public boolean equals(Object obj) {
1357 return obj == this;
1358 }
1359
1360 /**
1361 * Returns the termination object, creating it if needed.
1362 */
1363 private CountDownLatch getTermination() {
1364 CountDownLatch termination = this.termination;
1365 if (termination == null) {
1366 termination = new CountDownLatch(1);
1367 if (!U.compareAndSetReference(this, TERMINATION, null, termination)) {
1368 termination = this.termination;
1369 }
1370 }
1371 return termination;
1372 }
1373
1374 /**
1375 * Returns the lock object to synchronize on when accessing carrierThread.
1376 * The lock prevents carrierThread from being reset to null during unmount.
1377 */
1378 private Object carrierThreadAccessLock() {
1379 // return interruptLock as unmount has to coordinate with interrupt
1380 return interruptLock;
1381 }
1382
1383 /**
1384 * Returns a lock object for coordinating timed-wait setup and timeout handling.
1385 */
1386 private Object timedWaitLock() {
1387 // use this object for now to avoid the overhead of introducing another lock
1388 return runContinuation;
1389 }
1390
1391 /**
1392 * Disallow the current thread be suspended or preempted.
1393 */
1394 private void disableSuspendAndPreempt() {
1395 notifyJvmtiDisableSuspend(true);
1396 Continuation.pin();
1397 }
1398
1399 /**
1400 * Allow the current thread be suspended or preempted.
1401 */
1402 private void enableSuspendAndPreempt() {
1403 Continuation.unpin();
1404 notifyJvmtiDisableSuspend(false);
1405 }
1406
1407 // -- wrappers for get/set of state, parking permit, and carrier thread --
1408
1409 private int state() {
1410 return state; // volatile read
1411 }
1412
1413 private void setState(int newValue) {
1414 state = newValue; // volatile write
1415 }
1416
1417 private boolean compareAndSetState(int expectedValue, int newValue) {
1418 return U.compareAndSetInt(this, STATE, expectedValue, newValue);
1419 }
1420
1421 private boolean compareAndSetOnWaitingList(boolean expectedValue, boolean newValue) {
1422 return U.compareAndSetBoolean(this, ON_WAITING_LIST, expectedValue, newValue);
1423 }
1424
1425 private void setParkPermit(boolean newValue) {
1426 if (parkPermit != newValue) {
1427 parkPermit = newValue;
1428 }
1429 }
1430
1431 private boolean getAndSetParkPermit(boolean newValue) {
1432 if (parkPermit != newValue) {
1433 return U.getAndSetBoolean(this, PARK_PERMIT, newValue);
1434 } else {
1435 return newValue;
1436 }
1437 }
1438
1439 private void setCarrierThread(Thread carrier) {
1440 // U.putReferenceRelease(this, CARRIER_THREAD, carrier);
1441 this.carrierThread = carrier;
1442 }
1443
1444 // -- JVM TI support --
1445
1446 @IntrinsicCandidate
1447 @JvmtiMountTransition
1448 private native void notifyJvmtiStart();
1449
1450 @IntrinsicCandidate
1451 @JvmtiMountTransition
1452 private native void notifyJvmtiEnd();
1453
1454 @IntrinsicCandidate
1455 @JvmtiMountTransition
1456 private native void notifyJvmtiMount(boolean hide);
1457
1458 @IntrinsicCandidate
1459 @JvmtiMountTransition
1460 private native void notifyJvmtiUnmount(boolean hide);
1461
1462 @IntrinsicCandidate
1463 private static native void notifyJvmtiDisableSuspend(boolean enter);
1464
1465 private static native void registerNatives();
1466 static {
1467 registerNatives();
1468
1469 // ensure VTHREAD_GROUP is created, may be accessed by JVMTI
1470 var group = Thread.virtualThreadGroup();
1471 }
1472
1473 /**
1474 * Loads a VirtualThreadScheduler with the given class name. The class must be public
1475 * in an exported package, with public one-arg or no-arg constructor, and be visible
1476 * to the system class loader.
1477 * @param delegate the scheduler that the custom scheduler may delegate to
1478 * @param cn the class name of the custom scheduler
1479 */
1480 private static VirtualThreadScheduler loadCustomScheduler(VirtualThreadScheduler delegate, String cn) {
1481 try {
1482 Class<?> clazz = Class.forName(cn, true, ClassLoader.getSystemClassLoader());
1483 VirtualThreadScheduler scheduler;
1484 try {
1485 // 1-arg constructor
1486 Constructor<?> ctor = clazz.getConstructor(VirtualThreadScheduler.class);
1487 scheduler = (VirtualThreadScheduler) ctor.newInstance(delegate);
1488 } catch (NoSuchMethodException e) {
1489 // 0-arg constructor
1490 Constructor<?> ctor = clazz.getConstructor();
1491 scheduler = (VirtualThreadScheduler) ctor.newInstance();
1492 }
1493 System.err.println("""
1494 WARNING: Using custom default scheduler, this is an experimental feature!""");
1495 return scheduler;
1496 } catch (Exception ex) {
1497 throw new Error(ex);
1498 }
1499 }
1500
1501 /**
1502 * Creates the built-in default ForkJoinPool scheduler.
1503 * @param wrapped true if wrapped by a custom default scheduler
1504 */
1505 private static BuiltinDefaultScheduler createBuiltinDefaultScheduler(boolean wrapped) {
1506 int parallelism, maxPoolSize, minRunnable;
1507 String parallelismValue = System.getProperty("jdk.virtualThreadScheduler.parallelism");
1508 String maxPoolSizeValue = System.getProperty("jdk.virtualThreadScheduler.maxPoolSize");
1509 String minRunnableValue = System.getProperty("jdk.virtualThreadScheduler.minRunnable");
1510 if (parallelismValue != null) {
1511 parallelism = Integer.parseInt(parallelismValue);
1512 } else {
1513 parallelism = Runtime.getRuntime().availableProcessors();
1514 }
1515 if (maxPoolSizeValue != null) {
1516 maxPoolSize = Integer.parseInt(maxPoolSizeValue);
1517 parallelism = Integer.min(parallelism, maxPoolSize);
1518 } else {
1519 maxPoolSize = Integer.max(parallelism, 256);
1520 }
1521 if (minRunnableValue != null) {
1522 minRunnable = Integer.parseInt(minRunnableValue);
1523 } else {
1524 minRunnable = Integer.max(parallelism / 2, 1);
1525 }
1526 return new BuiltinDefaultScheduler(parallelism, maxPoolSize, minRunnable, wrapped);
1527 }
1528
1529 /**
1530 * The built-in default ForkJoinPool scheduler.
1531 */
1532 private static class BuiltinDefaultScheduler
1533 extends ForkJoinPool implements VirtualThreadScheduler {
1534
1535 private static final StableValue<VirtualThreadScheduler> VIEW = StableValue.of();
1536
1537 BuiltinDefaultScheduler(int parallelism, int maxPoolSize, int minRunnable, boolean wrapped) {
1538 ForkJoinWorkerThreadFactory factory = wrapped
1539 ? ForkJoinPool.defaultForkJoinWorkerThreadFactory
1540 : CarrierThread::new;
1541 Thread.UncaughtExceptionHandler handler = (t, e) -> { };
1542 boolean asyncMode = true; // FIFO
1543 super(parallelism, factory, handler, asyncMode,
1544 0, maxPoolSize, minRunnable, pool -> true, 30, SECONDS);
1545 }
1546
1547 private void adaptAndExecute(Runnable task) {
1548 execute(ForkJoinTask.adapt(task));
1549 }
1550
1551 @Override
1552 public void onStart(Thread vthread, Runnable task) {
1553 adaptAndExecute(task);
1554 }
1555
1556 @Override
1557 public void onContinue(Thread vthread, Runnable task) {
1558 adaptAndExecute(task);
1559 }
1560
1561 /**
1562 * Wraps the scheduler to avoid leaking a direct reference.
1563 */
1564 VirtualThreadScheduler externalView() {
1565 BuiltinDefaultScheduler builtin = this;
1566 return VIEW.orElseSet(() -> {
1567 return new VirtualThreadScheduler() {
1568 private void execute(Thread thread, Runnable task) {
1569 Objects.requireNonNull(thread);
1570 if (thread instanceof VirtualThread vthread) {
1571 VirtualThreadScheduler scheduler = vthread.scheduler;
1572 if (scheduler == this || scheduler == DEFAULT_SCHEDULER) {
1573 builtin.adaptAndExecute(task);
1574 } else {
1575 throw new IllegalArgumentException();
1576 }
1577 } else {
1578 throw new UnsupportedOperationException();
1579 }
1580 }
1581 @Override
1582 public void onStart(Thread thread, Runnable task) {
1583 execute(thread, task);
1584 }
1585 @Override
1586 public void onContinue(Thread thread, Runnable task) {
1587 execute(thread, task);
1588 }
1589 };
1590 });
1591 }
1592 }
1593
1594 /**
1595 * Schedule a runnable task to run after a delay.
1596 */
1597 private Future<?> schedule(Runnable command, long delay, TimeUnit unit) {
1598 if (scheduler instanceof ForkJoinPool pool) {
1599 return pool.schedule(command, delay, unit);
1600 } else {
1601 return DelayedTaskSchedulers.schedule(command, delay, unit);
1602 }
1603 }
1604
1605 /**
1606 * Supports scheduling a runnable task to run after a delay. It uses a number
1607 * of ScheduledThreadPoolExecutor instances to reduce contention on the delayed
1608 * work queue used. This class is used when using a custom scheduler.
1609 */
1610 private static class DelayedTaskSchedulers {
1611 private static final ScheduledExecutorService[] INSTANCE = createDelayedTaskSchedulers();
1612
1613 static Future<?> schedule(Runnable command, long delay, TimeUnit unit) {
1614 long tid = Thread.currentThread().threadId();
1615 int index = (int) tid & (INSTANCE.length - 1);
1616 return INSTANCE[index].schedule(command, delay, unit);
1617 }
1618
1619 private static ScheduledExecutorService[] createDelayedTaskSchedulers() {
1620 String propName = "jdk.virtualThreadScheduler.timerQueues";
1621 String propValue = System.getProperty(propName);
1622 int queueCount;
1623 if (propValue != null) {
1624 queueCount = Integer.parseInt(propValue);
1625 if (queueCount != Integer.highestOneBit(queueCount)) {
1626 throw new RuntimeException("Value of " + propName + " must be power of 2");
1627 }
1628 } else {
1629 int ncpus = Runtime.getRuntime().availableProcessors();
1630 queueCount = Math.max(Integer.highestOneBit(ncpus / 4), 1);
1631 }
1632 var schedulers = new ScheduledExecutorService[queueCount];
1633 for (int i = 0; i < queueCount; i++) {
1634 ScheduledThreadPoolExecutor stpe = (ScheduledThreadPoolExecutor)
1635 Executors.newScheduledThreadPool(1, task -> {
1636 Thread t = InnocuousThread.newThread("VirtualThread-unparker", task);
1637 t.setDaemon(true);
1638 return t;
1639 });
1640 stpe.setRemoveOnCancelPolicy(true);
1641 schedulers[i] = stpe;
1642 }
1643 return schedulers;
1644 }
1645 }
1646
1647 /**
1648 * Schedule virtual threads that are ready to be scheduled after they blocked on
1649 * monitor enter.
1650 */
1651 private static void unblockVirtualThreads() {
1652 while (true) {
1653 VirtualThread vthread = takeVirtualThreadListToUnblock();
1654 while (vthread != null) {
1655 assert vthread.onWaitingList;
1656 VirtualThread nextThread = vthread.next;
1657
1658 // remove from list and unblock
1659 vthread.next = null;
1660 boolean changed = vthread.compareAndSetOnWaitingList(true, false);
1661 assert changed;
1662 vthread.unblock();
1663
1664 vthread = nextThread;
1665 }
1666 }
1667 }
1668
1669 /**
1670 * Retrieves the list of virtual threads that are waiting to be unblocked, waiting
1671 * if necessary until a list of one or more threads becomes available.
1672 */
1673 private static native VirtualThread takeVirtualThreadListToUnblock();
1674
1675 static {
1676 var unblocker = InnocuousThread.newThread("VirtualThread-unblocker",
1677 VirtualThread::unblockVirtualThreads);
1678 unblocker.setDaemon(true);
1679 unblocker.start();
1680 }
1681 }