Module java.base
Package java.lang

Interface Thread.Builder

Enclosing class:
Thread
public static interface Thread.Builder
A mutable builder for a Thread or ThreadFactory.

Builder defines methods to set the Thread characteristics and features. Once set, a Thread or ThreadFactory can be created with the following methods:

  • The build method creates an unstarted Thread.
  • The start method creates and starts a Thread.
  • The factory method creates a ThreadFactory.

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

API Note:
Builder checks invariants as components are added to the builder. The rationale for this is to detect errors as early as possible and not defer all validation to the build method.
Since:
99
See Also:
Thread.builder()

  • Method Details

    • group

      Thread.Builder group​(ThreadGroup group)
      Sets the thread group.

      The thread group for threads that are scheduled by the Java virtual machine threads does not support all features of regular thread groups. The thread group can only be set for threads that are scheduled by the operating system.

      Parameters:
      group - the thread group
      Returns:
      this builder
      Throws:
      IllegalStateException - if this is a builder for a virtual thread

    • name

      Thread.Builder name​(String name)
      Sets the thread name.
      Parameters:
      name - thread name
      Returns:
      this builder

    • name

      Thread.Builder name​(String prefix, int start)
      Sets the thread name to be the concatenation of a string prefix and a counter value.
      Parameters:
      prefix - thread name prefix
      start - counter start
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if count is negative

    • virtual

      Thread.Builder virtual()
      The thread will be scheduled by the Java virtual machine rather than the operating system. The scheduler will be selected when the thread is created or started.
      Returns:
      this builder
      Throws:
      IllegalStateException - if a thread group has been set

    • virtual

      Thread.Builder virtual​(Executor scheduler)
      The thread will be scheduled by the Java virtual machine rather than the operating system with the given scheduler. The scheduler's execute method is invoked with tasks of type Thread.VirtualThreadTask. It may be invoked in the context of a virtual thread. The scheduler should arrange to execute these tasks on a kernel thread. Attempting to execute the task on a virtual thread causes an exception to be thrown (see Thread.VirtualThreadTask.run()). The execute method may be invoked at sensitive times (e.g. when unparking a thread) so care should be taken to not directly execute the task on the current thread.
      Parameters:
      scheduler - the scheduler or null for the default scheduler
      Returns:
      this builder
      Throws:
      IllegalStateException - if a thread group has been set

    • disallowThreadLocals

      Thread.Builder disallowThreadLocals()
      Disallow threads locals. If the thread attempts to set a value for a thread-local with the ThreadLocal.set(Object) method then UnsupportedOperationException is thrown.
      Returns:
      this builder
      Throws:
      IllegalStateException - if inheritThreadLocals has already been set
      See Also:
      ThreadLocal.set(Object)

    • inheritThreadLocals

      Thread.Builder inheritThreadLocals()
      Inherit threads-locals. Thread locals are inherited when the Thread is created with the build method or when the thread factory newThread method is invoked.
      Returns:
      this builder
      Throws:
      IllegalStateException - if disallowThreadLocals has already been set

    • daemon

      Thread.Builder daemon​(boolean on)
      Sets the daemon status. The daemon status of virtual threads is always true. Setting the daemon status at build time has no effect.
      Parameters:
      on - true to create daemon threads
      Returns:
      this builder

    • priority

      Thread.Builder priority​(int priority)
      Sets the thread priority. The priority of virtual threads is always Thread.NORM_PRIORITY. Setting the priority of a virtual thread at build time has no effect.
      Parameters:
      priority - priority
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the priority is less than Thread.MIN_PRIORITY or greater than Thread.MAX_PRIORITY

    • uncaughtExceptionHandler

      Thread.Builder uncaughtExceptionHandler​(Thread.UncaughtExceptionHandler ueh)
      Sets the uncaught exception handler.
      Parameters:
      ueh - uncaught exception handler
      Returns:
      this builder

    • task

      Thread.Builder task​(Runnable task)
      Sets the task for the thread to run.
      Parameters:
      task - the task to run
      Returns:
      this builder

    • build

      Thread build()
      Creates a new unstarted Thread from the current state of the builder.

      When this method creates a kernel thread then it will inherit the thread-group, priority, and daemon status of the current thread if these characteristics have not been set. The context-class-loader is inherited from the current thread.

      When this method creates a virtual thread and a scheduler has not been set then the thread will be scheduled using the default scheduler if the current thread is a kernel thread, or the scheduler for the current thread if it is a virtual thread. The context-class-loader is inherited from the current thread. The thread will have no permissions.

      Returns:
      a new unstarted Thread
      Throws:
      IllegalStateException - if the task object to run object has not been set
      SecurityException - if a thread group has been set and the current thread cannot create a thread in that thread group

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

      A ThreadFactory that creates kernel threads will inherit the thread-group, priority, and daemon status of the current thread when creating a Thread if these characteristics have not been set. The context-class-loader is inherited from the current thread when creating a Thread.

      A ThreadFactory that creates virtual threads will use the selected scheduler. If a scheduler has not been set then the ThreadFactory will select the scheduler when creating a Thread. The default scheduler will be selected if the current thread is a kernel thread. It will use the scheduler for the current thread if it is a virtual thread. The context-class-loader is inherited from the current thread. The thread will have no permissions.

      Returns:
      a thread factory to create threads

    • start

      default Thread start()
      Creates a new Thread from the current state of the builder and starts it as if by invoking the start method.

      When this method starts a kernel thread then it will inherit the thread-group, priority, and daemon status of the current thread if these characteristics have not been set. The context-class-loader is inherited from the current thread.

      When this method starts a virtual thread and a scheduler has not been set then the thread will be scheduled using the default scheduler if the current thread is a kernel thread, or the scheduler for the current thread if it is a virtual thread. The context-class-loader is inherited from the current thread. The thread will have no permissions.

      Implementation Requirements:
      The default implementation invokes build to create a Thread and then invokes its start method to start it.
      Returns:
      The started thread
      Throws:
      IllegalStateException - if the task object to run object has not been set
      SecurityException - if a thread group has been set and the current thread cannot create a thread in that thread group