ThreadLocal源码阅读

  1 package java.lang;
  2 
  3 import java.lang.ref.WeakReference;
  4 import java.util.Objects;
  5 import java.util.concurrent.atomic.AtomicInteger;
  6 import java.util.function.Supplier;
  7 
  8 /**
  9  * This class provides thread-local variables.  These variables differ from
 10  * their normal counterparts in that each thread that accesses one (via its
 11  * {@code get} or {@code set} method) has its own, independently initialized
 12  * copy of the variable.  {@code ThreadLocal} instances are typically private
 13  * static fields in classes that wish to associate state with a thread (e.g.,
 14  * a user ID or Transaction ID).
 15  * 本类提供线程局部变量。这些变量和普通变量不同，每一个线程访问（通过get和set方法）
 16  * 的变量都是属于线程的独立初始化的一个线程局部变量的副本。线程局部变量通常是类中希望
 17  * 将状态与线程关联的私有静态域（如用户ID和事务ID）。
 18  *
 19  * 
For example, the class below generates unique identifiers local to each
 20  * thread.
 21  * 例如，下面的类生成每个线程本地的唯一标识符。
 22  * A thread's id is assigned the first time it invokes {@code ThreadId.get()}
 23  * and remains unchanged on subsequent calls.
 24  * 一个线程的Id在该线程首次调用get方法时生成，且在后续通话中保持不变。
 25  * 
 26  * import java.util.concurrent.atomic.AtomicInteger;
 27  *
 28  * public class ThreadId {
 29  *     // Atomic integer containing the next thread ID to be assigned
 30  *     private static final AtomicInteger nextId = new AtomicInteger(0);
 31  *
 32  *     // Thread local variable containing each thread's ID
 33  *     private static final ThreadLocal threadId =
 34  *         new ThreadLocal() {
 35  *             @Override
 36  *             protected Integer initialValue() {
 37  *                 return nextId.getAndIncrement();
 38  *         }
 39  *     };
 40  *
 41  *     // Returns the current thread's unique ID, assigning it if necessary
 42  *     public static int get() {
 43  *         return threadId.get();
 44  *     }
 45  * }
 46  * 
 47  * 
Each thread holds an implicit reference to its copy of a thread-local
 48  * variable as long as the thread is alive and the {@code ThreadLocal}
 49  * instance is accessible; after a thread goes away, all of its copies of
 50  * thread-local instances are subject to garbage collection (unless other
 51  * references to these copies exist).
 52  * 只要线程还活着，且ThreadLocal实例能够被访问，每个线程均保留其线程局部变量
 53  * 副本的隐式引用；线程死后它的所有线程局部变量副本被垃圾回收器回收（除非存在
 54  * 对这些线程局部变量副本的其他应用）
 55  *
 56  * @author Josh Bloch and Doug Lea
 57  * @since 1.2
 58 */
 59 public class ThreadLocal {
 60 /**
 61  * ThreadLocals rely on per-thread linear-probe hash maps attached
 62  * to each thread (Thread.threadLocals and inheritableThreadLocals).
 63  * ThreadLocal的实例依赖于每个线程的线性探针哈希图附加到每个线程。
 64  * The ThreadLocal objects act as keys,searched via threadLocalHashCode.
 65  * ThreadLocal对象充当键，通过threadLocalHashCode搜索。
 66  * This is a custom hash code
 67  * (useful only within ThreadLocalMaps) that eliminates collisions
 68  * in the common case where consecutively constructed ThreadLocals
 69  * are used by the same threads, while remaining well-behaved in
 70  * less common cases.
 71  * 这是一个自定义哈希码（仅在ThreadLocalMaps中有用），在相同的线程使用连续构造
 72  * 的ThreadLocals的常见情况下，它消除了冲突，而在不太常见的情况下，它们表现良好。
 73 */
 74 private final int threadLocalHashCode = nextHashCode();
 75
 76 /**
 77  * The next hash code to be given out. Updated atomically. Starts at
 78  * zero.
 79  * 下一次给出的哈希码，该值的自动更新不能被中断（原子性），值从0开始累加。
 80 */
 81 private static AtomicInteger nextHashCode =
 82 new AtomicInteger();
 83
 84 /**
 85  * The difference between successively generated hash codes - turns
 86  * implicit sequential thread-local IDs into near-optimally spread
 87  * multiplicative hash values for power-of-two-sized tables.
 88  * 连续生成的哈希码间的差值，
 89 */
 90 private static final int HASH_INCREMENT = 0x61c88647;
 91
 92 /**
 93  * Returns the next hash code.
 94  * 返回下一个哈希码
 95 */
 96 private static int nextHashCode() {
 97 return nextHashCode.getAndAdd(HASH_INCREMENT);
 98  }
 99
100 /**
101  * Returns the current thread's "initial value" for this
102  * thread-local variable. This method will be invoked the first
103  * time a thread accesses the variable with the {@link #get}
104  * method, unless the thread previously invoked the {@link #set}
105  * method, in which case the {@code initialValue} method will not
106  * be invoked for the thread. Normally, this method is invoked at
107  * most once per thread, but it may be invoked again in case of
108  * subsequent invocations of {@link #remove} followed by {@link #get}.
109  * 翻译：
110  * 返回当前线程持有的线程局部变量副本的初始值。线程在第一次通过get方法访问局部
111  * 变量前如果没有调用过set方法为局部变量设置值，本函数就会被调用。通常每个线程
112  * 最多会调用一次本方法，但是如果在之后依次调用了remove和get方法，它可能会再次被调用。
113  *
114  * 
This implementation simply returns {@code null}; if the
115  * programmer desires thread-local variables to have an initial
116  * value other than {@code null}, {@code ThreadLocal} must be
117  * subclassed, and this method overridden. Typically, an
118  * anonymous inner class will be used.
119  * 本实现仅返回null，如果开发者希望线程的局部变量具体其他初始值，只能通过声明子类并
120  * 重写本方法。通常，将使用匿名内部类。（下面就有一个内部类）
121  *
122  * @return the initial value for this thread-local
123 */
124 protected T initialValue() {
125 return null;
126  }
127
128 /**
129  * Creates a thread local variable. The initial value of the variable is
130  * determined by invoking the {@code get} method on the {@code Supplier}.
131  * 创建一个线程局部变量的副本，变量的初始值是通过调用Supplier上的get方法确定的。
132  * （Supplier是一个函数式接口）
133  *
134  * @param  the type of the thread local's value
135  * @param supplier the supplier to be used to determine the initial value
136  * @return a new thread local variable
137  * @throws NullPointerException if the specified supplier is null
138  * @since 1.8
139 */
140 public static  ThreadLocal withInitial(Supplierextends S> supplier) {
141 return new SuppliedThreadLocal<>(supplier);
142  }
143
144 /**
145  * 构造函数
146  * Creates a thread local variable.
147  *
148  * @see #withInitial(java.util.function.Supplier)
149 */
150 public ThreadLocal() {
151  }
152
153 /**
154  * Returns the value in the current thread's copy of this
155  * thread-local variable. If the variable has no value for the
156  * current thread, it is first initialized to the value returned
157  * by an invocation of the {@link #initialValue} method.
158  * 译：
159  * 返回当前线程持有的线程局部变量副本的值。如果该变量还没赋值，
160  * 则先使用initialValue方法为其赋予初始值。
161  *
162  * @return the current thread's value of this thread-local
163 */
164 public T get() {
165 //1、确定当前线程
166 Thread t = Thread.currentThread();
167 //2、
168 ThreadLocalMap map = getMap(t);
169 if (map != null) {
170 ThreadLocalMap.Entry e = map.getEntry(this);
171 if (e != null) {
172 @SuppressWarnings("unchecked")
173 T result = (T) e.value;
174 return result;
175  }
176  }
177 return setInitialValue();
178  }
179
180 /**
181  * Variant of set() to establish initialValue. Used instead
182  * of set() in case user has overridden the set() method.
183  * 译：
184  * set方法的变体，用于设置初始值。如果用户已覆盖set（）方法，
185  * 请使用它代替set（）。
186  *
187  * @return the initial value
188 */
189 private T setInitialValue() {
190 T value = initialValue();
191 Thread t = Thread.currentThread();
192 ThreadLocalMap map = getMap(t);
193 if (map != null)
194 map.set(this, value);
195 else
196  createMap(t, value);
197 return value;
198  }
199
200 /**
201  * Sets the current thread's copy of this thread-local variable
202  * to the specified value. Most subclasses will have no need to
203  * override this method, relying solely on the {@link #initialValue}
204  * method to set the values of thread-locals.
205  * 译：
206  * 设置当前线程持有的线程局部变量副本的值为指定值。大部分子类不需要重写本
207  * 方法，仅依靠initialValue方法来设置值。
208  *
209  * @param value the value to be stored in the current thread's copy of
210  * this thread-local.
211 */
212 public void set(T value) {
213 Thread t = Thread.currentThread();
214 ThreadLocalMap map = getMap(t);
215 if (map != null)
216 map.set(this, value);
217 else
218  createMap(t, value);
219  }
220
221 /**
222  * Removes the current thread's value for this thread-local
223  * variable. If this thread-local variable is subsequently
224  * {@linkplain #get read} by the current thread, its value will be
225  * reinitialized by invoking its {@link #initialValue} method,
226  * unless its value is {@linkplain #set set} by the current thread
227  * in the interim. This may result in multiple invocations of the
228  * {@code initialValue} method in the current thread.
229  * 译：
230  * 移除单前线程持有的线程本地变量的值。如果随后马上又通过get方法试图获取
231  * 这个线程本地变量的值，这个变量的值会再次通过调用initialValue方法确定，
232  * 除非在调用get方法前通过set方法设置了值就不会。这可能会导致initialValue
233  * 方法被当前线程多次调用。
234  *
235  * @since 1.5
236 */
237 public void remove() {
238 ThreadLocalMap m = getMap(Thread.currentThread());
239 if (m != null)
240 m.remove(this);
241  }
242
243 /**
244  * Get the map associated with a ThreadLocal. Overridden in
245  * InheritableThreadLocal.
246  *
247  * @param t the current thread
248  * @return the map
249 */
250  ThreadLocalMap getMap(Thread t) {
251 return t.threadLocals;
252  }
253
254 /**
255  * Create the map associated with a ThreadLocal. Overridden in
256  * InheritableThreadLocal.
257  *
258  * @param t the current thread
259  * @param firstValue value for the initial entry of the map
260 */
261 void createMap(Thread t, T firstValue) {
262 t.threadLocals = new ThreadLocalMap(this, firstValue);
263  }
264
265 /**
266  * Factory method to create map of inherited thread locals.
267  * Designed to be called only from Thread constructor.
268  *
269  * @param parentMap the map associated with parent thread
270  * @return a map containing the parent's inheritable bindings
271 */
272 static ThreadLocalMap createInheritedMap(ThreadLocalMap parentMap) {
273 return new ThreadLocalMap(parentMap);
274  }
275
276 /**
277  * Method childValue is visibly defined in subclass
278  * InheritableThreadLocal, but is internally defined here for the
279  * sake of providing createInheritedMap factory method without
280  * needing to subclass the map class in InheritableThreadLocal.
281  * This technique is preferable to the alternative of embedding
282  * instanceof tests in methods.
283 */
284  T childValue(T parentValue) {
285 throw new UnsupportedOperationException();
286  }
287
288 /**
289  * An extension of ThreadLocal that obtains its initial value from
290  * the specified {@code Supplier}.
291  * SuppliedThreadLocal类拓展了ThreadLocal类，该类重写了initialValue函数，
292  * 用于从指定的Supplier获取初始值。
293 */
294 static final class SuppliedThreadLocal extends ThreadLocal {
295
296 /**
297  * Supplier是一个函数式接口
298 */
299 private final Supplierextends T> supplier;
300
301 /**
302  * 构造函数
303  *
304  * @param supplier - 一个函数式接口，用来返回线程本地变量的初始值
305 */
306 SuppliedThreadLocal(Supplierextends T> supplier) {
307 /**
308  * public static  T requireNonNull(T obj) {
309  * if (obj == null)
310  * throw new NullPointerException();
311  * return obj;
312  * }
313 */
314 this.supplier = Objects.requireNonNull(supplier);
315  }
316
317 /**
318  * 这里很关键，需要去看看Supplier接口的源码。
319 */
320  @Override
321 protected T initialValue() {
322 return supplier.get();
323  }
324  }
325
326 /**
327  * ThreadLocalMap is a customized hash map suitable only for
328  * maintaining thread local values. No operations are exported
329  * outside of the ThreadLocal class. The class is package private to
330  * allow declaration of fields in class Thread. To help deal with
331  * very large and long-lived usages, the hash table entries use
332  * WeakReferences for keys. However, since reference queues are not
333  * used, stale entries are guaranteed to be removed only when
334  * the table starts running out of space.
335  * 译：
336  * ThreadLocalMap是自定义的HashMap，仅适用于维护线程局部变量的值。
337  * 没有操作导出到ThreadLocal类之外。这个类是包私有的，用于Thread类
338  * 域声明。为了处理存储空间消耗大，使用时间长的使用情况，这个HashTable
339  * 使用WeakReferences（弱引用）作为键。但是，由于未使用参考队列，因此
340  * 仅在表开始空间不足时，才保证删除过时的条目。
341 */
342 static class ThreadLocalMap {
343
344 /**
345  * The entries in this hash map extend WeakReference, using
346  * its main ref field as the key (which is always a
347  * ThreadLocal object). Note that null keys (i.e. entry.get()
348  * == null) mean that the key is no longer referenced, so the
349  * entry can be expunged from table. Such entries are referred to
350  * as "stale entries" in the code that follows.
351  * 译：
352  * 该哈希表中的条目是WeakReference子类的对象，以其主域作为键（大多数情
353  * 况下是一个ThreadLocal对象）。需要注意，当以null作为键时，意味着这个
354  * 键已经不再被引用，因此这个键所在的条目能被表移除。这样的条目我们在下文
355  * 中称为“过时的条目”
356 */
357 static class Entry extends WeakReference> {
358 /**
359  * The value associated with this ThreadLocal.
360  * 与ThreadLocal相关联的值
361 */
362  Object value;
363
364 /**
365  * @param k - 以线程作为键
366  * @param v - 线程持有的threal-local变量副本的值
367 */
368 Entry(ThreadLocal k, Object v) {
369 super(k);
370 value = v;
371  }
372  }
373
374 /**
375  * The initial capacity -- MUST be a power of two.
376  * 初始容量——必须是2的幂
377 */
378 private static final int INITIAL_CAPACITY = 16;
379
380 /**
381  * The table, resized as necessary.
382  * table.length MUST always be a power of two.
383  * 译：
384  * 表在必要的时候会扩容，表的大小必须是2的幂
385 */
386 private Entry[] table;
387
388 /**
389  * The number of entries in the table.
390  * 表中条目（键值对）的数量
391 */
392 private int size = 0;
393
394 /**
395  * the next size value at which to resize.
396  * 下一次调整表的大小时要增加的值
397 */
398 private int threshold; // Default to 0
399
400 /**
401  * Set the resize threshold to maintain at worst a 2/3 load factor.
402  * 从这里可以看出，每次扩容，容量增加2/3。
403 */
404 private void setThreshold(int len) {
405 threshold = len * 2 / 3;
406  }
407
408 /**
409  * Increment i modulo len.
410 */
411 private static int nextIndex(int i, int len) {
412 return ((i + 1 < len) ? i + 1 : 0);
413  }
414
415 /**
416  * Decrement i modulo len.
417 */
418 private static int prevIndex(int i, int len) {
419 return ((i - 1 >= 0) ? i - 1 : len - 1);
420  }
421
422 /**
423  * Construct a new map initially containing (firstKey, firstValue).
424  * ThreadLocalMaps are constructed lazily, so we only create
425  * one when we have at least one entry to put in it.
426  * 译：
427  * 构造一个最初包含以下内容的新Map。ThreadLocalMaps是延迟创建的，所以
428  * 只有当至少要添加一条条目时才创建一个。
429 */
430 ThreadLocalMap(ThreadLocal firstKey, Object firstValue) {
431 table = new Entry[INITIAL_CAPACITY];
432 int i = firstKey.threadLocalHashCode & (INITIAL_CAPACITY - 1);
433 table[i] = new Entry(firstKey, firstValue);
434 size = 1;
435  setThreshold(INITIAL_CAPACITY);
436  }
437
438 /**
439  * Construct a new map including all Inheritable ThreadLocals
440  * from given parent map. Called only by createInheritedMap.
441  *
442  * @param parentMap the map associated with parent thread.
443 */
444 private ThreadLocalMap(ThreadLocalMap parentMap) {
445 Entry[] parentTable = parentMap.table;
446 int len = parentTable.length;
447  setThreshold(len);
448 table = new Entry[len];
449
450 for (int j = 0; j < len; j++) {
451 Entry e = parentTable[j];
452 if (e != null) {
453 @SuppressWarnings("unchecked")
454 ThreadLocal