/**
 * A reentrant mutual exclusion {@link Lock} with the same basic
 * behavior and semantics as the implicit monitor lock accessed using
 * {@code synchronized} methods and statements, but with extended
 * capabilities.
 * 
A {@code ReentrantLock} is owned by the thread last
 * successfully locking, but not yet unlocking it. A thread invoking
 * {@code lock} will return, successfully acquiring the lock, when
 * the lock is not owned by another thread. The method will return
 * immediately if the current thread already owns the lock. This can
 * be checked using methods {@link #isHeldByCurrentThread}, and {@link
 * #getHoldCount}.

  /** Synchronizer providing all implementation mechanics **/
  private final Sync sync;

  /**
   * Creates an instance of {@code ReentrantLock}.
   * This is equivalent to using {@code ReentrantLock(false)}.
   **/
  public ReentrantLock() {
    sync = new NonfairSync();
  }
  /**
   * Creates an instance of {@code ReentrantLock} with the
   * given fairness policy.
   * @param fair {@code true} if this lock should use a fair ordering policy
   **/
  public ReentrantLock(boolean fair) {
    sync = fair ? new FairSync() : new NonfairSync();
  }

  /**
   * Acquires the lock.
   * 
Acquires the lock if it is not held by another thread and returns
   * immediately, setting the lock hold count to one.
   * 
If the current thread already holds the lock then the hold
   * count is incremented by one and the method returns immediately.
   * 
If the lock is held by another thread then the
   * current thread becomes disabled for thread scheduling
   * purposes and lies dormant until the lock has been acquired,
   * at which time the lock hold count is set to one.
   **/
  public void lock() {
    sync.lock();
  }
  public void lockInterruptibly() throws InterruptedException {
    sync.acquireInterruptibly(1);
  }

    /**
     * 非公平锁中的lock
     * Performs lock. Try immediate barge, backing up to normal
     * acquire on failure.
     **/
    final void lock() {
      if (compareAndSetState(0, 1))
        setExclusiveOwnerThread(Thread.currentThread());
      else
        acquire(1);
    }
    //公平锁中的lock
    final void lock() {
      acquire(1);
    }

  /**
   * Atomically sets synchronization state to the given updated
   * value if the current state value equals the expected value.
   * This operation has memory semantics of a {@code volatile} read
   * and write.
   * @param expect the expected value
   * @param update the new value
   * @return {@code true} if successful. False return indicates that the actual
   *     value was not equal to the expected value.
   **/
  protected final boolean compareAndSetState(int expect, int update) {
    // See below for intrinsics setup to support this
    return unsafe.compareAndSwapInt(this, stateOffset, expect, update);
  }
  public final native boolean compareAndSwapInt(Object var1, long var2, int var4, int var5);

  /**
   * 公平锁的lock
   **/
  final void lock() {
    acquire(1);
  }
  /**
   * Acquires in exclusive mode, ignoring interrupts. Implemented
   * by invoking at least once {@link #tryAcquire},
   * returning on success. Otherwise the thread is queued, possibly
   * repeatedly blocking and unblocking, invoking {@link
   * #tryAcquire} until success. This method can be used
   * to implement method {@link Lock#lock}.
   * @param arg the acquire argument. This value is conveyed to
   *    {@link #tryAcquire} but is otherwise uninterpreted and
   *    can represent anything you like.
   **/
  public final void acquire(int arg) {
    /**
     * acquire首先进行tryAcquire()操作。如果tryAcquire()成功时则获取到锁，即刻返回。
     * 如果tryAcquire()false时，会执行acquireQueued(addWaiter(Node.EXCLUSIVE), arg)
     * 操作。如果acquireQueued(addWaiter(Node.EXCLUSIVE), arg)true时，则当前线程中断自己。
     * 如果acquireQueued(addWaiter(Node.EXCLUSIVE), arg)false，则返回。
     * 其中tryAcquire()操作在NonfairSync中和FairSync中实现又有所区别。
     **/
    if (!tryAcquire(arg) &&
        acquireQueued(addWaiter(Node.EXCLUSIVE), arg))
      selfInterrupt();
  }
  /**
   * NonfairSync中的tryAcquire。
   * @param acquires
   * @return
   **/
  protected final boolean tryAcquire(int acquires) {
    return nonfairTryAcquire(acquires);
  }
  /**
   * Performs non-fair tryLock. tryAcquire is implemented in
   * subclasses, but both need nonfair try for trylock method.
   **/
  final boolean nonfairTryAcquire(int acquires) {
    final Thread current = Thread.currentThread();
    //首先获取当前同步状态值
    int c = getState();
    if (c == 0) {
      //c为0，表示目前没有线程占用锁。没有线程占用锁时，当前线程尝试抢锁，如果抢锁成功，则返回true。
      if (compareAndSetState(0, acquires)) {
        setExclusiveOwnerThread(current);
        return true;
      }
    }
    else if (current == getExclusiveOwnerThread()) {
      //c不等于0时表示锁被线程占用。如果是当前线程占用了，则将锁计数加上acquires，并返回true。
      int nextc = c + acquires;
      if (nextc < 0) // overflow
        throw new Error("Maximum lock count exceeded");
      setState(nextc);
      return true;
    }
    //以上情况都不是时，返回false，表示非公平抢锁失败。
    return false;
  }
  /**
   * Fair version of tryAcquire. Don't grant access unless
   * recursive call or no waiters or is first.
   * 这个是公平版本的tryAcquire
   **/
  protected final boolean tryAcquire(int acquires) {
    final Thread current = Thread.currentThread();
    int c = getState();
    if (c == 0) {
      //c=0时表示锁未被占用。这里是先判断队列中前面是否有别的线程。没有别的线程时，才进行CAS操作。
      //公平锁之所以公平，正是因为这里。它发现锁未被占用时，首先判断等待队列中是否有别的线程已经在等待了。
      //而非公平锁，发现锁未被占用时，根本不管队列中的排队情况，上来就抢。
      if (!hasQueuedPredecessors() &&
          compareAndSetState(0, acquires)) {
        setExclusiveOwnerThread(current);
        return true;
      }
    }
    else if (current == getExclusiveOwnerThread()) {
      int nextc = c + acquires;
      if (nextc < 0)
        throw new Error("Maximum lock count exceeded");
      setState(nextc);
      return true;
    }
    return false;
  }
  /**
   * Acquires in exclusive uninterruptible mode for thread already in
   * queue. Used by condition wait methods as well as acquire.
   * 当抢锁失败时，先执行addWaiter(Node.EXCLUSIVE)，将当前线程加入等待队列，再执行该方法。
   * 该方法的作用是中断当前线程，并进行检查，知道当前线程是队列中的第一个线程，并且抢锁成功时，
   * 该方法返回。
   * @param node the node
   * @param arg the acquire argument
   * @return {@code true} if interrupted while waiting
   **/
  final boolean acquireQueued(final Node node, int arg) {
    boolean failed = true;
    try {
      boolean interrupted = false;
      for (;;) {
        final Node p = node.predecessor();
        if (p == head && tryAcquire(arg)) {
          setHead(node);
          p.next = null; // help GC
          failed = false;
          return interrupted;
        }
        if (shouldParkAfterFailedAcquire(p, node) &&
            parkAndCheckInterrupt())
          interrupted = true;
      }
    } finally {
      if (failed)
        cancelAcquire(node);
    }
  }

