Add Java 21 advice to each method of ThreadFactoryBuilder.

RELNOTES=n/a
PiperOrigin-RevId: 792835335

Author: kluever

android/guava/src/com/google/common/util/concurrent/ThreadFactoryBuilder.java

@@ -59,13 +59,25 @@ public final class ThreadFactoryBuilder {
   private @Nullable UncaughtExceptionHandler uncaughtExceptionHandler = null;
   private @Nullable ThreadFactory backingThreadFactory = null;
 
-  /** Creates a new {@link ThreadFactory} builder. */
+  /**
+   * Creates a new {@link ThreadFactory} builder.
+   *
+   * <p><b>Java 21+ users:</b> use {@link Thread#ofPlatform()} instead, translating other calls on
+   * the builder as documented on each method (except for the rarely used {@link #setThreadFactory},
+   * which does not have an equivalent).
+   */
   public ThreadFactoryBuilder() {}
 
   /**
    * Sets the naming format to use when naming threads ({@link Thread#setName}) which are created
    * with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder#name(String, long)} instead. Note that
+   * {@link #setNameFormat} accepts a thread name <i>format string</i> (e.g., {@code
+   * threadFactoryBuilder.setNameFormat("rpc-pool-%d")}), while {@code threadBuilder.name()} accepts
+   * a thread name <i>prefix</i> and initial counter value (e.g., {@code
+   * threadBuilder.name("rpc-pool-", 0)}.
+   *
    * @param nameFormat a {@link String#format(String, Object...)}-compatible format String, to which
    *     a unique integer (0, 1, etc.) will be supplied as the single parameter. This integer will
    *     be unique to the built instance of the ThreadFactory and will be assigned sequentially. For
@@ -83,6 +95,8 @@ public ThreadFactoryBuilder setNameFormat(String nameFormat) {
   /**
    * Sets daemon or not for new threads created with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder.OfPlatform#daemon(boolean)} instead.
+   *
    * @param daemon whether or not new Threads created with this ThreadFactory will be daemon threads
    * @return this for the builder pattern
    */
@@ -98,6 +112,8 @@ public ThreadFactoryBuilder setDaemon(boolean daemon) {
    * <p><b>Warning:</b> relying on the thread scheduler is <a
    * href="http://errorprone.info/bugpattern/ThreadPriorityCheck">discouraged</a>.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder.OfPlatform#priority(int)} instead.
+   *
    * @param priority the priority for new Threads created with this ThreadFactory
    * @return this for the builder pattern
    */
@@ -122,6 +138,9 @@ public ThreadFactoryBuilder setPriority(int priority) {
   /**
    * Sets the {@link UncaughtExceptionHandler} for new threads created with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link
+   * Thread.Builder#uncaughtExceptionHandler(Thread.UncaughtExceptionHandler)} instead.
+   *
    * @param uncaughtExceptionHandler the uncaught exception handler for new Threads created with
    *     this ThreadFactory
    * @return this for the builder pattern
@@ -153,6 +172,8 @@ public ThreadFactoryBuilder setThreadFactory(ThreadFactory backingThreadFactory)
    * building, it is still possible to change the options used to build the ThreadFactory and/or
    * build again. State is not shared amongst built instances.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder#factory()} instead.
+   *
    * @return the fully constructed {@link ThreadFactory}
    */
   public ThreadFactory build() {
@@ -161,6 +182,7 @@ public ThreadFactory build() {
 
   // Split out so that the anonymous ThreadFactory can't contain a reference back to the builder.
   // At least, I assume that's why. TODO(cpovirk): Check, and maybe add a test for this.
+  @SuppressWarnings("ThreadPriorityCheck") // We only propagate user requests (which we discourage).
   private static ThreadFactory doBuild(ThreadFactoryBuilder builder) {
     String nameFormat = builder.nameFormat;
     Boolean daemon = builder.daemon;

guava/src/com/google/common/util/concurrent/ThreadFactoryBuilder.java

@@ -59,13 +59,25 @@ public final class ThreadFactoryBuilder {
   private @Nullable UncaughtExceptionHandler uncaughtExceptionHandler = null;
   private @Nullable ThreadFactory backingThreadFactory = null;
 
-  /** Creates a new {@link ThreadFactory} builder. */
+  /**
+   * Creates a new {@link ThreadFactory} builder.
+   *
+   * <p><b>Java 21+ users:</b> use {@link Thread#ofPlatform()} instead, translating other calls on
+   * the builder as documented on each method (except for the rarely used {@link #setThreadFactory},
+   * which does not have an equivalent).
+   */
   public ThreadFactoryBuilder() {}
 
   /**
    * Sets the naming format to use when naming threads ({@link Thread#setName}) which are created
    * with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder#name(String, long)} instead. Note that
+   * {@link #setNameFormat} accepts a thread name <i>format string</i> (e.g., {@code
+   * threadFactoryBuilder.setNameFormat("rpc-pool-%d")}), while {@code threadBuilder.name()} accepts
+   * a thread name <i>prefix</i> and initial counter value (e.g., {@code
+   * threadBuilder.name("rpc-pool-", 0)}.
+   *
    * @param nameFormat a {@link String#format(String, Object...)}-compatible format String, to which
    *     a unique integer (0, 1, etc.) will be supplied as the single parameter. This integer will
    *     be unique to the built instance of the ThreadFactory and will be assigned sequentially. For
@@ -83,6 +95,8 @@ public ThreadFactoryBuilder setNameFormat(String nameFormat) {
   /**
    * Sets daemon or not for new threads created with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder.OfPlatform#daemon(boolean)} instead.
+   *
    * @param daemon whether or not new Threads created with this ThreadFactory will be daemon threads
    * @return this for the builder pattern
    */
@@ -98,6 +112,8 @@ public ThreadFactoryBuilder setDaemon(boolean daemon) {
    * <p><b>Warning:</b> relying on the thread scheduler is <a
    * href="http://errorprone.info/bugpattern/ThreadPriorityCheck">discouraged</a>.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder.OfPlatform#priority(int)} instead.
+   *
    * @param priority the priority for new Threads created with this ThreadFactory
    * @return this for the builder pattern
    */
@@ -122,6 +138,9 @@ public ThreadFactoryBuilder setPriority(int priority) {
   /**
    * Sets the {@link UncaughtExceptionHandler} for new threads created with this ThreadFactory.
    *
+   * <p><b>Java 21+ users:</b> use {@link
+   * Thread.Builder#uncaughtExceptionHandler(Thread.UncaughtExceptionHandler)} instead.
+   *
    * @param uncaughtExceptionHandler the uncaught exception handler for new Threads created with
    *     this ThreadFactory
    * @return this for the builder pattern
@@ -153,6 +172,8 @@ public ThreadFactoryBuilder setThreadFactory(ThreadFactory backingThreadFactory)
    * building, it is still possible to change the options used to build the ThreadFactory and/or
    * build again. State is not shared amongst built instances.
    *
+   * <p><b>Java 21+ users:</b> use {@link Thread.Builder#factory()} instead.
+   *
    * @return the fully constructed {@link ThreadFactory}
    */
   public ThreadFactory build() {
@@ -161,6 +182,7 @@ public ThreadFactory build() {
 
   // Split out so that the anonymous ThreadFactory can't contain a reference back to the builder.
   // At least, I assume that's why. TODO(cpovirk): Check, and maybe add a test for this.
+  @SuppressWarnings("ThreadPriorityCheck") // We only propagate user requests (which we discourage).
   private static ThreadFactory doBuild(ThreadFactoryBuilder builder) {
     String nameFormat = builder.nameFormat;
     Boolean daemon = builder.daemon;