< prev index next >

src/java.base/share/classes/java/util/concurrent/locks/LockSupport.java

Print this page

 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

156      *
157      * @param blocker the blocker object
158      * @since 14
159      */
160     public static void setCurrentBlocker(Object blocker) {
161         U.putReferenceOpaque(Thread.currentThread(), PARKBLOCKER, blocker);
162     }
163 
164     /**
165      * Makes available the permit for the given thread, if it
166      * was not already available.  If the thread was blocked on
167      * {@code park} then it will unblock.  Otherwise, its next call
168      * to {@code park} is guaranteed not to block. This operation
169      * is not guaranteed to have any effect at all if the given
170      * thread has not been started.
171      *
172      * @param thread the thread to unpark, or {@code null}, in which case
173      *        this operation has no effect
174      */
175     public static void unpark(Thread thread) {
176         if (thread != null)
177             U.unpark(thread);





178     }
179 
180     /**
181      * Disables the current thread for thread scheduling purposes unless the
182      * permit is available.
183      *
184      * <p>If the permit is available then it is consumed and the call returns
185      * immediately; otherwise
186      * the current thread becomes disabled for thread scheduling
187      * purposes and lies dormant until one of three things happens:
188      *
189      * <ul>
190      * <li>Some other thread invokes {@link #unpark unpark} with the
191      * current thread as the target; or
192      *
193      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
194      * the current thread; or
195      *
196      * <li>The call spuriously (that is, for no reason) returns.
197      * </ul>
198      *
199      * <p>This method does <em>not</em> report which of these caused the
200      * method to return. Callers should re-check the conditions which caused
201      * the thread to park in the first place. Callers may also determine,
202      * for example, the interrupt status of the thread upon return.
203      *
204      * @param blocker the synchronization object responsible for this
205      *        thread parking
206      * @since 1.6
207      */
208     public static void park(Object blocker) {
209         Thread t = Thread.currentThread();
210         setBlocker(t, blocker);
211         U.park(false, 0L);
212         setBlocker(t, null);







213     }
214 
215     /**
216      * Disables the current thread for thread scheduling purposes, for up to
217      * the specified waiting time, unless the permit is available.
218      *
219      * <p>If the specified waiting time is zero or negative, the
220      * method does nothing. Otherwise, if the permit is available then
221      * it is consumed and the call returns immediately; otherwise the
222      * current thread becomes disabled for thread scheduling purposes
223      * and lies dormant until one of four things happens:
224      *
225      * <ul>
226      * <li>Some other thread invokes {@link #unpark unpark} with the
227      * current thread as the target; or
228      *
229      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
230      * the current thread; or
231      *
232      * <li>The specified waiting time elapses; or
233      *
234      * <li>The call spuriously (that is, for no reason) returns.
235      * </ul>
236      *
237      * <p>This method does <em>not</em> report which of these caused the
238      * method to return. Callers should re-check the conditions which caused
239      * the thread to park in the first place. Callers may also determine,
240      * for example, the interrupt status of the thread, or the elapsed time
241      * upon return.
242      *
243      * @param blocker the synchronization object responsible for this
244      *        thread parking
245      * @param nanos the maximum number of nanoseconds to wait
246      * @since 1.6
247      */
248     public static void parkNanos(Object blocker, long nanos) {
249         if (nanos > 0) {
250             Thread t = Thread.currentThread();
251             setBlocker(t, blocker);
252             U.park(false, nanos);
253             setBlocker(t, null);







254         }
255     }
256 
257     /**
258      * Disables the current thread for thread scheduling purposes, until
259      * the specified deadline, unless the permit is available.
260      *
261      * <p>If the permit is available then it is consumed and the call
262      * returns immediately; otherwise the current thread becomes disabled
263      * for thread scheduling purposes and lies dormant until one of four
264      * things happens:
265      *
266      * <ul>
267      * <li>Some other thread invokes {@link #unpark unpark} with the
268      * current thread as the target; or
269      *
270      * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
271      * current thread; or
272      *
273      * <li>The specified deadline passes; or
274      *
275      * <li>The call spuriously (that is, for no reason) returns.
276      * </ul>
277      *
278      * <p>This method does <em>not</em> report which of these caused the
279      * method to return. Callers should re-check the conditions which caused
280      * the thread to park in the first place. Callers may also determine,
281      * for example, the interrupt status of the thread, or the current time
282      * upon return.
283      *
284      * @param blocker the synchronization object responsible for this
285      *        thread parking
286      * @param deadline the absolute time, in milliseconds from the Epoch,
287      *        to wait until
288      * @since 1.6
289      */
290     public static void parkUntil(Object blocker, long deadline) {
291         Thread t = Thread.currentThread();
292         setBlocker(t, blocker);
293         U.park(true, deadline);
294         setBlocker(t, null);







295     }
296 
297     /**
298      * Returns the blocker object supplied to the most recent
299      * invocation of a park method that has not yet unblocked, or null
300      * if not blocked.  The value returned is just a momentary
301      * snapshot -- the thread may have since unblocked or blocked on a
302      * different blocker object.
303      *
304      * @param t the thread
305      * @return the blocker
306      * @throws NullPointerException if argument is null
307      * @since 1.6
308      */
309     public static Object getBlocker(Thread t) {
310         if (t == null)
311             throw new NullPointerException();
312         return U.getReferenceOpaque(t, PARKBLOCKER);
313     }
314 

