18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
29 * file:
30 *
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
34 */
35
36 package java.util.concurrent.locks;
37
38 import jdk.internal.misc.Unsafe;
39
40 /**
41 * Basic thread blocking primitives for creating locks and other
42 * synchronization classes.
43 *
44 * <p>This class associates, with each thread that uses it, a permit
45 * (in the sense of the {@link java.util.concurrent.Semaphore
46 * Semaphore} class). A call to {@code park} will return immediately
47 * if the permit is available, consuming it in the process; otherwise
48 * it <em>may</em> block. A call to {@code unpark} makes the permit
49 * available, if it was not already available. (Unlike with Semaphores
50 * though, permits do not accumulate. There is at most one.)
51 * Reliable usage requires the use of volatile (or atomic) variables
52 * to control when to park or unpark. Orderings of calls to these
53 * methods are maintained with respect to volatile variable accesses,
54 * but not necessarily non-volatile variable accesses.
55 *
56 * <p>Methods {@code park} and {@code unpark} provide efficient
57 * means of blocking and unblocking threads that do not encounter the
139 public class LockSupport {
140 private LockSupport() {} // Cannot be instantiated.
141
142 private static void setBlocker(Thread t, Object arg) {
143 // Even though volatile, hotspot doesn't need a write barrier here.
144 U.putObject(t, PARKBLOCKER, arg);
145 }
146
147 /**
148 * Makes available the permit for the given thread, if it
149 * was not already available. If the thread was blocked on
150 * {@code park} then it will unblock. Otherwise, its next call
151 * to {@code park} is guaranteed not to block. This operation
152 * is not guaranteed to have any effect at all if the given
153 * thread has not been started.
154 *
155 * @param thread the thread to unpark, or {@code null}, in which case
156 * this operation has no effect
157 */
158 public static void unpark(Thread thread) {
159 if (thread != null)
160 U.unpark(thread);
161 }
162
163 /**
164 * Disables the current thread for thread scheduling purposes unless the
165 * permit is available.
166 *
167 * <p>If the permit is available then it is consumed and the call returns
168 * immediately; otherwise
169 * the current thread becomes disabled for thread scheduling
170 * purposes and lies dormant until one of three things happens:
171 *
172 * <ul>
173 * <li>Some other thread invokes {@link #unpark unpark} with the
174 * current thread as the target; or
175 *
176 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
177 * the current thread; or
178 *
179 * <li>The call spuriously (that is, for no reason) returns.
180 * </ul>
181 *
182 * <p>This method does <em>not</em> report which of these caused the
183 * method to return. Callers should re-check the conditions which caused
184 * the thread to park in the first place. Callers may also determine,
185 * for example, the interrupt status of the thread upon return.
186 *
187 * @param blocker the synchronization object responsible for this
188 * thread parking
189 * @since 1.6
190 */
191 public static void park(Object blocker) {
192 Thread t = Thread.currentThread();
193 setBlocker(t, blocker);
194 U.park(false, 0L);
195 setBlocker(t, null);
196 }
197
198 /**
199 * Disables the current thread for thread scheduling purposes, for up to
200 * the specified waiting time, unless the permit is available.
201 *
202 * <p>If the permit is available then it is consumed and the call
203 * returns immediately; otherwise the current thread becomes disabled
204 * for thread scheduling purposes and lies dormant until one of four
205 * things happens:
206 *
207 * <ul>
208 * <li>Some other thread invokes {@link #unpark unpark} with the
209 * current thread as the target; or
210 *
211 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
212 * the current thread; or
213 *
214 * <li>The specified waiting time elapses; or
215 *
216 * <li>The call spuriously (that is, for no reason) returns.
217 * </ul>
218 *
219 * <p>This method does <em>not</em> report which of these caused the
220 * method to return. Callers should re-check the conditions which caused
221 * the thread to park in the first place. Callers may also determine,
222 * for example, the interrupt status of the thread, or the elapsed time
223 * upon return.
224 *
225 * @param blocker the synchronization object responsible for this
226 * thread parking
227 * @param nanos the maximum number of nanoseconds to wait
228 * @since 1.6
229 */
230 public static void parkNanos(Object blocker, long nanos) {
231 if (nanos > 0) {
232 Thread t = Thread.currentThread();
233 setBlocker(t, blocker);
234 U.park(false, nanos);
235 setBlocker(t, null);
236 }
237 }
238
239 /**
240 * Disables the current thread for thread scheduling purposes, until
241 * the specified deadline, unless the permit is available.
242 *
243 * <p>If the permit is available then it is consumed and the call
244 * returns immediately; otherwise the current thread becomes disabled
245 * for thread scheduling purposes and lies dormant until one of four
246 * things happens:
247 *
248 * <ul>
249 * <li>Some other thread invokes {@link #unpark unpark} with the
250 * current thread as the target; or
251 *
252 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
253 * current thread; or
254 *
255 * <li>The specified deadline passes; or
256 *
257 * <li>The call spuriously (that is, for no reason) returns.
258 * </ul>
259 *
260 * <p>This method does <em>not</em> report which of these caused the
261 * method to return. Callers should re-check the conditions which caused
262 * the thread to park in the first place. Callers may also determine,
263 * for example, the interrupt status of the thread, or the current time
264 * upon return.
265 *
266 * @param blocker the synchronization object responsible for this
267 * thread parking
268 * @param deadline the absolute time, in milliseconds from the Epoch,
269 * to wait until
270 * @since 1.6
271 */
272 public static void parkUntil(Object blocker, long deadline) {
273 Thread t = Thread.currentThread();
274 setBlocker(t, blocker);
275 U.park(true, deadline);
276 setBlocker(t, null);
277 }
278
279 /**
280 * Returns the blocker object supplied to the most recent
281 * invocation of a park method that has not yet unblocked, or null
282 * if not blocked. The value returned is just a momentary
283 * snapshot -- the thread may have since unblocked or blocked on a
284 * different blocker object.
285 *
286 * @param t the thread
287 * @return the blocker
288 * @throws NullPointerException if argument is null
289 * @since 1.6
290 */
291 public static Object getBlocker(Thread t) {
292 if (t == null)
293 throw new NullPointerException();
294 return U.getObjectVolatile(t, PARKBLOCKER);
295 }
303 * for thread scheduling purposes and lies dormant until one of three
304 * things happens:
305 *
306 * <ul>
307 *
308 * <li>Some other thread invokes {@link #unpark unpark} with the
309 * current thread as the target; or
310 *
311 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
312 * the current thread; or
313 *
314 * <li>The call spuriously (that is, for no reason) returns.
315 * </ul>
316 *
317 * <p>This method does <em>not</em> report which of these caused the
318 * method to return. Callers should re-check the conditions which caused
319 * the thread to park in the first place. Callers may also determine,
320 * for example, the interrupt status of the thread upon return.
321 */
322 public static void park() {
323 U.park(false, 0L);
324 }
325
326 /**
327 * Disables the current thread for thread scheduling purposes, for up to
328 * the specified waiting time, unless the permit is available.
329 *
330 * <p>If the permit is available then it is consumed and the call
331 * returns immediately; otherwise the current thread becomes disabled
332 * for thread scheduling purposes and lies dormant until one of four
333 * things happens:
334 *
335 * <ul>
336 * <li>Some other thread invokes {@link #unpark unpark} with the
337 * current thread as the target; or
338 *
339 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
340 * the current thread; or
341 *
342 * <li>The specified waiting time elapses; or
343 *
344 * <li>The call spuriously (that is, for no reason) returns.
345 * </ul>
346 *
347 * <p>This method does <em>not</em> report which of these caused the
348 * method to return. Callers should re-check the conditions which caused
349 * the thread to park in the first place. Callers may also determine,
350 * for example, the interrupt status of the thread, or the elapsed time
351 * upon return.
352 *
353 * @param nanos the maximum number of nanoseconds to wait
354 */
355 public static void parkNanos(long nanos) {
356 if (nanos > 0)
357 U.park(false, nanos);
358 }
359
360 /**
361 * Disables the current thread for thread scheduling purposes, until
362 * the specified deadline, unless the permit is available.
363 *
364 * <p>If the permit is available then it is consumed and the call
365 * returns immediately; otherwise the current thread becomes disabled
366 * for thread scheduling purposes and lies dormant until one of four
367 * things happens:
368 *
369 * <ul>
370 * <li>Some other thread invokes {@link #unpark unpark} with the
371 * current thread as the target; or
372 *
373 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
374 * the current thread; or
375 *
376 * <li>The specified deadline passes; or
377 *
378 * <li>The call spuriously (that is, for no reason) returns.
379 * </ul>
380 *
381 * <p>This method does <em>not</em> report which of these caused the
382 * method to return. Callers should re-check the conditions which caused
383 * the thread to park in the first place. Callers may also determine,
384 * for example, the interrupt status of the thread, or the current time
385 * upon return.
386 *
387 * @param deadline the absolute time, in milliseconds from the Epoch,
388 * to wait until
389 */
390 public static void parkUntil(long deadline) {
391 U.park(true, deadline);
392 }
393
394 /**
395 * Returns the pseudo-randomly initialized or updated secondary seed.
396 * Copied from ThreadLocalRandom due to package access restrictions.
397 */
398 static final int nextSecondarySeed() {
399 int r;
400 Thread t = Thread.currentThread();
401 if ((r = U.getInt(t, SECONDARY)) != 0) {
402 r ^= r << 13; // xorshift
403 r ^= r >>> 17;
404 r ^= r << 5;
405 }
406 else if ((r = java.util.concurrent.ThreadLocalRandom.current().nextInt()) == 0)
407 r = 1; // avoid zero
408 U.putInt(t, SECONDARY, r);
409 return r;
410 }
411
412 /**
|
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
19 *
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
22 * questions.
23 */
24
25 /*
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
29 * file:
30 *
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
34 */
35
36 package java.util.concurrent.locks;
37
38 import java.util.concurrent.TimeUnit;
39 import jdk.internal.misc.Unsafe;
40
41 /**
42 * Basic thread blocking primitives for creating locks and other
43 * synchronization classes.
44 *
45 * <p>This class associates, with each thread that uses it, a permit
46 * (in the sense of the {@link java.util.concurrent.Semaphore
47 * Semaphore} class). A call to {@code park} will return immediately
48 * if the permit is available, consuming it in the process; otherwise
49 * it <em>may</em> block. A call to {@code unpark} makes the permit
50 * available, if it was not already available. (Unlike with Semaphores
51 * though, permits do not accumulate. There is at most one.)
52 * Reliable usage requires the use of volatile (or atomic) variables
53 * to control when to park or unpark. Orderings of calls to these
54 * methods are maintained with respect to volatile variable accesses,
55 * but not necessarily non-volatile variable accesses.
56 *
57 * <p>Methods {@code park} and {@code unpark} provide efficient
58 * means of blocking and unblocking threads that do not encounter the
140 public class LockSupport {
141 private LockSupport() {} // Cannot be instantiated.
142
143 private static void setBlocker(Thread t, Object arg) {
144 // Even though volatile, hotspot doesn't need a write barrier here.
145 U.putObject(t, PARKBLOCKER, arg);
146 }
147
148 /**
149 * Makes available the permit for the given thread, if it
150 * was not already available. If the thread was blocked on
151 * {@code park} then it will unblock. Otherwise, its next call
152 * to {@code park} is guaranteed not to block. This operation
153 * is not guaranteed to have any effect at all if the given
154 * thread has not been started.
155 *
156 * @param thread the thread to unpark, or {@code null}, in which case
157 * this operation has no effect
158 */
159 public static void unpark(Thread thread) {
160 if (thread != null) {
161 if (thread instanceof Fiber) {
162 ((Fiber)thread).unpark();
163 } else {
164 U.unpark(thread);
165 }
166 }
167 }
168
169 /**
170 * Disables the current thread for thread scheduling purposes unless the
171 * permit is available.
172 *
173 * <p>If the permit is available then it is consumed and the call returns
174 * immediately; otherwise
175 * the current thread becomes disabled for thread scheduling
176 * purposes and lies dormant until one of three things happens:
177 *
178 * <ul>
179 * <li>Some other thread invokes {@link #unpark unpark} with the
180 * current thread as the target; or
181 *
182 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
183 * the current thread; or
184 *
185 * <li>The call spuriously (that is, for no reason) returns.
186 * </ul>
187 *
188 * <p>This method does <em>not</em> report which of these caused the
189 * method to return. Callers should re-check the conditions which caused
190 * the thread to park in the first place. Callers may also determine,
191 * for example, the interrupt status of the thread upon return.
192 *
193 * @param blocker the synchronization object responsible for this
194 * thread parking
195 * @since 1.6
196 */
197 public static void park(Object blocker) {
198 Thread t = Thread.currentThread();
199 setBlocker(t, blocker);
200 if (t instanceof Fiber) {
201 Fiber.park();
202 } else {
203 U.park(false, 0L);
204 }
205 setBlocker(t, null);
206 }
207
208 /**
209 * Disables the current thread for thread scheduling purposes, for up to
210 * the specified waiting time, unless the permit is available.
211 *
212 * <p>If the permit is available then it is consumed and the call
213 * returns immediately; otherwise the current thread becomes disabled
214 * for thread scheduling purposes and lies dormant until one of four
215 * things happens:
216 *
217 * <ul>
218 * <li>Some other thread invokes {@link #unpark unpark} with the
219 * current thread as the target; or
220 *
221 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
222 * the current thread; or
223 *
224 * <li>The specified waiting time elapses; or
225 *
226 * <li>The call spuriously (that is, for no reason) returns.
227 * </ul>
228 *
229 * <p>This method does <em>not</em> report which of these caused the
230 * method to return. Callers should re-check the conditions which caused
231 * the thread to park in the first place. Callers may also determine,
232 * for example, the interrupt status of the thread, or the elapsed time
233 * upon return.
234 *
235 * @param blocker the synchronization object responsible for this
236 * thread parking
237 * @param nanos the maximum number of nanoseconds to wait
238 * @since 1.6
239 */
240 public static void parkNanos(Object blocker, long nanos) {
241 if (nanos > 0) {
242 Thread t = Thread.currentThread();
243 setBlocker(t, blocker);
244 if (t instanceof Fiber) {
245 Fiber.parkNanos(nanos);
246 } else {
247 U.park(false, nanos);
248 }
249 setBlocker(t, null);
250 }
251 }
252
253 /**
254 * Disables the current thread for thread scheduling purposes, until
255 * the specified deadline, unless the permit is available.
256 *
257 * <p>If the permit is available then it is consumed and the call
258 * returns immediately; otherwise the current thread becomes disabled
259 * for thread scheduling purposes and lies dormant until one of four
260 * things happens:
261 *
262 * <ul>
263 * <li>Some other thread invokes {@link #unpark unpark} with the
264 * current thread as the target; or
265 *
266 * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
267 * current thread; or
268 *
269 * <li>The specified deadline passes; or
270 *
271 * <li>The call spuriously (that is, for no reason) returns.
272 * </ul>
273 *
274 * <p>This method does <em>not</em> report which of these caused the
275 * method to return. Callers should re-check the conditions which caused
276 * the thread to park in the first place. Callers may also determine,
277 * for example, the interrupt status of the thread, or the current time
278 * upon return.
279 *
280 * @param blocker the synchronization object responsible for this
281 * thread parking
282 * @param deadline the absolute time, in milliseconds from the Epoch,
283 * to wait until
284 * @since 1.6
285 */
286 public static void parkUntil(Object blocker, long deadline) {
287 Thread t = Thread.currentThread();
288 setBlocker(t, blocker);
289 if (t instanceof Fiber) {
290 long millis = deadline - System.currentTimeMillis();
291 long nanos = TimeUnit.NANOSECONDS.convert(millis, TimeUnit.MILLISECONDS);
292 Fiber.parkNanos(nanos);
293 } else {
294 U.park(true, deadline);
295 }
296 setBlocker(t, null);
297 }
298
299 /**
300 * Returns the blocker object supplied to the most recent
301 * invocation of a park method that has not yet unblocked, or null
302 * if not blocked. The value returned is just a momentary
303 * snapshot -- the thread may have since unblocked or blocked on a
304 * different blocker object.
305 *
306 * @param t the thread
307 * @return the blocker
308 * @throws NullPointerException if argument is null
309 * @since 1.6
310 */
311 public static Object getBlocker(Thread t) {
312 if (t == null)
313 throw new NullPointerException();
314 return U.getObjectVolatile(t, PARKBLOCKER);
315 }
323 * for thread scheduling purposes and lies dormant until one of three
324 * things happens:
325 *
326 * <ul>
327 *
328 * <li>Some other thread invokes {@link #unpark unpark} with the
329 * current thread as the target; or
330 *
331 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
332 * the current thread; or
333 *
334 * <li>The call spuriously (that is, for no reason) returns.
335 * </ul>
336 *
337 * <p>This method does <em>not</em> report which of these caused the
338 * method to return. Callers should re-check the conditions which caused
339 * the thread to park in the first place. Callers may also determine,
340 * for example, the interrupt status of the thread upon return.
341 */
342 public static void park() {
343 Thread t = Thread.currentThread();
344 if (t instanceof Fiber) {
345 Fiber.park();
346 } else {
347 U.park(false, 0L);
348 }
349 }
350
351 /**
352 * Disables the current thread for thread scheduling purposes, for up to
353 * the specified waiting time, unless the permit is available.
354 *
355 * <p>If the permit is available then it is consumed and the call
356 * returns immediately; otherwise the current thread becomes disabled
357 * for thread scheduling purposes and lies dormant until one of four
358 * things happens:
359 *
360 * <ul>
361 * <li>Some other thread invokes {@link #unpark unpark} with the
362 * current thread as the target; or
363 *
364 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
365 * the current thread; or
366 *
367 * <li>The specified waiting time elapses; or
368 *
369 * <li>The call spuriously (that is, for no reason) returns.
370 * </ul>
371 *
372 * <p>This method does <em>not</em> report which of these caused the
373 * method to return. Callers should re-check the conditions which caused
374 * the thread to park in the first place. Callers may also determine,
375 * for example, the interrupt status of the thread, or the elapsed time
376 * upon return.
377 *
378 * @param nanos the maximum number of nanoseconds to wait
379 */
380 public static void parkNanos(long nanos) {
381 if (nanos > 0) {
382 Thread t = Thread.currentThread();
383 if (t instanceof Fiber) {
384 Fiber.parkNanos(nanos);
385 } else {
386 U.park(false, nanos);
387 }
388 }
389 }
390
391 /**
392 * Disables the current thread for thread scheduling purposes, until
393 * the specified deadline, unless the permit is available.
394 *
395 * <p>If the permit is available then it is consumed and the call
396 * returns immediately; otherwise the current thread becomes disabled
397 * for thread scheduling purposes and lies dormant until one of four
398 * things happens:
399 *
400 * <ul>
401 * <li>Some other thread invokes {@link #unpark unpark} with the
402 * current thread as the target; or
403 *
404 * <li>Some other thread {@linkplain Thread#interrupt interrupts}
405 * the current thread; or
406 *
407 * <li>The specified deadline passes; or
408 *
409 * <li>The call spuriously (that is, for no reason) returns.
410 * </ul>
411 *
412 * <p>This method does <em>not</em> report which of these caused the
413 * method to return. Callers should re-check the conditions which caused
414 * the thread to park in the first place. Callers may also determine,
415 * for example, the interrupt status of the thread, or the current time
416 * upon return.
417 *
418 * @param deadline the absolute time, in milliseconds from the Epoch,
419 * to wait until
420 */
421 public static void parkUntil(long deadline) {
422 Thread t = Thread.currentThread();
423 if (t instanceof Fiber) {
424 long millis = deadline - System.currentTimeMillis();
425 long nanos = TimeUnit.NANOSECONDS.convert(millis, TimeUnit.MILLISECONDS);
426 Fiber.parkNanos(nanos);
427 } else {
428 U.park(true, deadline);
429 }
430 }
431
432 /**
433 * Returns the pseudo-randomly initialized or updated secondary seed.
434 * Copied from ThreadLocalRandom due to package access restrictions.
435 */
436 static final int nextSecondarySeed() {
437 int r;
438 Thread t = Thread.currentThread();
439 if ((r = U.getInt(t, SECONDARY)) != 0) {
440 r ^= r << 13; // xorshift
441 r ^= r >>> 17;
442 r ^= r << 5;
443 }
444 else if ((r = java.util.concurrent.ThreadLocalRandom.current().nextInt()) == 0)
445 r = 1; // avoid zero
446 U.putInt(t, SECONDARY, r);
447 return r;
448 }
449
450 /**
|