- Enclosing class:
- Thread
Thread
or ThreadFactory
.
Builder
defines methods to set the Thread
characteristics
and features. Once set, a Thread
or ThreadFactory
can be
created with the following methods:
- The build method creates an unstarted
Thread
. - The start method creates and starts a
Thread
. - The factory method creates a
ThreadFactory
.
A Builder
is not thread safe. The ThreadFactory
returned by the builder's factory() method
is thread safe.
Unless otherwise specified, passing a null argument to a method in
this interface causes a NullPointerException
to be thrown.
- API Note:
Builder
checks invariants as components are added to the builder. The rationale for this is to detect errors as early as possible and not defer all validation to thebuild
method.- Since:
- 99
- See Also:
Thread.builder()
-
Method Summary
Modifier and TypeMethodDescriptionbuild()
Creates a new unstartedThread
from the current state of the builder.daemon(boolean on)
Sets the daemon status.factory()
Returns aThreadFactory
to create threads from the current state of the builder.group(ThreadGroup group)
Sets the thread group.Sets the thread name.Sets the thread name to be the concatenation of a string prefix and a counter value.The thread will not inherit the initial values for inheritable-thread-local variables.The thread is not allowed to set values for its copy of thread-local variables.priority(int priority)
Sets the thread priority.default Thread
start()
Creates a newThread
from the current state of the builder and starts it as if by invoking the start method.Sets the task for the thread to run.Sets the uncaught exception handler.virtual()
The thread will be scheduled by the Java virtual machine rather than the operating system.The thread will be scheduled by the Java virtual machine rather than the operating system with the given scheduler.
-
Method Details
-
group
Sets the thread group. The thread group of a virtual thread cannot be selected at build time. Setting the thread group of a virtual thread has no effect.- Parameters:
group
- the thread group- Returns:
- this builder
-
name
Sets the thread name.- Parameters:
name
- thread name- Returns:
- this builder
-
name
Sets the thread name to be the concatenation of a string prefix and a counter value.- Parameters:
prefix
- thread name prefixstart
- counter start- Returns:
- this builder
- Throws:
IllegalArgumentException
- if count is negative
-
virtual
Thread.Builder virtual()The thread will be scheduled by the Java virtual machine rather than the operating system. The scheduler will be selected when the thread is created or started.- Returns:
- this builder
-
virtual
The thread will be scheduled by the Java virtual machine rather than the operating system with the given scheduler. The scheduler'sexecute
method is invoked with tasks of typeThread.VirtualThreadTask
. It may be invoked in the context of a virtual thread. The scheduler should arrange to execute these tasks on a platform thread. Attempting to execute the task on a virtual thread causes an exception to be thrown (seeThread.VirtualThreadTask.run()
). Theexecute
method may be invoked at sensitive times (e.g. when unparking a thread) so care should be taken to not directly execute the task on the current thread.- Parameters:
scheduler
- the scheduler ornull
for the default scheduler- Returns:
- this builder
-
noThreadLocals
Thread.Builder noThreadLocals()The thread is not allowed to set values for its copy of thread-local variables. If the thread attempts to set a value for a thread-local with theThreadLocal.set(Object)
method thenUnsupportedOperationException
is thrown.- Returns:
- this builder
- See Also:
ThreadLocal.set(Object)
-
noInheritInheritableThreadLocals
Thread.Builder noInheritInheritableThreadLocals()The thread will not inherit the initial values for inheritable-thread-local variables. The thread will also not inherit the initial values whennoThreadLocals()
is used to disallow the thread from setting the values of thread-local variables.- Returns:
- this builder
-
daemon
Sets the daemon status. Thedaemon status
of virtual threads is alwaystrue
. Setting the daemon status of a virtual thread has no effect.- Parameters:
on
-true
to create daemon threads- Returns:
- this builder
-
priority
Sets the thread priority. The priority of virtual threads is always Thread.NORM_PRIORITY. Setting the priority of a virtual thread has no effect.- Parameters:
priority
- priority- Returns:
- this builder
- Throws:
IllegalArgumentException
- if the priority is less thanThread.MIN_PRIORITY
or greater thanThread.MAX_PRIORITY
-
uncaughtExceptionHandler
Sets the uncaught exception handler.- Parameters:
ueh
- uncaught exception handler- Returns:
- this builder
-
task
Sets the task for the thread to run.- Parameters:
task
- the task to run- Returns:
- this builder
-
build
Thread build()Creates a new unstartedThread
from the current state of the builder.When this method creates a platform thread then it will inherit the thread-group, priority, and daemon status of the current thread if these characteristics have not been set. The context-class-loader is inherited from the current thread.
When this method creates a virtual thread and a scheduler has not been set then the thread will be scheduled using the default scheduler if the current thread is a platform thread, or the scheduler for the current thread if it is a virtual thread. The
context-class-loader
is inherited from the current thread. The thread will have nopermissions
.- Returns:
- a new unstarted Thread
- Throws:
IllegalStateException
- if the task object to run object has not been setSecurityException
- if a thread group has been set and the current thread cannot create a thread in that thread group
-
factory
ThreadFactory factory()Returns aThreadFactory
to create threads from the current state of the builder. The returned thread factory is safe for use by multiple concurrent threads.A
ThreadFactory
that creates platform threads will inherit the thread-group, priority, and daemon status of the current thread when creating aThread
if these characteristics have not been set. The context-class-loader is inherited from the current thread when creating aThread
.A
ThreadFactory
that creates virtual threads will use the selected scheduler. If a scheduler has not been set then theThreadFactory
will select the scheduler when creating aThread
. The default scheduler will be selected if the current thread is a platform thread. It will use the scheduler for the current thread if it is a virtual thread. Thecontext-class-loader
is inherited from the current thread. The thread will have nopermissions
.- Returns:
- a thread factory to create threads
-
start
Creates a newThread
from the current state of the builder and starts it as if by invoking the start method.When this method starts a platform thread then it will inherit the thread-group, priority, and daemon status of the current thread if these characteristics have not been set. The context-class-loader is inherited from the current thread.
When this method starts a virtual thread and a scheduler has not been set then the thread will be scheduled using the default scheduler if the current thread is a platform thread, or the scheduler for the current thread if it is a virtual thread. The
context-class-loader
is inherited from the current thread. The thread will have nopermissions
.- Implementation Requirements:
- The default implementation invokes build
to create a
Thread
and then invokes its start method to start it. - Returns:
- The started thread
- Throws:
IllegalStateException
- if the task object to run object has not been setSecurityException
- if a thread group has been set and the current thread cannot create a thread in that thread group
-