001/*
002 * Copyright (C) 2010 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.google.common.util.concurrent;
018
019import static com.google.common.base.Preconditions.checkArgument;
020import static com.google.common.base.Preconditions.checkNotNull;
021
022import java.lang.Thread.UncaughtExceptionHandler;
023import java.util.concurrent.Executors;
024import java.util.concurrent.ThreadFactory;
025import java.util.concurrent.atomic.AtomicLong;
026
027/**
028 * A ThreadFactory builder, providing any combination of these features:
029 * <ul>
030 * <li> whether threads should be marked as {@linkplain Thread#setDaemon daemon}
031 * threads
032 * <li> a {@linkplain ThreadFactoryBuilder#setNameFormat naming format}
033 * <li> a {@linkplain Thread#setPriority thread priority}
034 * <li> an {@linkplain Thread#setUncaughtExceptionHandler uncaught exception
035 * handler}
036 * <li> a {@linkplain ThreadFactory#newThread backing thread factory}
037 * </ul>
038 * If no backing thread factory is provided, a default backing thread factory is
039 * used as if by calling {@code setThreadFactory(}{@link
040 * Executors#defaultThreadFactory()}{@code )}.
041 *
042 * @author Kurt Alfred Kluever
043 * @since 4.0
044 */
045public final class ThreadFactoryBuilder {
046  private String nameFormat = null;
047  private Boolean daemon = null;
048  private Integer priority = null;
049  private UncaughtExceptionHandler uncaughtExceptionHandler = null;
050  private ThreadFactory backingThreadFactory = null;
051
052  /**
053   * Creates a new {@link ThreadFactory} builder.
054   */
055  public ThreadFactoryBuilder() {}
056
057  /**
058   * Sets the naming format to use when naming threads ({@link Thread#setName})
059   * which are created with this ThreadFactory.
060   *
061   * @param nameFormat a {@link String#format(String, Object...)}-compatible
062   *     format String, to which a unique integer (0, 1, etc.) will be supplied
063   *     as the single parameter. This integer will be unique to the built
064   *     instance of the ThreadFactory and will be assigned sequentially. For
065   *     example, {@code "rpc-pool-%d"} will generate thread names like
066   *     {@code "rpc-pool-0"}, {@code "rpc-pool-1"}, {@code "rpc-pool-2"}, etc.
067   * @return this for the builder pattern
068   */
069  @SuppressWarnings("ReturnValueIgnored")
070  public ThreadFactoryBuilder setNameFormat(String nameFormat) {
071    String.format(nameFormat, 0); // fail fast if the format is bad or null
072    this.nameFormat = nameFormat;
073    return this;
074  }
075
076  /**
077   * Sets daemon or not for new threads created with this ThreadFactory.
078   *
079   * @param daemon whether or not new Threads created with this ThreadFactory
080   *     will be daemon threads
081   * @return this for the builder pattern
082   */
083  public ThreadFactoryBuilder setDaemon(boolean daemon) {
084    this.daemon = daemon;
085    return this;
086  }
087
088  /**
089   * Sets the priority for new threads created with this ThreadFactory.
090   *
091   * @param priority the priority for new Threads created with this
092   *     ThreadFactory
093   * @return this for the builder pattern
094   */
095  public ThreadFactoryBuilder setPriority(int priority) {
096    // Thread#setPriority() already checks for validity. These error messages
097    // are nicer though and will fail-fast.
098    checkArgument(priority >= Thread.MIN_PRIORITY,
099        "Thread priority (%s) must be >= %s", priority, Thread.MIN_PRIORITY);
100    checkArgument(priority <= Thread.MAX_PRIORITY,
101        "Thread priority (%s) must be <= %s", priority, Thread.MAX_PRIORITY);
102    this.priority = priority;
103    return this;
104  }
105
106  /**
107   * Sets the {@link UncaughtExceptionHandler} for new threads created with this
108   * ThreadFactory.
109   *
110   * @param uncaughtExceptionHandler the uncaught exception handler for new
111   *     Threads created with this ThreadFactory
112   * @return this for the builder pattern
113   */
114  public ThreadFactoryBuilder setUncaughtExceptionHandler(
115      UncaughtExceptionHandler uncaughtExceptionHandler) {
116    this.uncaughtExceptionHandler = checkNotNull(uncaughtExceptionHandler);
117    return this;
118  }
119
120  /**
121   * Sets the backing {@link ThreadFactory} for new threads created with this
122   * ThreadFactory. Threads will be created by invoking #newThread(Runnable) on
123   * this backing {@link ThreadFactory}.
124   *
125   * @param backingThreadFactory the backing {@link ThreadFactory} which will
126   *     be delegated to during thread creation.
127   * @return this for the builder pattern
128   *
129   * @see MoreExecutors
130   */
131  public ThreadFactoryBuilder setThreadFactory(
132      ThreadFactory backingThreadFactory) {
133    this.backingThreadFactory = checkNotNull(backingThreadFactory);
134    return this;
135  }
136
137  /**
138   * Returns a new thread factory using the options supplied during the building
139   * process. After building, it is still possible to change the options used to
140   * build the ThreadFactory and/or build again. State is not shared amongst
141   * built instances.
142   *
143   * @return the fully constructed {@link ThreadFactory}
144   */
145  public ThreadFactory build() {
146    return build(this);
147  }
148
149  private static ThreadFactory build(ThreadFactoryBuilder builder) {
150    final String nameFormat = builder.nameFormat;
151    final Boolean daemon = builder.daemon;
152    final Integer priority = builder.priority;
153    final UncaughtExceptionHandler uncaughtExceptionHandler =
154        builder.uncaughtExceptionHandler;
155    final ThreadFactory backingThreadFactory =
156        (builder.backingThreadFactory != null)
157        ? builder.backingThreadFactory
158        : Executors.defaultThreadFactory();
159    final AtomicLong count = (nameFormat != null) ? new AtomicLong(0) : null;
160    return new ThreadFactory() {
161      @Override public Thread newThread(Runnable runnable) {
162        Thread thread = backingThreadFactory.newThread(runnable);
163        if (nameFormat != null) {
164          thread.setName(String.format(nameFormat, count.getAndIncrement()));
165        }
166        if (daemon != null) {
167          thread.setDaemon(daemon);
168        }
169        if (priority != null) {
170          thread.setPriority(priority);
171        }
172        if (uncaughtExceptionHandler != null) {
173          thread.setUncaughtExceptionHandler(uncaughtExceptionHandler);
174        }
175        return thread;
176      }
177    };
178  }
179}