Module java.base

Package java.lang

Interface Thread.Builder

All Known Subinterfaces:

Thread.Builder.OfPlatform, Thread.Builder.OfVirtual

Enclosing class:

Thread

public static sealed interface Thread.Builder
permits Thread.Builder.OfPlatform, Thread.Builder.OfVirtual

A builder for Thread and ThreadFactory objects.

Builder defines methods to set Thread properties such as the thread name. This includes properties that would otherwise be inherited. Once set, a Thread or ThreadFactory is created with the following methods:

• The unstarted method creates a new unstarted Thread to run a task. The Thread's start method must be invoked to schedule the thread to execute.
• The start method creates a new Thread to run a task and schedules the thread to execute.
• The factory method creates a ThreadFactory.

A Thread.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.

Since:

21

See Also:

• Thread.ofPlatform()
• Thread.ofVirtual()

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Thread.Builder.OfPlatform	A builder for creating a platform Thread or ThreadFactory that creates platform threads.
static interface	Thread.Builder.OfVirtual	A builder for creating a virtual Thread or ThreadFactory that creates virtual threads.

Method Summary

Modifier and Type	Method	Description
ThreadFactory	factory()	Returns a ThreadFactory to create threads from the current state of the builder.
Thread.Builder	inheritInheritableThreadLocals(boolean inherit)	Sets whether the thread inherits the initial values of inheritable-thread-local variables from the constructing thread.
Thread.Builder	name(String name)	Sets the thread name.
Thread.Builder	name(String prefix, long start)	Sets the thread name to be the concatenation of a string prefix and the string representation of a counter value.
Thread	start(Runnable task)	Creates a new Thread from the current state of the builder and schedules it to execute.
Thread.Builder	uncaughtExceptionHandler(Thread.UncaughtExceptionHandler ueh)	Sets the uncaught exception handler.
Thread	unstarted(Runnable task)	Creates a new Thread from the current state of the builder to run the given task.

Method Details

name

Thread.Builder name(String name)

Sets the thread name.

Parameters:

name - thread name

Returns:

this builder

name

Thread.Builder name(String prefix,
 long start)

Sets the thread name to be the concatenation of a string prefix and the string representation of a counter value. The counter's initial value is start. It is incremented after a Thread is created with this builder so that the next thread is named with the new counter value. A ThreadFactory created with this builder is seeded with the current value of the counter. The ThreadFactory increments its copy of the counter after newThread is used to create a Thread.

API Note:

The following example creates a builder that is invoked twice to start two threads named "worker-0" and "worker-1".

  Thread.Builder builder = Thread.ofPlatform().name("worker-", 0);
  Thread t1 = builder.start(task1);   // name "worker-0"
  Thread t2 = builder.start(task2);   // name "worker-1"

Parameters:

prefix - thread name prefix

start - the starting value of the counter

Returns:

this builder

Throws:

IllegalArgumentException - if start is negative

inheritInheritableThreadLocals

Thread.Builder inheritInheritableThreadLocals(boolean inherit)

Sets whether the thread inherits the initial values of inheritable-thread-local variables from the constructing thread. The default is to inherit.

Parameters:

inherit - true to inherit, false to not inherit

Returns:

this builder

uncaughtExceptionHandler

Thread.Builder uncaughtExceptionHandler(Thread.UncaughtExceptionHandler ueh)

Sets the uncaught exception handler.

Parameters:

ueh - uncaught exception handler

Returns:

this builder

unstarted

Thread unstarted(Runnable task)

Creates a new Thread from the current state of the builder to run the given task. The Thread's start method must be invoked to schedule the thread to execute.

Parameters:

task - the object to run when the thread executes

Returns:

a new unstarted Thread

Throws:

SecurityException - if denied by the security manager (See Interaction with security manager when creating platform threads)

See Also:

• Inheritance when creating threads

start

Thread start(Runnable task)

Creates a new Thread from the current state of the builder and schedules it to execute.

Parameters:

task - the object to run when the thread executes

Returns:

a new started Thread

Throws:

SecurityException - if denied by the security manager (See Interaction with security manager when creating platform threads)

See Also:

• Inheritance when creating threads

factory

ThreadFactory factory()

Returns a ThreadFactory to create threads from the current state of the builder. The returned thread factory is safe for use by multiple concurrent threads.

Returns:

a thread factory to create threads