1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.lang3.concurrent; 18 19 import java.lang.Thread.UncaughtExceptionHandler; 20 import java.util.Objects; 21 import java.util.concurrent.ExecutorService; 22 import java.util.concurrent.Executors; 23 import java.util.concurrent.ThreadFactory; 24 import java.util.concurrent.atomic.AtomicLong; 25 26 /** 27 * An implementation of the {@link ThreadFactory} interface that provides some 28 * configuration options for the threads it creates. 29 * <p> 30 * A {@link ThreadFactory} is used for instance by an {@link ExecutorService} to 31 * create the threads it uses for executing tasks. In many cases users do not 32 * have to care about a {@link ThreadFactory} because the default one used by an 33 * {@link ExecutorService} will do. However, if there are special requirements 34 * for the threads, a custom {@link ThreadFactory} has to be created. 35 * </p> 36 * <p> 37 * This class provides some frequently needed configuration options for the 38 * threads it creates. These are the following: 39 * </p> 40 * <ul> 41 * <li>A name pattern for the threads created by this factory can be specified. 42 * This is often useful if an application uses multiple executor services for 43 * different purposes. If the names of the threads used by these services have 44 * meaningful names, log output or exception traces can be much easier to read. 45 * Naming patterns are <em>format strings</em> as used by the {@code 46 * String.format()} method. The string can contain the place holder {@code %d} 47 * which will be replaced by the number of the current thread ({@code 48 * ThreadFactoryImpl} keeps a counter of the threads it has already created). 49 * For instance, the naming pattern {@code "My %d. worker thread"} will result 50 * in thread names like {@code "My 1. worker thread"}, {@code 51 * "My 2. worker thread"} and so on.</li> 52 * <li>A flag whether the threads created by this factory should be daemon 53 * threads. This can impact the exit behavior of the current Java application 54 * because the JVM shuts down if there are only daemon threads running.</li> 55 * <li>The priority of the thread. Here an integer value can be provided. The 56 * {@link Thread} class defines constants for valid ranges of priority 57 * values.</li> 58 * <li>The {@link UncaughtExceptionHandler} for the thread. This handler is 59 * called if an uncaught exception occurs within the thread.</li> 60 * </ul> 61 * <p> 62 * {@link BasicThreadFactory} wraps another thread factory which actually 63 * creates new threads. The configuration options are set on the threads created 64 * by the wrapped thread factory. On construction time the factory to be wrapped 65 * can be specified. If none is provided, a default {@link ThreadFactory} is 66 * used. 67 * </p> 68 * <p> 69 * Instances of {@link BasicThreadFactory} are not created directly, but the 70 * nested {@link Builder} class is used for this purpose. Using the builder only 71 * the configuration options an application is interested in need to be set. The 72 * following example shows how a {@link BasicThreadFactory} is created and 73 * installed in an {@link ExecutorService}: 74 * </p> 75 * 76 * <pre> 77 * // Create a factory that produces daemon threads with a naming pattern and 78 * // a priority 79 * BasicThreadFactory factory = new BasicThreadFactory.Builder() 80 * .namingPattern("workerthread-%d") 81 * .daemon(true) 82 * .priority(Thread.MAX_PRIORITY) 83 * .build(); 84 * // Create an executor service for single-threaded execution 85 * ExecutorService exec = Executors.newSingleThreadExecutor(factory); 86 * </pre> 87 * 88 * @since 3.0 89 */ 90 public class BasicThreadFactory implements ThreadFactory { 91 92 /** 93 * A <em>builder</em> class for creating instances of {@code 94 * BasicThreadFactory}. 95 * <p> 96 * Using this builder class instances of {@link BasicThreadFactory} can be 97 * created and initialized. The class provides methods that correspond to 98 * the configuration options supported by {@link BasicThreadFactory}. Method 99 * chaining is supported. Refer to the documentation of {@code 100 * BasicThreadFactory} for a usage example. 101 * </p> 102 */ 103 public static class Builder 104 implements org.apache.commons.lang3.builder.Builder<BasicThreadFactory> { 105 106 /** The wrapped factory. */ 107 private ThreadFactory factory; 108 109 /** The uncaught exception handler. */ 110 private Thread.UncaughtExceptionHandler exceptionHandler; 111 112 /** The naming pattern. */ 113 private String namingPattern; 114 115 /** The priority. */ 116 private Integer priority; 117 118 /** The daemon flag. */ 119 private Boolean daemon; 120 121 /** 122 * Creates a new {@link BasicThreadFactory} with all configuration 123 * options that have been specified by calling methods on this builder. 124 * After creating the factory {@link #reset()} is called. 125 * 126 * @return the new {@link BasicThreadFactory} 127 */ 128 @Override 129 public BasicThreadFactory build() { 130 final BasicThreadFactory factory = new BasicThreadFactory(this); 131 reset(); 132 return factory; 133 } 134 135 /** 136 * Sets the daemon flag for the new {@link BasicThreadFactory}. If this 137 * flag is set to <b>true</b> the new thread factory will create daemon 138 * threads. 139 * 140 * @param daemon the value of the daemon flag 141 * @return a reference to this {@link Builder} 142 */ 143 public Builder daemon(final boolean daemon) { 144 this.daemon = Boolean.valueOf(daemon); 145 return this; 146 } 147 148 /** 149 * Sets the naming pattern to be used by the new {@code 150 * BasicThreadFactory}. 151 * 152 * @param namingPattern the naming pattern (must not be <b>null</b>) 153 * @return a reference to this {@link Builder} 154 * @throws NullPointerException if the naming pattern is <b>null</b> 155 */ 156 public Builder namingPattern(final String namingPattern) { 157 this.namingPattern = Objects.requireNonNull(namingPattern, "pattern"); 158 return this; 159 } 160 161 /** 162 * Sets the priority for the threads created by the new {@code 163 * BasicThreadFactory}. 164 * 165 * @param priority the priority 166 * @return a reference to this {@link Builder} 167 */ 168 public Builder priority(final int priority) { 169 this.priority = Integer.valueOf(priority); 170 return this; 171 } 172 173 /** 174 * Resets this builder. All configuration options are set to default 175 * values. Note: If the {@link #build()} method was called, it is not 176 * necessary to call {@code reset()} explicitly because this is done 177 * automatically. 178 */ 179 public void reset() { 180 factory = null; 181 exceptionHandler = null; 182 namingPattern = null; 183 priority = null; 184 daemon = null; 185 } 186 187 /** 188 * Sets the uncaught exception handler for the threads created by the 189 * new {@link BasicThreadFactory}. 190 * 191 * @param exceptionHandler the {@link UncaughtExceptionHandler} (must not be 192 * <b>null</b>) 193 * @return a reference to this {@link Builder} 194 * @throws NullPointerException if the exception handler is <b>null</b> 195 */ 196 public Builder uncaughtExceptionHandler( 197 final Thread.UncaughtExceptionHandler exceptionHandler) { 198 this.exceptionHandler = Objects.requireNonNull(exceptionHandler, "handler"); 199 return this; 200 } 201 202 /** 203 * Sets the {@link ThreadFactory} to be wrapped by the new {@code 204 * BasicThreadFactory}. 205 * 206 * @param factory the wrapped {@link ThreadFactory} (must not be 207 * <b>null</b>) 208 * @return a reference to this {@link Builder} 209 * @throws NullPointerException if the passed in {@link ThreadFactory} 210 * is <b>null</b> 211 */ 212 public Builder wrappedFactory(final ThreadFactory factory) { 213 this.factory = Objects.requireNonNull(factory, "factory"); 214 return this; 215 } 216 } 217 218 /** A counter for the threads created by this factory. */ 219 private final AtomicLong threadCounter; 220 221 /** Stores the wrapped factory. */ 222 private final ThreadFactory wrappedFactory; 223 224 /** Stores the uncaught exception handler. */ 225 private final Thread.UncaughtExceptionHandler uncaughtExceptionHandler; 226 227 /** Stores the naming pattern for newly created threads. */ 228 private final String namingPattern; 229 230 /** Stores the priority. */ 231 private final Integer priority; 232 233 /** Stores the daemon status flag. */ 234 private final Boolean daemon; 235 236 /** 237 * Creates a new instance of {@link ThreadFactory} and configures it 238 * from the specified {@link Builder} object. 239 * 240 * @param builder the {@link Builder} object 241 */ 242 private BasicThreadFactory(final Builder builder) { 243 wrappedFactory = builder.factory != null ? builder.factory : Executors.defaultThreadFactory(); 244 namingPattern = builder.namingPattern; 245 priority = builder.priority; 246 daemon = builder.daemon; 247 uncaughtExceptionHandler = builder.exceptionHandler; 248 threadCounter = new AtomicLong(); 249 } 250 251 /** 252 * Gets the daemon flag. This flag determines whether newly created 253 * threads should be daemon threads. If <b>true</b>, this factory object 254 * calls {@code setDaemon(true)} on the newly created threads. Result can be 255 * <b>null</b> if no daemon flag was provided at creation time. 256 * 257 * @return the daemon flag 258 */ 259 public final Boolean getDaemonFlag() { 260 return daemon; 261 } 262 263 /** 264 * Gets the naming pattern for naming newly created threads. Result can 265 * be <b>null</b> if no naming pattern was provided. 266 * 267 * @return the naming pattern 268 */ 269 public final String getNamingPattern() { 270 return namingPattern; 271 } 272 273 /** 274 * Gets the priority of the threads created by this factory. Result can 275 * be <b>null</b> if no priority was specified. 276 * 277 * @return the priority for newly created threads 278 */ 279 public final Integer getPriority() { 280 return priority; 281 } 282 283 /** 284 * Gets the number of threads this factory has already created. This 285 * class maintains an internal counter that is incremented each time the 286 * {@link #newThread(Runnable)} method is invoked. 287 * 288 * @return the number of threads created by this factory 289 */ 290 public long getThreadCount() { 291 return threadCounter.get(); 292 } 293 294 /** 295 * Gets the {@link UncaughtExceptionHandler} for the threads created by 296 * this factory. Result can be <b>null</b> if no handler was provided. 297 * 298 * @return the {@link UncaughtExceptionHandler} 299 */ 300 public final Thread.UncaughtExceptionHandler getUncaughtExceptionHandler() { 301 return uncaughtExceptionHandler; 302 } 303 304 /** 305 * Gets the wrapped {@link ThreadFactory}. This factory is used for 306 * actually creating threads. This method never returns <b>null</b>. If no 307 * {@link ThreadFactory} was passed when this object was created, a default 308 * thread factory is returned. 309 * 310 * @return the wrapped {@link ThreadFactory} 311 */ 312 public final ThreadFactory getWrappedFactory() { 313 return wrappedFactory; 314 } 315 316 /** 317 * Initializes the specified thread. This method is called by 318 * {@link #newThread(Runnable)} after a new thread has been obtained from 319 * the wrapped thread factory. It initializes the thread according to the 320 * options set for this factory. 321 * 322 * @param thread the thread to be initialized 323 */ 324 private void initializeThread(final Thread thread) { 325 if (getNamingPattern() != null) { 326 final Long count = Long.valueOf(threadCounter.incrementAndGet()); 327 thread.setName(String.format(getNamingPattern(), count)); 328 } 329 if (getUncaughtExceptionHandler() != null) { 330 thread.setUncaughtExceptionHandler(getUncaughtExceptionHandler()); 331 } 332 if (getPriority() != null) { 333 thread.setPriority(getPriority().intValue()); 334 } 335 if (getDaemonFlag() != null) { 336 thread.setDaemon(getDaemonFlag().booleanValue()); 337 } 338 } 339 340 /** 341 * Creates a new thread. This implementation delegates to the wrapped 342 * factory for creating the thread. Then, on the newly created thread the 343 * corresponding configuration options are set. 344 * 345 * @param runnable the {@link Runnable} to be executed by the new thread 346 * @return the newly created thread 347 */ 348 @Override 349 public Thread newThread(final Runnable runnable) { 350 final Thread thread = getWrappedFactory().newThread(runnable); 351 initializeThread(thread); 352 return thread; 353 } 354 }