23 * questions. |
23 * questions. |
24 */ |
24 */ |
25 |
25 |
26 package java.lang; |
26 package java.lang; |
27 import java.lang.ref.*; |
27 import java.lang.ref.*; |
|
28 import java.util.Objects; |
28 import java.util.concurrent.atomic.AtomicInteger; |
29 import java.util.concurrent.atomic.AtomicInteger; |
|
30 import java.util.function.Supplier; |
29 |
31 |
30 /** |
32 /** |
31 * This class provides thread-local variables. These variables differ from |
33 * This class provides thread-local variables. These variables differ from |
32 * their normal counterparts in that each thread that accesses one (via its |
34 * their normal counterparts in that each thread that accesses one (via its |
33 * <tt>get</tt> or <tt>set</tt> method) has its own, independently initialized |
35 * {@code get} or {@code set} method) has its own, independently initialized |
34 * copy of the variable. <tt>ThreadLocal</tt> instances are typically private |
36 * copy of the variable. {@code ThreadLocal} instances are typically private |
35 * static fields in classes that wish to associate state with a thread (e.g., |
37 * static fields in classes that wish to associate state with a thread (e.g., |
36 * a user ID or Transaction ID). |
38 * a user ID or Transaction ID). |
37 * |
39 * |
38 * <p>For example, the class below generates unique identifiers local to each |
40 * <p>For example, the class below generates unique identifiers local to each |
39 * thread. |
41 * thread. |
40 * A thread's id is assigned the first time it invokes <tt>ThreadId.get()</tt> |
42 * A thread's id is assigned the first time it invokes {@code ThreadId.get()} |
41 * and remains unchanged on subsequent calls. |
43 * and remains unchanged on subsequent calls. |
42 * <pre> |
44 * <pre> |
43 * import java.util.concurrent.atomic.AtomicInteger; |
45 * import java.util.concurrent.atomic.AtomicInteger; |
44 * |
46 * |
45 * public class ThreadId { |
47 * public class ThreadId { |
59 * return threadId.get(); |
61 * return threadId.get(); |
60 * } |
62 * } |
61 * } |
63 * } |
62 * </pre> |
64 * </pre> |
63 * <p>Each thread holds an implicit reference to its copy of a thread-local |
65 * <p>Each thread holds an implicit reference to its copy of a thread-local |
64 * variable as long as the thread is alive and the <tt>ThreadLocal</tt> |
66 * variable as long as the thread is alive and the {@code ThreadLocal} |
65 * instance is accessible; after a thread goes away, all of its copies of |
67 * instance is accessible; after a thread goes away, all of its copies of |
66 * thread-local instances are subject to garbage collection (unless other |
68 * thread-local instances are subject to garbage collection (unless other |
67 * references to these copies exist). |
69 * references to these copies exist). |
68 * |
70 * |
69 * @author Josh Bloch and Doug Lea |
71 * @author Josh Bloch and Doug Lea |
106 /** |
108 /** |
107 * Returns the current thread's "initial value" for this |
109 * Returns the current thread's "initial value" for this |
108 * thread-local variable. This method will be invoked the first |
110 * thread-local variable. This method will be invoked the first |
109 * time a thread accesses the variable with the {@link #get} |
111 * time a thread accesses the variable with the {@link #get} |
110 * method, unless the thread previously invoked the {@link #set} |
112 * method, unless the thread previously invoked the {@link #set} |
111 * method, in which case the <tt>initialValue</tt> method will not |
113 * method, in which case the {@code initialValue} method will not |
112 * be invoked for the thread. Normally, this method is invoked at |
114 * be invoked for the thread. Normally, this method is invoked at |
113 * most once per thread, but it may be invoked again in case of |
115 * most once per thread, but it may be invoked again in case of |
114 * subsequent invocations of {@link #remove} followed by {@link #get}. |
116 * subsequent invocations of {@link #remove} followed by {@link #get}. |
115 * |
117 * |
116 * <p>This implementation simply returns <tt>null</tt>; if the |
118 * <p>This implementation simply returns {@code null}; if the |
117 * programmer desires thread-local variables to have an initial |
119 * programmer desires thread-local variables to have an initial |
118 * value other than <tt>null</tt>, <tt>ThreadLocal</tt> must be |
120 * value other than {@code null}, {@code ThreadLocal} must be |
119 * subclassed, and this method overridden. Typically, an |
121 * subclassed, and this method overridden. Typically, an |
120 * anonymous inner class will be used. |
122 * anonymous inner class will be used. |
121 * |
123 * |
122 * @return the initial value for this thread-local |
124 * @return the initial value for this thread-local |
123 */ |
125 */ |
124 protected T initialValue() { |
126 protected T initialValue() { |
125 return null; |
127 return null; |
126 } |
128 } |
127 |
129 |
128 /** |
130 /** |
|
131 * Creates a thread local variable. The initial value of the variable is |
|
132 * determined by invoking the {@code get} method on the {@code Supplier}. |
|
133 * |
|
134 * @param supplier the supplier to be used to determine the initial value |
|
135 * @return a new thread local variable |
|
136 * @throws NullPointerException if the specified supplier is null |
|
137 * @since 1.8 |
|
138 */ |
|
139 public static <T> ThreadLocal<T> withInitial(Supplier<? extends T> supplier) { |
|
140 return new SuppliedThreadLocal<>(supplier); |
|
141 } |
|
142 |
|
143 /** |
129 * Creates a thread local variable. |
144 * Creates a thread local variable. |
|
145 * @see #withInitial(java.util.function.Supplier) |
130 */ |
146 */ |
131 public ThreadLocal() { |
147 public ThreadLocal() { |
132 } |
148 } |
133 |
149 |
134 /** |
150 /** |
193 * variable. If this thread-local variable is subsequently |
209 * variable. If this thread-local variable is subsequently |
194 * {@linkplain #get read} by the current thread, its value will be |
210 * {@linkplain #get read} by the current thread, its value will be |
195 * reinitialized by invoking its {@link #initialValue} method, |
211 * reinitialized by invoking its {@link #initialValue} method, |
196 * unless its value is {@linkplain #set set} by the current thread |
212 * unless its value is {@linkplain #set set} by the current thread |
197 * in the interim. This may result in multiple invocations of the |
213 * in the interim. This may result in multiple invocations of the |
198 * <tt>initialValue</tt> method in the current thread. |
214 * {@code initialValue} method in the current thread. |
199 * |
215 * |
200 * @since 1.5 |
216 * @since 1.5 |
201 */ |
217 */ |
202 public void remove() { |
218 public void remove() { |
203 ThreadLocalMap m = getMap(Thread.currentThread()); |
219 ThreadLocalMap m = getMap(Thread.currentThread()); |
246 * This technique is preferable to the alternative of embedding |
262 * This technique is preferable to the alternative of embedding |
247 * instanceof tests in methods. |
263 * instanceof tests in methods. |
248 */ |
264 */ |
249 T childValue(T parentValue) { |
265 T childValue(T parentValue) { |
250 throw new UnsupportedOperationException(); |
266 throw new UnsupportedOperationException(); |
|
267 } |
|
268 |
|
269 /** |
|
270 * An extension of ThreadLocal that obtains its initial value from |
|
271 * the specified {@code Supplier}. |
|
272 */ |
|
273 static final class SuppliedThreadLocal<T> extends ThreadLocal<T> { |
|
274 |
|
275 private final Supplier<? extends T> supplier; |
|
276 |
|
277 SuppliedThreadLocal(Supplier<? extends T> supplier) { |
|
278 this.supplier = Objects.requireNonNull(supplier); |
|
279 } |
|
280 |
|
281 @Override |
|
282 protected T initialValue() { |
|
283 return supplier.get(); |
|
284 } |
251 } |
285 } |
252 |
286 |
253 /** |
287 /** |
254 * ThreadLocalMap is a customized hash map suitable only for |
288 * ThreadLocalMap is a customized hash map suitable only for |
255 * maintaining thread local values. No operations are exported |
289 * maintaining thread local values. No operations are exported |
597 * garbage but would cause some insertions to take O(n) time. |
631 * garbage but would cause some insertions to take O(n) time. |
598 * |
632 * |
599 * @param i a position known NOT to hold a stale entry. The |
633 * @param i a position known NOT to hold a stale entry. The |
600 * scan starts at the element after i. |
634 * scan starts at the element after i. |
601 * |
635 * |
602 * @param n scan control: <tt>log2(n)</tt> cells are scanned, |
636 * @param n scan control: {@code log2(n)} cells are scanned, |
603 * unless a stale entry is found, in which case |
637 * unless a stale entry is found, in which case |
604 * <tt>log2(table.length)-1</tt> additional cells are scanned. |
638 * {@code log2(table.length)-1} additional cells are scanned. |
605 * When called from insertions, this parameter is the number |
639 * When called from insertions, this parameter is the number |
606 * of elements, but when from replaceStaleEntry, it is the |
640 * of elements, but when from replaceStaleEntry, it is the |
607 * table length. (Note: all this could be changed to be either |
641 * table length. (Note: all this could be changed to be either |
608 * more or less aggressive by weighting n instead of just |
642 * more or less aggressive by weighting n instead of just |
609 * using straight log n. But this version is simple, fast, and |
643 * using straight log n. But this version is simple, fast, and |