321      * for thread scheduling purposes and lies dormant until one of three
322      * things happens:
323      *
324      * <ul>
325      *
326      * <li>Some other thread invokes {@link #unpark unpark} with the
327      * current thread as the target; or
328      *
329      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
330      * the current thread; or
331      *
332      * <li>The call spuriously (that is, for no reason) returns.
333      * </ul>
334      *
335      * <p>This method does <em>not</em> report which of these caused the
336      * method to return. Callers should re-check the conditions which caused
337      * the thread to park in the first place. Callers may also determine,
338      * for example, the interrupt status of the thread upon return.
339      */
340     public static void park() {
341         U.park(false, 0L);




342     }
343 
344     /**
345      * Disables the current thread for thread scheduling purposes, for up to
346      * the specified waiting time, unless the permit is available.
347      *
348      * <p>If the specified waiting time is zero or negative, the
349      * method does nothing. Otherwise, if the permit is available then
350      * it is consumed and the call returns immediately; otherwise the
351      * current thread becomes disabled for thread scheduling purposes
352      * and lies dormant until one of four things happens:
353      *
354      * <ul>
355      * <li>Some other thread invokes {@link #unpark unpark} with the
356      * current thread as the target; or
357      *
358      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
359      * the current thread; or
360      *
361      * <li>The specified waiting time elapses; or
362      *
363      * <li>The call spuriously (that is, for no reason) returns.
364      * </ul>
365      *
366      * <p>This method does <em>not</em> report which of these caused the
367      * method to return. Callers should re-check the conditions which caused
368      * the thread to park in the first place. Callers may also determine,
369      * for example, the interrupt status of the thread, or the elapsed time
370      * upon return.
371      *
372      * @param nanos the maximum number of nanoseconds to wait
373      */
374     public static void parkNanos(long nanos) {
375         if (nanos > 0)
376             U.park(false, nanos);





377     }
378 
379     /**
380      * Disables the current thread for thread scheduling purposes, until
381      * the specified deadline, unless the permit is available.
382      *
383      * <p>If the permit is available then it is consumed and the call
384      * returns immediately; otherwise the current thread becomes disabled
385      * for thread scheduling purposes and lies dormant until one of four
386      * things happens:
387      *
388      * <ul>
389      * <li>Some other thread invokes {@link #unpark unpark} with the
390      * current thread as the target; or
391      *
392      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
393      * the current thread; or
394      *
395      * <li>The specified deadline passes; or
396      *
397      * <li>The call spuriously (that is, for no reason) returns.
398      * </ul>
399      *
400      * <p>This method does <em>not</em> report which of these caused the
401      * method to return. Callers should re-check the conditions which caused
402      * the thread to park in the first place. Callers may also determine,
403      * for example, the interrupt status of the thread, or the current time
404      * upon return.
405      *
406      * @param deadline the absolute time, in milliseconds from the Epoch,
407      *        to wait until
408      */
409     public static void parkUntil(long deadline) {
410         U.park(true, deadline);




411     }
412 
413     /**
414      * Returns the thread id for the given thread.  We must access
415      * this directly rather than via method Thread.getId() because
416      * getId() has been known to be overridden in ways that do not
417      * preserve unique mappings.
418      */
419     static final long getThreadId(Thread thread) {
420         return U.getLong(thread, TID);

421     }
422 
423     // Hotspot implementation via intrinsics API
424     private static final Unsafe U = Unsafe.getUnsafe();
425     private static final long PARKBLOCKER
426         = U.objectFieldOffset(Thread.class, "parkBlocker");
427     private static final long TID
428         = U.objectFieldOffset(Thread.class, "tid");

429 
430 }

 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.VirtualThreads;
 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

