Module java.base
Package java.lang

Class Thread

java.lang.Object
java.lang.Thread
All Implemented Interfaces:
Runnable
Direct Known Subclasses:
ForkJoinWorkerThread
public class Thread extends Object implements Runnable
A thread is a thread of execution in a program. The Java virtual machine allows an application to have multiple threads of execution running concurrently.

Thread defines constructors and a Thread.Builder to create threads. Starting a thread schedules it to execute its run method. The newly started thread executes concurrently with the thread that caused it to start.

A thread terminates if either its run method completes normally, or if its run method completes abruptly and the appropriate uncaught exception handler completes normally or abruptly. With no code left to run, the thread has completed execution. The join method can be used to wait for a thread to terminate.

Threads have a unique identifier and a name. The identifier is generated when a Thread is created and cannot be changed. The thread name can be specified when creating a thread or can be changed at a later time.

Threads support ThreadLocal variables. These are variables that are local to a thread, meaning a thread can have a copy of a variable that is set to a value that is independent of the value set by other threads. Thread also supports InheritableThreadLocal variables that are thread local variables that are inherited at thread creation time from the parent Thread. Thread supports a special inheritable thread local for the thread context-class-loader.

Platform threads

Thread supports the creation of platform threads that are typically mapped 1:1 to kernel threads scheduled by the operating system. Platform threads will usually have a large stack and other resources that are maintained by the operating system. Platforms threads are suitable for executing all types of tasks but may be a limited resource.

Platform threads get an automatically generated thread name by default.

Platform threads are designated daemon or non-daemon threads. When the Java virtual machine starts up, there is usually one non-daemon thread (the thread that typically calls the application's main method). The shutdown sequence begins when all started non-daemon threads have terminated. Unstarted non-daemon threads do not prevent the shutdown sequence from beginning.

In addition to the daemon status, platform threads have a thread priority and are members of a thread group.

Virtual threads

Thread also supports the creation of virtual threads. Virtual threads are typically user-mode threads scheduled by the Java runtime rather than the operating system. Virtual threads will typically require few resources and a single Java virtual machine may support millions of virtual threads. Virtual threads are suitable for executing tasks that spend most of the time blocked, often waiting for I/O operations to complete. Virtual threads are not intended for long running CPU intensive operations.

Virtual threads typically employ a small set of platform threads used as carrier threads. Locking and I/O operations are examples of operations where a carrier thread may be re-scheduled from one virtual thread to another. Code executing in a virtual thread is not aware of the underlying carrier thread. The currentThread() method, used to obtain a reference to the current thread, will always return the Thread object for the virtual thread.

Virtual threads do not have a thread name by default. The getName method returns the empty string if a thread name is not set.

Virtual threads are daemon threads and so do not prevent the shutdown sequence from beginning. Virtual threads have a fixed thread priority that cannot be changed.

Creating and starting threads

Thread defines public constructors for creating platform threads and the start method to schedule threads to execute. Thread may be extended for customization and other advanced reasons although most applications should have little need to do this.

Thread defines a Thread.Builder API for creating and starting both platform and virtual threads. The following are examples that use the builder: 

  Runnable runnable = ...

  // Start a daemon thread to run a task
  Thread thread = Thread.ofPlatform().daemon().start(runnable);

  // Create an unstarted thread with name "duke", its start() method
  // must be invoked to schedule it to execute.
  Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);

  // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
  ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();

  // Start a virtual thread to run a task
  Thread thread = Thread.ofVirtual().start(runnable);

  // A ThreadFactory that creates virtual threads
  ThreadFactory factory = Thread.ofVirtual().factory();

Inheritance when creating threads

A Thread inherits its initial values of inheritable-thread-local variables (including the context class loader) from the parent thread values at the time that the child Thread is created. The 5-param constructor can be used to create a thread that does not inherit its initial values from the constructing thread. When using a Thread.Builder, the inheritInheritableThreadLocals method can be used to select if the initial values are inherited.

Platform threads inherit the daemon status, thread priority, and when not provided (or not selected by a security manager), the thread group.

Creating a platform thread captures the caller context to limit the permissions of the new thread when it executes code that performs a privileged action. The captured caller context is the new thread's "Inherited AccessControlContext". Creating a virtual thread does not capture the caller context; virtual threads have no permissions when executing code that performs a privileged action.

Unless otherwise specified, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

Implementation Note:
In the JDK Reference Implementation, the virtual thread scheduler may be configured with the following system properties:
System properties
System property Description
jdk.virtualThreadScheduler.parallelism The number of platform threads available for scheduling virtual threads. It defaults to the number of available processors.
jdk.virtualThreadScheduler.maxPoolSize The maximum number of platform threads available to the scheduler. It defaults to 256.
Since:
1.0