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 (not exhaustive)
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:
99
See Also:

  • 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:
      
   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 count is negative

    • allowSetThreadLocals

      Thread.Builder 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 set method throws UnsupportedOperationException and the get method always returns the initial-value.
      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.Builder inheritInheritableThreadLocals(boolean inherit)
      Sets whether the thread inherits the initial values of inheritable-thread-local variables. The default is to inherit.

      The initial values of InheritableThreadLocals 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.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 a thread group has been set and the current thread cannot create a thread in that thread group
      See Also:

    • start

      default Thread start(Runnable task)
      Creates a new Thread from the current state of the builder and schedules it to execute.
      Implementation Requirements:
      The default implementation invokes unstarted to create a Thread and then invokes its start method to schedule it to execute.
      Parameters:
      task - the object to run when the thread executes
      Returns:
      a new started Thread
      Throws:
      SecurityException - if a thread group has been set and the current thread cannot create a thread in that thread group
      See Also:

    • 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