157      *
158      * @param blocker the blocker object
159      * @since 14
160      */
161     public static void setCurrentBlocker(Object blocker) {
162         U.putReferenceOpaque(Thread.currentThread(), PARKBLOCKER, blocker);
163     }
164 
165     /**
166      * Makes available the permit for the given thread, if it
167      * was not already available.  If the thread was blocked on
168      * {@code park} then it will unblock.  Otherwise, its next call
169      * to {@code park} is guaranteed not to block. This operation
170      * is not guaranteed to have any effect at all if the given
171      * thread has not been started.
172      *
173      * @param thread the thread to unpark, or {@code null}, in which case
174      *        this operation has no effect
175      */
176     public static void unpark(Thread thread) {
177         if (thread != null) {
178             if (thread.isVirtual()) {
179                 VirtualThreads.unpark(thread); // can throw RejectedExecutionException
180             } else {
181                 U.unpark(thread);
182             }
183         }
184     }
185 
186     /**
187      * Disables the current thread for thread scheduling purposes unless the
188      * permit is available.
189      *
190      * <p>If the permit is available then it is consumed and the call returns
191      * immediately; otherwise
192      * the current thread becomes disabled for thread scheduling
193      * purposes and lies dormant until one of three things happens:
194      *
195      * <ul>
196      * <li>Some other thread invokes {@link #unpark unpark} with the
197      * current thread as the target; or
198      *
199      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
200      * the current thread; or
201      *
202      * <li>The call spuriously (that is, for no reason) returns.
203      * </ul>
204      *
205      * <p>This method does <em>not</em> report which of these caused the
206      * method to return. Callers should re-check the conditions which caused
207      * the thread to park in the first place. Callers may also determine,
208      * for example, the interrupt status of the thread upon return.
209      *
210      * @param blocker the synchronization object responsible for this
211      *        thread parking
212      * @since 1.6
213      */
214     public static void park(Object blocker) {
215         Thread t = Thread.currentThread();
216         setBlocker(t, blocker);
217         try {
218             if (t.isVirtual()) {
219                 VirtualThreads.park();
220             } else {
221                 U.park(false, 0L);
222             }
223         } finally {
224             setBlocker(t, null);
225         }
226     }
227 
228     /**
229      * Disables the current thread for thread scheduling purposes, for up to
230      * the specified waiting time, unless the permit is available.
231      *
232      * <p>If the specified waiting time is zero or negative, the
233      * method does nothing. Otherwise, if the permit is available then
234      * it is consumed and the call returns immediately; otherwise the
235      * current thread becomes disabled for thread scheduling purposes
236      * and lies dormant until one of four things happens:
237      *
238      * <ul>
239      * <li>Some other thread invokes {@link #unpark unpark} with the
240      * current thread as the target; or
241      *
242      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
243      * the current thread; or
244      *
245      * <li>The specified waiting time elapses; or
246      *
247      * <li>The call spuriously (that is, for no reason) returns.
248      * </ul>
249      *
250      * <p>This method does <em>not</em> report which of these caused the
251      * method to return. Callers should re-check the conditions which caused
252      * the thread to park in the first place. Callers may also determine,
253      * for example, the interrupt status of the thread, or the elapsed time
254      * upon return.
255      *
256      * @param blocker the synchronization object responsible for this
257      *        thread parking
258      * @param nanos the maximum number of nanoseconds to wait
259      * @since 1.6
260      */
261     public static void parkNanos(Object blocker, long nanos) {
262         if (nanos > 0) {
263             Thread t = Thread.currentThread();
264             setBlocker(t, blocker);
265             try {
266                 if (t.isVirtual()) {
267                     VirtualThreads.park(nanos);
268                 } else {
269                     U.park(false, nanos);
270                 }
271             } finally {
272                 setBlocker(t, null);
273             }
274         }
275     }
276 
277     /**
278      * Disables the current thread for thread scheduling purposes, until
279      * the specified deadline, unless the permit is available.
280      *
281      * <p>If the permit is available then it is consumed and the call
282      * returns immediately; otherwise the current thread becomes disabled
283      * for thread scheduling purposes and lies dormant until one of four
284      * things happens:
285      *
286      * <ul>
287      * <li>Some other thread invokes {@link #unpark unpark} with the
288      * current thread as the target; or
289      *
290      * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
291      * current thread; or
292      *
293      * <li>The specified deadline passes; or
294      *
295      * <li>The call spuriously (that is, for no reason) returns.
296      * </ul>
297      *
298      * <p>This method does <em>not</em> report which of these caused the
299      * method to return. Callers should re-check the conditions which caused
300      * the thread to park in the first place. Callers may also determine,
301      * for example, the interrupt status of the thread, or the current time
302      * upon return.
303      *
304      * @param blocker the synchronization object responsible for this
305      *        thread parking
306      * @param deadline the absolute time, in milliseconds from the Epoch,
307      *        to wait until
308      * @since 1.6
309      */
310     public static void parkUntil(Object blocker, long deadline) {
311         Thread t = Thread.currentThread();
312         setBlocker(t, blocker);
313         try {
314             if (t.isVirtual()) {
315                 VirtualThreads.parkUntil(deadline);
316             } else {
317                 U.park(true, deadline);
318             }
319         } finally {
320             setBlocker(t, null);
321         }
322     }
323 
324     /**
325      * Returns the blocker object supplied to the most recent
326      * invocation of a park method that has not yet unblocked, or null
327      * if not blocked.  The value returned is just a momentary
328      * snapshot -- the thread may have since unblocked or blocked on a
329      * different blocker object.
330      *
331      * @param t the thread
332      * @return the blocker
333      * @throws NullPointerException if argument is null
334      * @since 1.6
335      */
336     public static Object getBlocker(Thread t) {
337         if (t == null)
338             throw new NullPointerException();
339         return U.getReferenceOpaque(t, PARKBLOCKER);
340     }
341 

