1 /*
  2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  3  *
  4  * This code is free software; you can redistribute it and/or modify it
  5  * under the terms of the GNU General Public License version 2 only, as
  6  * published by the Free Software Foundation.  Oracle designates this
  7  * particular file as subject to the "Classpath" exception as provided
  8  * by Oracle in the LICENSE file that accompanied this code.
  9  *
 10  * This code is distributed in the hope that it will be useful, but WITHOUT
 11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 13  * version 2 for more details (a copy is included in the LICENSE file that
 14  * accompanied this code).
 15  *
 16  * You should have received a copy of the GNU General Public License version
 17  * 2 along with this work; if not, write to the Free Software Foundation,
 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
 59  * problems that cause the deprecated methods {@code Thread.suspend}
 60  * and {@code Thread.resume} to be unusable for such purposes: Races
 61  * between one thread invoking {@code park} and another thread trying
 62  * to {@code unpark} it will preserve liveness, due to the
 63  * permit. Additionally, {@code park} will return if the caller's
 64  * thread was interrupted, and timeout versions are supported. The
 65  * {@code park} method may also return at any other time, for "no
 66  * reason", so in general must be invoked within a loop that rechecks
 67  * conditions upon return. In this sense {@code park} serves as an
 68  * optimization of a "busy wait" that does not waste as much time
 69  * spinning, but must be paired with an {@code unpark} to be
 70  * effective.
 71  *
 72  * <p>The three forms of {@code park} each also support a
 73  * {@code blocker} object parameter. This object is recorded while
 74  * the thread is blocked to permit monitoring and diagnostic tools to
 75  * identify the reasons that threads are blocked. (Such tools may
 76  * access blockers using method {@link #getBlocker(Thread)}.)
 77  * The use of these forms rather than the original forms without this
 78  * parameter is strongly encouraged. The normal argument to supply as
 79  * a {@code blocker} within a lock implementation is {@code this}.
 80  *
 81  * <p>These methods are designed to be used as tools for creating
 82  * higher-level synchronization utilities, and are not in themselves
 83  * useful for most concurrency control applications.  The {@code park}
 84  * method is designed for use only in constructions of the form:
 85  *
 86  * <pre> {@code
 87  * while (!canProceed()) {
 88  *   // ensure request to unpark is visible to other threads
 89  *   ...
 90  *   LockSupport.park(this);
 91  * }}</pre>
 92  *
 93  * where no actions by the thread publishing a request to unpark,
 94  * prior to the call to {@code park}, entail locking or blocking.
 95  * Because only one permit is associated with each thread, any
 96  * intermediary uses of {@code park}, including implicitly via class
 97  * loading, could lead to an unresponsive thread (a "lost unpark").
 98  *
 99  * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
100  * non-reentrant lock class:
101  * <pre> {@code
102  * class FIFOMutex {
103  *   private final AtomicBoolean locked = new AtomicBoolean(false);
104  *   private final Queue<Thread> waiters
105  *     = new ConcurrentLinkedQueue<>();
106  *
107  *   public void lock() {
108  *     boolean wasInterrupted = false;
109  *     // publish current thread for unparkers
110  *     waiters.add(Thread.currentThread());
111  *
112  *     // Block while not first in queue or cannot acquire lock
113  *     while (waiters.peek() != Thread.currentThread() ||
114  *            !locked.compareAndSet(false, true)) {
115  *       LockSupport.park(this);
116  *       // ignore interrupts while waiting
117  *       if (Thread.interrupted())
118  *         wasInterrupted = true;
119  *     }
120  *
121  *     waiters.remove();
122  *     // ensure correct interrupt status on return
123  *     if (wasInterrupted)
124  *       Thread.currentThread().interrupt();
125  *   }
126  *
127  *   public void unlock() {
128  *     locked.set(false);
129  *     LockSupport.unpark(waiters.peek());
130  *   }
131  *
132  *   static {
133  *     // Reduce the risk of "lost unpark" due to classloading
134  *     Class<?> ensureLoaded = LockSupport.class;
135  *   }
136  * }}</pre>
137  *
138  * @since 1.5
139  */
140 public class LockSupport {
141     private LockSupport() {} // Cannot be instantiated.
142 
143     private static void setBlocker(Thread t, Object arg) {
144         U.putReferenceOpaque(t, PARKBLOCKER, arg);
145     }
146 
147     /**
148      * Sets the object to be returned by invocations of {@link
149      * #getBlocker getBlocker} for the current thread. This method may
150      * be used before invoking the no-argument version of {@link
151      * LockSupport#park() park()} from non-public objects, allowing
152      * more helpful diagnostics, or retaining compatibility with
153      * previous implementations of blocking methods.  Previous values
154      * of the blocker are not automatically restored after blocking.
155      * To obtain the effects of {@code park(b}}, use {@code
156      * setCurrentBlocker(b); park(); setCurrentBlocker(null);}
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 
342     /**
343      * Disables the current thread for thread scheduling purposes unless the
344      * permit is available.
345      *
346      * <p>If the permit is available then it is consumed and the call
347      * returns immediately; otherwise the current thread becomes disabled
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 }
--- EOF ---