1 # Custom Schedulers
 2 
 3 The following is a summary of the experimental support for custom virtual thread schedulers
 4 in the loom repo.
 5 
 6 The purpose of the experimental support is to allow exploration and get feedback to help
 7 inform this project on whether to expose anything.
 8 
 9 The experimental support may change or be removed at any time.
10 
11 ## Using a custom scheduler as the default scheduler
12 
13 The JDK's built-in virtual thread scheduler is a `ForkJoinPool` instance that is
14 configured in FIFO mode.
15 
16 A default scheduler can be used by setting a system
17 property on the command line.
18 
19 ```
20 -Djdk.virtualThreadScheduler.implClass=<scheduler-class>
21 ```
22 
23 where `<scheduler-class>` is fully qualified name of a class that implements
24 `java.lang.Thread.VirtualThreadScheduler`. The scheduler's `execute` method is invoked
25 to continue execution of a virtual thread.
26 
27 A custom scheduler may use its own pool of platform threads, may assign virtual threads to
28 be carried by specific platform threads, or may delegate to the built-in default scheduler.
29 
30 The implementation class must be public, with a public no-arg or one-arg constructor, and
31 deployed on the class path or in an exported package of a module on the module path. If the
32 class has a one-arg constructor then the parameter is a `java.lang.Thread.VirtualThreadScheduler`
33 that is a reference to the built-in default scheduler.
34 
35 
36 ## Use the API to select a custom scheduler when creating a virtual thread
37 
38 `Thread.Builder.OfVirtual.scheduler(Thread.VirtualThreadScheduler)` can be used to set the
39 scheduler when creating a virtual thread. The experimental supports allows several
40 schedulers to be in use at the same time.
41 
42 The following example uses a thread pool with 8 threads as the scheduler.
43 
44 ```
45 ExecuorService pool = Executors.newFixedThreadPool(8);
46 var scheduler = Thread.VirtualThreadScheduler.adapt(pool);
47 
48 Thread thread = Thread.ofVirtual().scheduler(scheduler).start(() -> { });
49 thread.join();
50 ```