348      * for thread scheduling purposes and lies dormant until one of three
349      * things happens:
350      *
351      * <ul>
352      *
353      * <li>Some other thread invokes {@link #unpark unpark} with the
354      * current thread as the target; or
355      *
356      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
357      * the current thread; or
358      *
359      * <li>The call spuriously (that is, for no reason) returns.
360      * </ul>
361      *
362      * <p>This method does <em>not</em> report which of these caused the
363      * method to return. Callers should re-check the conditions which caused
364      * the thread to park in the first place. Callers may also determine,
365      * for example, the interrupt status of the thread upon return.
366      */
367     public static void park() {
368         if (Thread.currentThread().isVirtual()) {
369             VirtualThreads.park();
370         } else {
371             U.park(false, 0L);
372         }
373     }
374 
375     /**
376      * Disables the current thread for thread scheduling purposes, for up to
377      * the specified waiting time, unless the permit is available.
378      *
379      * <p>If the specified waiting time is zero or negative, the
380      * method does nothing. Otherwise, if the permit is available then
381      * it is consumed and the call returns immediately; otherwise the
382      * current thread becomes disabled for thread scheduling purposes
383      * and lies dormant until one of four things happens:
384      *
385      * <ul>
386      * <li>Some other thread invokes {@link #unpark unpark} with the
387      * current thread as the target; or
388      *
389      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
390      * the current thread; or
391      *
392      * <li>The specified waiting time elapses; or
393      *
394      * <li>The call spuriously (that is, for no reason) returns.
395      * </ul>
396      *
397      * <p>This method does <em>not</em> report which of these caused the
398      * method to return. Callers should re-check the conditions which caused
399      * the thread to park in the first place. Callers may also determine,
400      * for example, the interrupt status of the thread, or the elapsed time
401      * upon return.
402      *
403      * @param nanos the maximum number of nanoseconds to wait
404      */
405     public static void parkNanos(long nanos) {
406         if (nanos > 0) {
407             if (Thread.currentThread().isVirtual()) {
408                 VirtualThreads.park(nanos);
409             } else {
410                 U.park(false, nanos);
411             }
412         }
413     }
414 
415     /**
416      * Disables the current thread for thread scheduling purposes, until
417      * the specified deadline, unless the permit is available.
418      *
419      * <p>If the permit is available then it is consumed and the call
420      * returns immediately; otherwise the current thread becomes disabled
421      * for thread scheduling purposes and lies dormant until one of four
422      * things happens:
423      *
424      * <ul>
425      * <li>Some other thread invokes {@link #unpark unpark} with the
426      * current thread as the target; or
427      *
428      * <li>Some other thread {@linkplain Thread#interrupt interrupts}
429      * the current thread; or
430      *
431      * <li>The specified deadline passes; or
432      *
433      * <li>The call spuriously (that is, for no reason) returns.
434      * </ul>
435      *
436      * <p>This method does <em>not</em> report which of these caused the
437      * method to return. Callers should re-check the conditions which caused
438      * the thread to park in the first place. Callers may also determine,
439      * for example, the interrupt status of the thread, or the current time
440      * upon return.
441      *
442      * @param deadline the absolute time, in milliseconds from the Epoch,
443      *        to wait until
444      */
445     public static void parkUntil(long deadline) {
446         if (Thread.currentThread().isVirtual()) {
447             VirtualThreads.parkUntil(deadline);
448         } else {
449             U.park(true, deadline);
450         }
451     }
452 
453     /**
454      * Returns the thread id for the given thread.  We must access
455      * this directly rather than via method Thread.getId() because
456      * getId() has been known to be overridden in ways that do not
457      * preserve unique mappings.
458      */
459     static final long getThreadId(Thread thread) {
460         // need to keep in sync with Thread::getId
461         return U.getLong(thread, TID) & TID_MASK;
462     }
463 
464     // Hotspot implementation via intrinsics API
465     private static final Unsafe U = Unsafe.getUnsafe();
466     private static final long PARKBLOCKER
467         = U.objectFieldOffset(Thread.class, "parkBlocker");
468     private static final long TID
469         = U.objectFieldOffset(Thread.class, "tid");
470     private static final long TID_MASK = (1L << 48) - 1;
471 
472 }
< prev index next >