# 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
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
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