1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/rt/emul/compact/src/main/java/java/util/concurrent/locks/LockSupport.java Sat Mar 19 10:46:31 2016 +0100
1.3 @@ -0,0 +1,385 @@
1.4 +/*
1.5 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.6 + *
1.7 + * This code is free software; you can redistribute it and/or modify it
1.8 + * under the terms of the GNU General Public License version 2 only, as
1.9 + * published by the Free Software Foundation. Oracle designates this
1.10 + * particular file as subject to the "Classpath" exception as provided
1.11 + * by Oracle in the LICENSE file that accompanied this code.
1.12 + *
1.13 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.14 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.15 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.16 + * version 2 for more details (a copy is included in the LICENSE file that
1.17 + * accompanied this code).
1.18 + *
1.19 + * You should have received a copy of the GNU General Public License version
1.20 + * 2 along with this work; if not, write to the Free Software Foundation,
1.21 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.22 + *
1.23 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.24 + * or visit www.oracle.com if you need additional information or have any
1.25 + * questions.
1.26 + */
1.27 +
1.28 +/*
1.29 + * This file is available under and governed by the GNU General Public
1.30 + * License version 2 only, as published by the Free Software Foundation.
1.31 + * However, the following notice accompanied the original version of this
1.32 + * file:
1.33 + *
1.34 + * Written by Doug Lea with assistance from members of JCP JSR-166
1.35 + * Expert Group and released to the public domain, as explained at
1.36 + * http://creativecommons.org/publicdomain/zero/1.0/
1.37 + */
1.38 +
1.39 +package java.util.concurrent.locks;
1.40 +import java.util.concurrent.*;
1.41 +import sun.misc.Unsafe;
1.42 +
1.43 +
1.44 +/**
1.45 + * Basic thread blocking primitives for creating locks and other
1.46 + * synchronization classes.
1.47 + *
1.48 + * <p>This class associates, with each thread that uses it, a permit
1.49 + * (in the sense of the {@link java.util.concurrent.Semaphore
1.50 + * Semaphore} class). A call to {@code park} will return immediately
1.51 + * if the permit is available, consuming it in the process; otherwise
1.52 + * it <em>may</em> block. A call to {@code unpark} makes the permit
1.53 + * available, if it was not already available. (Unlike with Semaphores
1.54 + * though, permits do not accumulate. There is at most one.)
1.55 + *
1.56 + * <p>Methods {@code park} and {@code unpark} provide efficient
1.57 + * means of blocking and unblocking threads that do not encounter the
1.58 + * problems that cause the deprecated methods {@code Thread.suspend}
1.59 + * and {@code Thread.resume} to be unusable for such purposes: Races
1.60 + * between one thread invoking {@code park} and another thread trying
1.61 + * to {@code unpark} it will preserve liveness, due to the
1.62 + * permit. Additionally, {@code park} will return if the caller's
1.63 + * thread was interrupted, and timeout versions are supported. The
1.64 + * {@code park} method may also return at any other time, for "no
1.65 + * reason", so in general must be invoked within a loop that rechecks
1.66 + * conditions upon return. In this sense {@code park} serves as an
1.67 + * optimization of a "busy wait" that does not waste as much time
1.68 + * spinning, but must be paired with an {@code unpark} to be
1.69 + * effective.
1.70 + *
1.71 + * <p>The three forms of {@code park} each also support a
1.72 + * {@code blocker} object parameter. This object is recorded while
1.73 + * the thread is blocked to permit monitoring and diagnostic tools to
1.74 + * identify the reasons that threads are blocked. (Such tools may
1.75 + * access blockers using method {@link #getBlocker}.) The use of these
1.76 + * forms rather than the original forms without this parameter is
1.77 + * strongly encouraged. The normal argument to supply as a
1.78 + * {@code blocker} within a lock implementation is {@code this}.
1.79 + *
1.80 + * <p>These methods are designed to be used as tools for creating
1.81 + * higher-level synchronization utilities, and are not in themselves
1.82 + * useful for most concurrency control applications. The {@code park}
1.83 + * method is designed for use only in constructions of the form:
1.84 + * <pre>while (!canProceed()) { ... LockSupport.park(this); }</pre>
1.85 + * where neither {@code canProceed} nor any other actions prior to the
1.86 + * call to {@code park} entail locking or blocking. Because only one
1.87 + * permit is associated with each thread, any intermediary uses of
1.88 + * {@code park} could interfere with its intended effects.
1.89 + *
1.90 + * <p><b>Sample Usage.</b> Here is a sketch of a first-in-first-out
1.91 + * non-reentrant lock class:
1.92 + * <pre>{@code
1.93 + * class FIFOMutex {
1.94 + * private final AtomicBoolean locked = new AtomicBoolean(false);
1.95 + * private final Queue<Thread> waiters
1.96 + * = new ConcurrentLinkedQueue<Thread>();
1.97 + *
1.98 + * public void lock() {
1.99 + * boolean wasInterrupted = false;
1.100 + * Thread current = Thread.currentThread();
1.101 + * waiters.add(current);
1.102 + *
1.103 + * // Block while not first in queue or cannot acquire lock
1.104 + * while (waiters.peek() != current ||
1.105 + * !locked.compareAndSet(false, true)) {
1.106 + * LockSupport.park(this);
1.107 + * if (Thread.interrupted()) // ignore interrupts while waiting
1.108 + * wasInterrupted = true;
1.109 + * }
1.110 + *
1.111 + * waiters.remove();
1.112 + * if (wasInterrupted) // reassert interrupt status on exit
1.113 + * current.interrupt();
1.114 + * }
1.115 + *
1.116 + * public void unlock() {
1.117 + * locked.set(false);
1.118 + * LockSupport.unpark(waiters.peek());
1.119 + * }
1.120 + * }}</pre>
1.121 + */
1.122 +
1.123 +public class LockSupport {
1.124 + private LockSupport() {} // Cannot be instantiated.
1.125 +
1.126 + // Hotspot implementation via intrinsics API
1.127 + private static final Unsafe unsafe = Unsafe.getUnsafe();
1.128 + private static final long parkBlockerOffset;
1.129 +
1.130 + static {
1.131 + try {
1.132 + parkBlockerOffset = unsafe.objectFieldOffset
1.133 + (java.lang.Thread.class.getDeclaredField("parkBlocker"));
1.134 + } catch (Exception ex) { throw new Error(ex); }
1.135 + }
1.136 +
1.137 + private static void setBlocker(Thread t, Object arg) {
1.138 + // Even though volatile, hotspot doesn't need a write barrier here.
1.139 + unsafe.putObject(t, parkBlockerOffset, arg);
1.140 + }
1.141 +
1.142 + /**
1.143 + * Makes available the permit for the given thread, if it
1.144 + * was not already available. If the thread was blocked on
1.145 + * {@code park} then it will unblock. Otherwise, its next call
1.146 + * to {@code park} is guaranteed not to block. This operation
1.147 + * is not guaranteed to have any effect at all if the given
1.148 + * thread has not been started.
1.149 + *
1.150 + * @param thread the thread to unpark, or {@code null}, in which case
1.151 + * this operation has no effect
1.152 + */
1.153 + public static void unpark(Thread thread) {
1.154 + if (thread != null)
1.155 + unsafe.unpark(thread);
1.156 + }
1.157 +
1.158 + /**
1.159 + * Disables the current thread for thread scheduling purposes unless the
1.160 + * permit is available.
1.161 + *
1.162 + * <p>If the permit is available then it is consumed and the call returns
1.163 + * immediately; otherwise
1.164 + * the current thread becomes disabled for thread scheduling
1.165 + * purposes and lies dormant until one of three things happens:
1.166 + *
1.167 + * <ul>
1.168 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.169 + * current thread as the target; or
1.170 + *
1.171 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
1.172 + * the current thread; or
1.173 + *
1.174 + * <li>The call spuriously (that is, for no reason) returns.
1.175 + * </ul>
1.176 + *
1.177 + * <p>This method does <em>not</em> report which of these caused the
1.178 + * method to return. Callers should re-check the conditions which caused
1.179 + * the thread to park in the first place. Callers may also determine,
1.180 + * for example, the interrupt status of the thread upon return.
1.181 + *
1.182 + * @param blocker the synchronization object responsible for this
1.183 + * thread parking
1.184 + * @since 1.6
1.185 + */
1.186 + public static void park(Object blocker) {
1.187 + Thread t = Thread.currentThread();
1.188 + setBlocker(t, blocker);
1.189 + unsafe.park(false, 0L);
1.190 + setBlocker(t, null);
1.191 + }
1.192 +
1.193 + /**
1.194 + * Disables the current thread for thread scheduling purposes, for up to
1.195 + * the specified waiting time, unless the permit is available.
1.196 + *
1.197 + * <p>If the permit is available then it is consumed and the call
1.198 + * returns immediately; otherwise the current thread becomes disabled
1.199 + * for thread scheduling purposes and lies dormant until one of four
1.200 + * things happens:
1.201 + *
1.202 + * <ul>
1.203 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.204 + * current thread as the target; or
1.205 + *
1.206 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
1.207 + * the current thread; or
1.208 + *
1.209 + * <li>The specified waiting time elapses; or
1.210 + *
1.211 + * <li>The call spuriously (that is, for no reason) returns.
1.212 + * </ul>
1.213 + *
1.214 + * <p>This method does <em>not</em> report which of these caused the
1.215 + * method to return. Callers should re-check the conditions which caused
1.216 + * the thread to park in the first place. Callers may also determine,
1.217 + * for example, the interrupt status of the thread, or the elapsed time
1.218 + * upon return.
1.219 + *
1.220 + * @param blocker the synchronization object responsible for this
1.221 + * thread parking
1.222 + * @param nanos the maximum number of nanoseconds to wait
1.223 + * @since 1.6
1.224 + */
1.225 + public static void parkNanos(Object blocker, long nanos) {
1.226 + if (nanos > 0) {
1.227 + Thread t = Thread.currentThread();
1.228 + setBlocker(t, blocker);
1.229 + unsafe.park(false, nanos);
1.230 + setBlocker(t, null);
1.231 + }
1.232 + }
1.233 +
1.234 + /**
1.235 + * Disables the current thread for thread scheduling purposes, until
1.236 + * the specified deadline, unless the permit is available.
1.237 + *
1.238 + * <p>If the permit is available then it is consumed and the call
1.239 + * returns immediately; otherwise the current thread becomes disabled
1.240 + * for thread scheduling purposes and lies dormant until one of four
1.241 + * things happens:
1.242 + *
1.243 + * <ul>
1.244 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.245 + * current thread as the target; or
1.246 + *
1.247 + * <li>Some other thread {@linkplain Thread#interrupt interrupts} the
1.248 + * current thread; or
1.249 + *
1.250 + * <li>The specified deadline passes; or
1.251 + *
1.252 + * <li>The call spuriously (that is, for no reason) returns.
1.253 + * </ul>
1.254 + *
1.255 + * <p>This method does <em>not</em> report which of these caused the
1.256 + * method to return. Callers should re-check the conditions which caused
1.257 + * the thread to park in the first place. Callers may also determine,
1.258 + * for example, the interrupt status of the thread, or the current time
1.259 + * upon return.
1.260 + *
1.261 + * @param blocker the synchronization object responsible for this
1.262 + * thread parking
1.263 + * @param deadline the absolute time, in milliseconds from the Epoch,
1.264 + * to wait until
1.265 + * @since 1.6
1.266 + */
1.267 + public static void parkUntil(Object blocker, long deadline) {
1.268 + Thread t = Thread.currentThread();
1.269 + setBlocker(t, blocker);
1.270 + unsafe.park(true, deadline);
1.271 + setBlocker(t, null);
1.272 + }
1.273 +
1.274 + /**
1.275 + * Returns the blocker object supplied to the most recent
1.276 + * invocation of a park method that has not yet unblocked, or null
1.277 + * if not blocked. The value returned is just a momentary
1.278 + * snapshot -- the thread may have since unblocked or blocked on a
1.279 + * different blocker object.
1.280 + *
1.281 + * @param t the thread
1.282 + * @return the blocker
1.283 + * @throws NullPointerException if argument is null
1.284 + * @since 1.6
1.285 + */
1.286 + public static Object getBlocker(Thread t) {
1.287 + if (t == null)
1.288 + throw new NullPointerException();
1.289 + return unsafe.getObjectVolatile(t, parkBlockerOffset);
1.290 + }
1.291 +
1.292 + /**
1.293 + * Disables the current thread for thread scheduling purposes unless the
1.294 + * permit is available.
1.295 + *
1.296 + * <p>If the permit is available then it is consumed and the call
1.297 + * returns immediately; otherwise the current thread becomes disabled
1.298 + * for thread scheduling purposes and lies dormant until one of three
1.299 + * things happens:
1.300 + *
1.301 + * <ul>
1.302 + *
1.303 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.304 + * current thread as the target; or
1.305 + *
1.306 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
1.307 + * the current thread; or
1.308 + *
1.309 + * <li>The call spuriously (that is, for no reason) returns.
1.310 + * </ul>
1.311 + *
1.312 + * <p>This method does <em>not</em> report which of these caused the
1.313 + * method to return. Callers should re-check the conditions which caused
1.314 + * the thread to park in the first place. Callers may also determine,
1.315 + * for example, the interrupt status of the thread upon return.
1.316 + */
1.317 + public static void park() {
1.318 + unsafe.park(false, 0L);
1.319 + }
1.320 +
1.321 + /**
1.322 + * Disables the current thread for thread scheduling purposes, for up to
1.323 + * the specified waiting time, unless the permit is available.
1.324 + *
1.325 + * <p>If the permit is available then it is consumed and the call
1.326 + * returns immediately; otherwise the current thread becomes disabled
1.327 + * for thread scheduling purposes and lies dormant until one of four
1.328 + * things happens:
1.329 + *
1.330 + * <ul>
1.331 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.332 + * current thread as the target; or
1.333 + *
1.334 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
1.335 + * the current thread; or
1.336 + *
1.337 + * <li>The specified waiting time elapses; or
1.338 + *
1.339 + * <li>The call spuriously (that is, for no reason) returns.
1.340 + * </ul>
1.341 + *
1.342 + * <p>This method does <em>not</em> report which of these caused the
1.343 + * method to return. Callers should re-check the conditions which caused
1.344 + * the thread to park in the first place. Callers may also determine,
1.345 + * for example, the interrupt status of the thread, or the elapsed time
1.346 + * upon return.
1.347 + *
1.348 + * @param nanos the maximum number of nanoseconds to wait
1.349 + */
1.350 + public static void parkNanos(long nanos) {
1.351 + if (nanos > 0)
1.352 + unsafe.park(false, nanos);
1.353 + }
1.354 +
1.355 + /**
1.356 + * Disables the current thread for thread scheduling purposes, until
1.357 + * the specified deadline, unless the permit is available.
1.358 + *
1.359 + * <p>If the permit is available then it is consumed and the call
1.360 + * returns immediately; otherwise the current thread becomes disabled
1.361 + * for thread scheduling purposes and lies dormant until one of four
1.362 + * things happens:
1.363 + *
1.364 + * <ul>
1.365 + * <li>Some other thread invokes {@link #unpark unpark} with the
1.366 + * current thread as the target; or
1.367 + *
1.368 + * <li>Some other thread {@linkplain Thread#interrupt interrupts}
1.369 + * the current thread; or
1.370 + *
1.371 + * <li>The specified deadline passes; or
1.372 + *
1.373 + * <li>The call spuriously (that is, for no reason) returns.
1.374 + * </ul>
1.375 + *
1.376 + * <p>This method does <em>not</em> report which of these caused the
1.377 + * method to return. Callers should re-check the conditions which caused
1.378 + * the thread to park in the first place. Callers may also determine,
1.379 + * for example, the interrupt status of the thread, or the current time
1.380 + * upon return.
1.381 + *
1.382 + * @param deadline the absolute time, in milliseconds from the Epoch,
1.383 + * to wait until
1.384 + */
1.385 + public static void parkUntil(long deadline) {
1.386 + unsafe.park(true, deadline);
1.387 + }
1.388 +}