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:

  • 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 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.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:

    • 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:

    • 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