文章首发于：clawhub.club
JDK LockSuppoprt源码翻译
import sun.misc.Unsafe;
/**
* Basic thread blocking primitives for creating locks and other
* synchronization classes.
* 用于创建锁和其他同步类的基本线程阻塞原语。
* This class associates, with each thread that uses it, a permit
* (in the sense of the {@link java.util.concurrent.Semaphore
* Semaphore} class). A call to {@code park} will return immediately
* if the permit is available, consuming it in the process; otherwise
* it may block. A call to {@code unpark} makes the permit
* available, if it was not already available. (Unlike with Semaphores
* though, permits do not accumulate. There is at most one.)
* 这个类与使用它的每个线程关联一个许可证(和Semaphore类差不多)。
* 如果许可证可用，对{@code park}的调用将立即返回，并在此过程中使用它;否则它可能会阻塞。
* 如果许可证尚未可用，则调用{@code unpark}将使许可证可用。
* (与信号量不同，许可证不会累积。最多只有一个)。
*
*
Methods {@code park} and {@code unpark} provide efficient
* means of blocking and unblocking threads that do not encounter the
* problems that cause the deprecated methods {@code Thread.suspend}
* and {@code Thread.resume} to be unusable for such purposes: Races
* between one thread invoking {@code park} and another thread trying
* to {@code unpark} it will preserve liveness, due to the
* permit. Additionally, {@code park} will return if the caller's
* thread was interrupted, and timeout versions are supported. The
* {@code park} method may also return at any other time, for "no
* reason", so in general must be invoked within a loop that rechecks
* conditions upon return. In this sense {@code park} serves as an
* optimization of a "busy wait" that does not waste as much time
* spinning, but must be paired with an {@code unpark} to be
* effective.
* 方法{@code park}和{@code unpark}提供了有效的方法来阻塞和解除阻塞线程，
* 这些线程不会遇到导致废弃方法{@code Thread.suspend}和{@code Thread.resume}不能用于这些目的的问题:
* 调用{@code park}的线程与试图{@code unpark}的线程之间的竞争将保持活跃，这是由于许可证的原因。
* 此外，如果调用者的线程被中断，并且支持超时版本，则{@code park}将interrupted。
* {@code park}方法也可以在任何其他时间返回，原因是“没有任何原因”，所以通常必须在返回时在循环中调用，循环会重新检查条件。
* 从这个意义上说，{@code park}是一个“繁忙等待”的优化，它不会浪费太多的时间旋转，但必须与{@code unpark}匹配才能有效。
*
*
The three forms of {@code park} each also support a
* {@code blocker} object parameter. This object is recorded while
* the thread is blocked to permit monitoring and diagnostic tools to
* identify the reasons that threads are blocked. (Such tools may
* access blockers using method {@link #getBlocker(Thread)}.)
* The use of these forms rather than the original forms without this
* parameter is strongly encouraged. The normal argument to supply as
* a {@code blocker} within a lock implementation is {@code this}.
* {@code park}的三种形式都支持{@code blocker}对象参数。
* 在线程被阻塞时记录此对象，以便允许监视和诊断工具识别线程被阻塞的原因。
* (这些工具可以使用方法{@link #getBlocker(Thread)}访问阻塞程序。)
* 强烈建议使用这些形式而不是没有此参数的原始形式。
* 在锁实现中作为{@code blocker}提供的正常参数是{@code this}。
*
*
These methods are designed to be used as tools for creating
* higher-level synchronization utilities, and are not in themselves
* useful for most concurrency control applications. The {@code park}
* method is designed for use only in constructions of the form:
* 这些方法被设计为用于创建更高级别的同步实用程序的工具，但它们本身并不适用于大多数并发控制应用程序。
* {@code park}方法只适用于下列结构:
*
{@code
* while (!canProceed()) { ... LockSupport.park(this); }}
*
* where neither {@code canProceed} nor any other actions prior to the
* call to {@code park} entail locking or blocking. Because only one
* permit is associated with each thread, any intermediary uses of
* {@code park} could interfere with its intended effects.
* 在调用{@code park}之前，{@code canProceed}或任何其他操作都不需要锁定或阻塞。
* 因为每个线程只与一个许可证相关联，所以任何中介使用{@code park}都可能干扰它的预期效果。
*
*
Sample Usage. Here is a sketch of a first-in-first-out
* non-reentrant lock class:
* 下面是一个先进先出非重入锁类的例子：
*
{@code
* class FIFOMutex {
* //有两种状态 true或者false
* private final AtomicBoolean locked = new AtomicBoolean(false);
* //线程队列
* private final Queue waiters
* = new ConcurrentLinkedQueue();
*
* //加锁
* public void lock() {
* //中断标志
* boolean wasInterrupted = false;
* //当前线程
* Thread current = Thread.currentThread();
* //当前线程入队列
* waiters.add(current);
*
* // Block while not first in queue or cannot acquire lock
* //在队列中不是第一个或无法获取锁时阻塞
* while (waiters.peek() != current ||
* !locked.compareAndSet(false, true)) {
* //阻塞
* LockSupport.park(this);
* //在等待时忽略中断
* if (Thread.interrupted()) // ignore interrupts while waiting
* wasInterrupted = true;
* }
* //移除当前线程
* waiters.remove();
* //退出时重申中断状态
* if (wasInterrupted) // reassert interrupt status on exit
* current.interrupt();
* }
* 解锁
* public void unlock() {
* //解锁状态设置
* locked.set(false);
* //当前线程解锁定
* LockSupport.unpark(waiters.peek());
* }
* }}
*/
public class LockSupport {
/**
* 不能被实例化。
*/
private LockSupport() {
} // Cannot be instantiated.
/**
* Sets blocker.
*
* @param t the t
* @param arg the arg
*/
private static void setBlocker(Thread t, Object arg) {
// Even though volatile, hotspot doesn't need a write barrier here.
// 尽管hotspot是易失性的，但它并不需要写屏障。
UNSAFE.putObject(t, parkBlockerOffset, arg);
}
/**
* Makes available the permit for the given thread, if it
* was not already available. If the thread was blocked on
* {@code park} then it will unblock. Otherwise, its next call
* to {@code park} is guaranteed not to block. This operation
* is not guaranteed to have any effect at all if the given
* thread has not been started.
* 使给定线程的许可证可用(如果它还没有可用)。如果线程在{@code park}上被阻塞，那么它将解阻塞。
* 否则，它对{@code park}的下一次调用将保证不会阻塞。
* 如果没有启动给定的线程，则不能保证此操作具有任何效果。
*
* @param thread the thread to unpark, or {@code null}, in which case
* this operation has no effect 取消停靠的线程，或{@code null}，在这种情况下，此操作没有效果
*/
public static void unpark(Thread thread) {
//如果线程不为空，则处理，解阻塞
if (thread != null)
UNSAFE.unpark(thread);
}
/**
* Disables the current thread for thread scheduling purposes unless the
* permit is available.
* 除非有许可证，否则为线程调度目的禁用当前线程。
*
* If the permit is available then it is consumed and the call returns
* immediately; otherwise
* the current thread becomes disabled for thread scheduling
* purposes and lies dormant until one of three things happens:
* 如果许可证是可用的，那么它将被使用，调用立即返回;
* 否则，当前线程将出于线程调度的目的被禁用，并处于休眠状态，直到以下三种情况之一发生:
*
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
* 其他一些线程以当前线程为目标调用{@link #unpark unpark}
*
*
- Some other thread {@linkplain Thread#interrupt interrupts}
* the current thread; or
* 其他线程中断当前线程
*
*
- The call spuriously (that is, for no reason) returns.
* 虚假的调用(也就是说，没有理由)返回。
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread upon return.
* 此方法不报告是哪些原因导致该方法返回。调用者应该重新检查导致线程首先停车的条件。
* 例如，调用者还可以在返回时确定线程的中断状态。
*
* @param blocker the synchronization object responsible for this
* thread parking 负责此操作的同步对象
* @since 1.6
*/
public static void park(Object blocker) {
//获取当前线程
Thread t = Thread.currentThread();
//设置线程parkBlocker
setBlocker(t, blocker);
//阻塞线程
UNSAFE.park(false, 0L);
//清除parkBlocker
setBlocker(t, null);
}
/**
* Disables the current thread for thread scheduling purposes, for up to
* the specified waiting time, unless the permit is available.
* 除非有许可证，否则在指定的等待时间内，为线程调度目的禁用当前线程。
*
*
If the permit is available then it is consumed and the call
* returns immediately; otherwise the current thread becomes disabled
* for thread scheduling purposes and lies dormant until one of four
* things happens:
* 如果许可证是可用的，那么它将被使用，调用立即返回;
* 否则，当前线程将出于线程调度的目的被禁用，并处于休眠状态，直到以下四种情况之一发生:
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
* 其他一些线程以当前线程为目标调用{@link #unpark unpark}
*
- Some other thread {@linkplain Thread#interrupt interrupts}
* the current thread; or
* 其他线程中断当前线程
*
*
- The specified waiting time elapses; or
* 指定的等待时间已经过了
*
- The call spuriously (that is, for no reason) returns.
* 虚假的调用(也就是说，没有理由)返回
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread, or the elapsed time
* upon return.
* 此方法不报告是哪些原因导致该方法返回。调用者应该重新检查导致线程首先停车的条件。
* 例如，调用者还可以确定线程的中断状态，或者返回时的运行时间。
*
* @param blocker the synchronization object responsible for this
* thread parking 负责此操作的同步对象
* @param nanos the maximum number of nanoseconds to wait 等待的最大纳秒数
* @since 1.6
*/
public static void parkNanos(Object blocker, long nanos) {
//如果等待纳秒数大于0
if (nanos > 0) {
//获取当前线程
Thread t = Thread.currentThread();
//设置当前线程parkBlocker
setBlocker(t, blocker);
//等待nanos后阻塞线程
UNSAFE.park(false, nanos);
//清除当前线程parkBlocker
setBlocker(t, null);
}
}
/**
* Disables the current thread for thread scheduling purposes, until
* the specified deadline, unless the permit is available.
* 为线程调度目的禁用当前线程，直到指定的截止日期，除非许可证可用。
*
*
If the permit is available then it is consumed and the call
* returns immediately; otherwise the current thread becomes disabled
* for thread scheduling purposes and lies dormant until one of four
* things happens:
* 如果许可证是可用的，那么它将被使用，调用立即返回;
* 否则，当前线程将出于线程调度的目的被禁用，并处于休眠状态，直到以下四种情况之一发生:
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
* 其他一些线程以当前线程为目标调用{@link #unpark unpark}
*
- Some other thread {@linkplain Thread#interrupt interrupts} the
* current thread; or
* 其他线程中断当前线程
*
- The specified deadline passes; or
* 指定的截止日期过了
*
- The call spuriously (that is, for no reason) returns.
* 虚假的调用(也就是说，没有理由)返回
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread, or the current time
* upon return.
* 此方法不报告是哪些原因导致该方法返回。调用者应该重新检查导致线程首先停车的条件。
* 例如，调用者还可以确定线程的中断状态，或者返回时的运行时间。
*
* @param blocker the synchronization object responsible for this
* thread parking 负责此操作的同步对象
* @param deadline the absolute time, in milliseconds from the Epoch,
* to wait until 等待到的绝对时间(以毫秒为单位)
* @since 1.6
*/
public static void parkUntil(Object blocker, long deadline) {
//获取当前线程
Thread t = Thread.currentThread();
//设置当前线程parkBlocker
setBlocker(t, blocker);
//达到截止时间后阻塞线程
UNSAFE.park(true, deadline);
//清除当前线程parkBlocker
setBlocker(t, null);
}
/**
* Returns the blocker object supplied to the most recent
* invocation of a park method that has not yet unblocked, or null
* if not blocked. The value returned is just a momentary
* snapshot -- the thread may have since unblocked or blocked on a
* different blocker object.
* 返回提供给最近一次调用尚未解阻塞的park方法的blocker对象，如果没有阻塞，则返回null。
* 返回的值只是一个瞬时快照——线程可能已经在另一个blocker对象上解除了阻塞或阻塞。
*
* @param t the thread
* @return the blocker
* @throws NullPointerException if argument is null
* @since 1.6
*/
public static Object getBlocker(Thread t) {
//判空
if (t == null)
throw new NullPointerException();
//获取线程parkBlocker
return UNSAFE.getObjectVolatile(t, parkBlockerOffset);
}
/**
* Disables the current thread for thread scheduling purposes unless the
* permit is available.
* 除非有许可证，否则为线程调度目的禁用当前线程。
*
*
If the permit is available then it is consumed and the call
* returns immediately; otherwise the current thread becomes disabled
* for thread scheduling purposes and lies dormant until one of three
* things happens:
* 如果许可证是可用的，那么它将被使用，调用立即返回;
* 否则，当前线程将出于线程调度的目的被禁用，并处于休眠状态，直到以下三种情况之一发生:
*
*
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
* 其他一些线程以当前线程为目标调用{@link #unpark unpark}
*
*
- Some other thread {@linkplain Thread#interrupt interrupts}
* the current thread; or
* 其他线程中断当前线程
*
*
- The call spuriously (that is, for no reason) returns.
* 虚假的调用(也就是说，没有理由)返回。
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread upon return.
* 此方法不报告是哪些原因导致该方法返回。调用者应该重新检查导致线程首先停车的条件。
* 例如，调用者还可以在返回时确定线程的中断状态。
*/
public static void park() {
//阻塞
UNSAFE.park(false, 0L);
}
/**
* Disables the current thread for thread scheduling purposes, for up to
* the specified waiting time, unless the permit is available.
*
*
If the permit is available then it is consumed and the call
* returns immediately; otherwise the current thread becomes disabled
* for thread scheduling purposes and lies dormant until one of four
* things happens:
*
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
*
*
- Some other thread {@linkplain Thread#interrupt interrupts}
* the current thread; or
*
*
- The specified waiting time elapses; or
*
*
- The call spuriously (that is, for no reason) returns.
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread, or the elapsed time
* upon return.
*
* @param nanos the maximum number of nanoseconds to wait
*/
public static void parkNanos(long nanos) {
if (nanos > 0)
//等待nanos后锁定
UNSAFE.park(false, nanos);
}
/**
* Disables the current thread for thread scheduling purposes, until
* the specified deadline, unless the permit is available.
*
*
If the permit is available then it is consumed and the call
* returns immediately; otherwise the current thread becomes disabled
* for thread scheduling purposes and lies dormant until one of four
* things happens:
*
*
* - Some other thread invokes {@link #unpark unpark} with the
* current thread as the target; or
*
*
- Some other thread {@linkplain Thread#interrupt interrupts}
* the current thread; or
*
*
- The specified deadline passes; or
*
*
- The call spuriously (that is, for no reason) returns.
*
*
* This method does not report which of these caused the
* method to return. Callers should re-check the conditions which caused
* the thread to park in the first place. Callers may also determine,
* for example, the interrupt status of the thread, or the current time
* upon return.
*
* @param deadline the absolute time, in milliseconds from the Epoch,
* to wait until
*/
public static void parkUntil(long deadline) {
//到截至日期后锁定
UNSAFE.park(true, deadline);
}
/**
* Returns the pseudo-randomly initialized or updated secondary seed.
* Copied from ThreadLocalRandom due to package access restrictions.
* 返回伪随机初始化或更新的辅助种子。由于包访问限制，从ThreadLocalRandom复制。
*/
static final int nextSecondarySeed() {
//threadLocalRandomSecondarySeed
int r;
//当前线程
Thread t = Thread.currentThread();
if ((r = UNSAFE.getInt(t, SECONDARY)) != 0) {
r ^= r << 13; // xorshift
r ^= r >>> 17;
r ^= r << 5;
} else if ((r = java.util.concurrent.ThreadLocalRandom.current().nextInt()) == 0)
r = 1; // avoid zero
UNSAFE.putInt(t, SECONDARY, r);
return r;
}
// Hotspot implementation via intrinsics API
private static final Unsafe UNSAFE;
private static final long parkBlockerOffset;
private static final long SEED;
private static final long PROBE;
private static final long SECONDARY;
static {
try {
UNSAFE = Unsafe.getUnsafe();
Class tk = Thread.class;
parkBlockerOffset = UNSAFE.objectFieldOffset
(tk.getDeclaredField("parkBlocker"));
SEED = UNSAFE.objectFieldOffset
(tk.getDeclaredField("threadLocalRandomSeed"));
PROBE = UNSAFE.objectFieldOffset
(tk.getDeclaredField("threadLocalRandomProbe"));
SECONDARY = UNSAFE.objectFieldOffset
(tk.getDeclaredField("threadLocalRandomSecondarySeed"));
} catch (Exception ex) {
throw new Error(ex);
}
}
}