W3cubDocs

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:

See Also:

Nested Class Summary

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

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

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/Thread.Builder.html