/**
   * Acquires the lock only if it is not held by another thread at the time
   * of invocation.
   * 
Acquires the lock if it is not held by another thread and
   * returns immediately with the value {@code true}, setting the
   * lock hold count to one. Even when this lock has been set to use a
   * fair ordering policy, a call to {@code tryLock()} will
   * immediately acquire the lock if it is available, whether or not
   * other threads are currently waiting for the lock.
   * This "barging" behavior can be useful in certain
   * circumstances, even though it breaks fairness. If you want to honor
   * the fairness setting for this lock, then use
   * {@link #tryLock(long, TimeUnit) tryLock(0, TimeUnit.SECONDS) }
   * which is almost equivalent (it also detects interruption).
   * 
If the current thread already holds this lock then the hold
   * count is incremented by one and the method returns {@code true}.
   * 
If the lock is held by another thread then this method will return
   * immediately with the value {@code false}.
   * @return {@code true} if the lock was free and was acquired by the
   *     current thread, or the lock was already held by the current
   *     thread; and {@code false} otherwise
   **/
  public boolean tryLock() {
    return sync.nonfairTryAcquire(1);
  }
  public boolean tryLock(long timeout, TimeUnit unit)
      throws InterruptedException {
    return sync.tryAcquireNanos(1, unit.toNanos(timeout));
  }

  /**
   * Attempts to release this lock.
   * 
If the current thread is the holder of this lock then the hold
   * count is decremented. If the hold count is now zero then the lock
   * is released. If the current thread is not the holder of this
   * lock then {@link IllegalMonitorStateException} is thrown.
   * @throws IllegalMonitorStateException if the current thread does not
   *     hold this lock
   **/
  public void unlock() {
    sync.release(1);
  }
  /**
   * Releases in exclusive mode. Implemented by unblocking one or
   * more threads if {@link #tryRelease} returns true.
   * This method can be used to implement method {@link Lock#unlock}.
   * @param arg the release argument. This value is conveyed to
   *    {@link #tryRelease} but is otherwise uninterpreted and
   *    can represent anything you like.
   * @return the value returned from {@link #tryRelease}
   **/
  public final boolean release(int arg) {
    if (tryRelease(arg)) {
      Node h = head;
      if (h != null && h.waitStatus != 0)
        unparkSuccessor(h);
      return true;
    }
    return false;
  }
  protected final boolean tryRelease(int releases) {
      int c = getState() - releases;
      if (Thread.currentThread() != getExclusiveOwnerThread())
        throw new IllegalMonitorStateException();
      boolean free = false;
      if (c == 0) {
        free = true;
        setExclusiveOwnerThread(null);
      }
      setState(c);
      return free;
    }
  /**
   * Wakes up node's successor, if one exists.
   * @param node the node
   **/
  private void unparkSuccessor(Node node) {
    /**
     * If status is negative (i.e., possibly needing signal) try
     * to clear in anticipation of signalling. It is OK if this
     * fails or if status is changed by waiting thread.
     **/
    int ws = node.waitStatus;
    if (ws < 0)
      compareAndSetWaitStatus(node, ws, 0);
    /**
     * Thread to unpark is held in successor, which is normally
     * just the next node. But if cancelled or apparently null,
     * traverse backwards from tail to find the actual
     * non-cancelled successor.
     **/
    Node s = node.next;
    if (s == null || s.waitStatus > 0) {
      s = null;
      for (Node t = tail; t != null && t != node; t = t.prev)
        if (t.waitStatus <= 0)
          s = t;
    }
    if (s != null)
      LockSupport.unpark(s.thread);
  }

  /**
   * Returns a {@link Condition} instance for use with this
   * {@link Lock} instance.
   * 
The returned {@link Condition} instance supports the same
   * usages as do the {@link Object} monitor methods ({@link
   * Object#wait() wait}, {@link Object#notify notify}, and {@link
   * Object#notifyAll notifyAll}) when used with the built-in
   * monitor lock.
   * 

   * 
If this lock is not held when any of the {@link Condition}
   * {@linkplain Condition#await() waiting} or {@linkplain
   * Condition#signal signalling} methods are called, then an {@link
   * IllegalMonitorStateException} is thrown.
   * 
When the condition {@linkplain Condition#await() waiting}
   * methods are called the lock is released and, before they
   * return, the lock is reacquired and the lock hold count restored
   * to what it was when the method was called.
   * 
If a thread is {@linkplain Thread#interrupt interrupted}
   * while waiting then the wait will terminate, an {@link
   * InterruptedException} will be thrown, and the thread's
   * interrupted status will be cleared.
   * 
 Waiting threads are signalled in FIFO order.
   * 
The ordering of lock reacquisition for threads returning
   * from waiting methods is the same as for threads initially
   * acquiring the lock, which is in the default case not specified,
   * but for fair locks favors those threads that have been
   * waiting the longest.
   * 
   * @return the Condition object
   **/
  public Condition newCondition() {
    return sync.newCondition();
  }