Module java.base
Package java.lang

# Interface Thread.Builder

All Known Subinterfaces:
  `Thread.Builder.OfPlatformPREVIEW`, `Thread.Builder.OfVirtualPREVIEW`

Enclosing class:
  `Thread`

public static sealed interface Thread.Builder permits Thread.Builder.OfPlatformPREVIEW, Thread.Builder.OfVirtualPREVIEW (not exhaustive)
`Builder` is a preview API of the Java platform.
Programs can only use `Builder` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
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:
  19
See Also:
  - `Thread.ofPlatform()`PREVIEW
  - `Thread.ofVirtual()`PREVIEW

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `Thread.Builder.OfPlatformPREVIEW`
  Preview.
  A builder for creating a platform `Thread` or `ThreadFactory` that creates platform threads.
  `static interface`
  `Thread.Builder.OfVirtualPREVIEW`
  Preview.
  A builder for creating a virtual `Thread` or `ThreadFactory` that creates virtual threads.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Thread.BuilderPREVIEW`
  `allowSetThreadLocals(boolean allow)`
  Sets whether the thread is allowed to set values for its copy of thread-local variables.
  `ThreadFactory`
  `factory()`
  Returns a `ThreadFactory` to create threads from the current state of the builder.
  `Thread.BuilderPREVIEW`
  `inheritInheritableThreadLocals(boolean inherit)`
  Sets whether the thread inherits the initial values of inheritable-thread-local variables from the constructing thread.
  `Thread.BuilderPREVIEW`
  `name(String name)`
  Sets the thread name.
  `Thread.BuilderPREVIEW`
  `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.BuilderPREVIEW`
  `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.BuilderPREVIEW name(String name)
    Sets the thread name.
    Parameters:
      `name` - thread name
    Returns:
      this builder

  - ### name

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

  - ### allowSetThreadLocals

    Thread.BuilderPREVIEW allowSetThreadLocals(boolean allow)
    Sets whether the thread is allowed to set values for its copy of thread-local variables. The default is to allow. If not allowed, then any attempt by the thread to set a value for a thread-local with the `ThreadLocal.set(Object)` method throws `UnsupportedOperationException`. Any attempt to set the thread's context class loader with `setContextClassLoader` also throws. The `ThreadLocal.get()` method always returns the initial-value when thread locals are not allowed.
    API Note:
      This method is intended for cases where there are a large number of threads and where potentially unbounded memory usage due to thread locals is a concern. Disallowing a thread to set its copy of thread-local variables creates the potential for exceptions at run-time so great care is required when the thread is used to invoke arbitrary code.
    Parameters:
      `allow` - `true` to allow, `false` to disallow
    Returns:
      this builder

  - ### inheritInheritableThreadLocals

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

    The initial values of `InheritableThreadLocal`s are never inherited when `allowSetThreadLocals(boolean)` is used to disallow the thread to have its own copy of thread-local variables.

    Parameters:
      `inherit` - `true` to inherit, `false` to not inherit
    Returns:
      this builder

  - ### uncaughtExceptionHandler

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