java.util.concurrent.locks
類別 ReentrantLock

java.lang.Object
  java.util.concurrent.locks.ReentrantLock

所有已實作的介面：

Serializable, Lock

public class ReentrantLock
extends Object
implements Lock, Serializable

一個可重入的互斥鎖 Lock，它具有與使用 synchronized 方法和語句所存取的隱式監視器鎖相同的一些基本行為和語義，但功能更強大。

ReentrantLock 將由最近成功獲得鎖，並且還沒有釋放該鎖的執行緒所擁有。當鎖沒有被另一個執行緒所擁有時，調用 lock 的執行緒將成功獲取該鎖並返回。如果當前執行緒已經擁有該鎖，此方法將立即返回。可以使用 isHeldByCurrentThread() 和 getHoldCount() 方法來檢查此情況是否發生。

此類別的建構子接受一個可選的公平 參數。當設置為 true 時，在多個執行緒的爭用下，這些鎖傾向於將存取權授予等待時間最長的執行緒。否則此鎖將無法保證任何特定存取順序。與採用預設設置（使用不公平鎖）相比，使用公平鎖的程序在許多執行緒存取時表現為很低的總體吞吐量（即速度很慢，常常極其慢），但是在獲得鎖和保證鎖分派的均衡性時差異較小。不過要注意的是，公平鎖不能保證執行緒排程的公平性。因此，使用公平鎖的眾多執行緒中的一員可能獲得多倍的成功機會，這種情況發生在其他活動執行緒沒有被處理並且目前並未持有鎖時。還要注意的是，未定時的 tryLock 方法並沒有使用公平設置。因為即使其他執行緒正在等待，只要該鎖是可用的，此方法就可以獲得成功。

建議總是 立即實踐，使用 lock 塊來調用 try，在之前/之後的建構中，最典型的程式碼如下：

 class X {
   private final ReentrantLock lock = new ReentrantLock();
   // ...

   public void m() { 
     lock.lock();  // block until condition holds
     try {
       // ... method body
     } finally {
       lock.unlock()
     }
   }
 }
 

除了實作 Lock 介面，此類別還定義了 isLocked 和 getLockQueueLength 方法，以及一些相關的 protected 存取方法，這些方法對檢測和監視可能很有用。

該類別的序列化與內置鎖的行為方式相同：一個反序列化的鎖處於解除鎖定狀態，不管它被序列化時的狀態是怎樣的。

此鎖最多支持同一個執行緒發起的 2147483648 個遞歸鎖。試圖超過此限制會導致由鎖方法拋出的 Error。

從以下版本開始：

1.5

另請參見：

序列化表格

建構子摘要

ReentrantLock()
創建一個 ReentrantLock 的實例。

ReentrantLock(boolean fair)
創建一個具有給定公平策略的 ReentrantLock。

方法摘要

int	getHoldCount() 查詢當前執行緒保持此鎖的次數。
protected Thread	getOwner() 返回目前擁有此鎖的執行緒，如果此鎖不被任何執行緒擁有，則返回 null。
protected Collection<Thread>	getQueuedThreads() 返回一個 collection，它包含可能正等待獲取此鎖的執行緒。
int	getQueueLength() 返回正等待獲取此鎖的執行緒估計數。
protected Collection<Thread>	getWaitingThreads(Condition condition) 返回一個 collection，它包含可能正在等待與此鎖相關給定條件的那些執行緒。
int	getWaitQueueLength(Condition condition) 返回等待與此鎖相關的給定條件的執行緒估計數。
boolean	hasQueuedThread(Thread thread) 查詢給定執行緒是否正在等待獲取此鎖。
boolean	hasQueuedThreads() 查詢是否有些執行緒正在等待獲取此鎖。
boolean	hasWaiters(Condition condition) 查詢是否有些執行緒正在等待與此鎖有關的給定條件。
boolean	isFair() 如果此鎖的公平設置為 true，則返回 true。
boolean	isHeldByCurrentThread() 查詢當前執行緒是否保持此鎖。
boolean	isLocked() 查詢此鎖是否由任意執行緒保持。
void	lock() 獲取鎖。
void	lockInterruptibly() 如果當前執行緒未被中斷，則獲取鎖。
Condition	newCondition() 返回用來與此 Lock 實例一起使用的 Condition 實例。
String	toString() 返回標識此鎖及其鎖定狀態的字元串。
boolean	tryLock() 僅在調用時鎖未被另一個執行緒保持的情況下，才獲取該鎖。
boolean	tryLock(long timeout, TimeUnit unit) 如果鎖在給定等待時間內沒有被另一個執行緒保持，且當前執行緒未被中斷，則獲取該鎖。
void	unlock() 試圖釋放此鎖。

從類別 java.lang.Object 繼承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

建構子詳細資訊

ReentrantLock

public ReentrantLock()

創建一個 ReentrantLock 的實例。這等同於使用 ReentrantLock(false)。

ReentrantLock

public ReentrantLock(boolean fair)

創建一個具有給定公平策略的 ReentrantLock。

參數：

fair - 如果此鎖應該使用公平的排序策略，則該參數為 true

方法詳細資訊

lock

public void lock()

獲取鎖。

如果該鎖沒有被另一個執行緒保持，則獲取該鎖並立即返回，將鎖的保持計數設置為 1。

如果當前執行緒已經保持該鎖，則將保持計數加 1，並且該方法立即返回。

如果該鎖被另一個執行緒保持，則出於執行緒排程的目的，禁用當前執行緒，並且在獲得鎖之前，該執行緒將一直處於休眠狀態，此時鎖保持計數被設置為 1。

指定者：

介面 Lock 中的 lock

lockInterruptibly

public void lockInterruptibly()
                       throws InterruptedException

如果當前執行緒未被中斷，則獲取鎖。

如果該鎖沒有被另一個執行緒保持，則獲取該鎖並立即返回，將鎖的保持計數設置為 1。

如果當前執行緒已經保持此鎖，則將保持計數加 1，並且該方法立即返回。

如果鎖被另一個執行緒保持，則出於執行緒排程目的，禁用當前執行緒，並且在發生以下兩種情況之一以前，該執行緒將一直處於休眠狀態：

• 鎖由當前執行緒獲得；或者
• 其他某個執行緒中斷當前執行緒。

如果當前執行緒獲得該鎖，則將鎖保持計數設置為 1。

如果當前執行緒：

• 在進入此方法時已經設置了該執行緒的中斷狀態；或者
• 在等待獲取鎖的同時被中斷。

則拋出 InterruptedException，並且清除當前執行緒的已中斷狀態。

在此實作中，因為此方法是一個顯式中斷點，所以要優先考慮回應中斷，而不是回應鎖的普通獲取或重入獲取。

指定者：

介面 Lock 中的 lockInterruptibly

拋出：

InterruptedException - 如果當前執行緒已中斷。

tryLock

public boolean tryLock()

僅在調用時鎖未被另一個執行緒保持的情況下，才獲取該鎖。

如果該鎖沒有被另一個執行緒保持，並且立即返回 true 值，則將鎖的保持計數設置為 1。即使已將此鎖設置為使用公平排序策略，但是調用 tryLock() 仍將 立即獲取鎖（如果有可用的），而不管其他執行緒當前是否正在等待該鎖。在某些情況下，此“闖入”行為可能很有用，即使它會打破公平性也如此。如果希望遵守此鎖的公平設置，則使用 tryLock(0, TimeUnit.SECONDS) ，它幾乎是等效的（也檢測中斷）。

如果當前執行緒已經保持此鎖，則將保持計數加 1，該方法將返回 true。

如果鎖被另一個執行緒保持，則此方法將立即返回 false 值。

指定者：

介面 Lock 中的 tryLock

返回：

如果鎖是自由的並且被當前執行緒獲取，或者當前執行緒已經保持該鎖，則返回 true；否則返回 false

tryLock

public boolean tryLock(long timeout,
                       TimeUnit unit)
                throws InterruptedException

如果鎖在給定等待時間內沒有被另一個執行緒保持，且當前執行緒未被中斷，則獲取該鎖。

如果該鎖沒有被另一個執行緒保持，並且立即返回 true 值，則將鎖的保持計數設置為 1。如果為了使用公平的排序策略，已經設置此鎖，並且其他執行緒都在等待該鎖，則不會 獲取一個可用的鎖。這與 tryLock() 方法相反。如果想使用一個允許闖入公平鎖的定時 tryLock，那麼可以將定時形式和不定時形式組合在一起：

if (lock.tryLock() || lock.tryLock(timeout, unit) ) { ... }
 

如果當前執行緒已經保持此鎖，則將保持計數加 1，該方法將返回 true。

如果鎖被另一個執行緒保持，則出於執行緒排程目的，禁用當前執行緒，並且在發生以下三種情況之一以前，該執行緒將一直處於休眠狀態：

• 鎖由當前執行緒獲得；或者
• 其他某個執行緒中斷 當前執行緒；或者
• 已超過指定的等待時間

如果獲得該鎖，則返回 true 值，並將鎖保持計數設置為 1。

如果當前執行緒：

• 在進入此方法時已經設置了該執行緒的中斷狀態；或者
• 在等待獲取鎖的同時被中斷。

則拋出 InterruptedException，並且清除當前執行緒的已中斷狀態。

如果超出了指定的等待時間，則返回值為 false。如果該時間小於等於 0，則此方法根本不會等待。

在此實作中，因為此方法是一個顯式中斷點，所以要優先考慮回應中斷，而不是回應鎖的普通獲取或重入獲取，或者報告所用的等待時間。

指定者：

介面 Lock 中的 tryLock

參數：

timeout - 等待鎖的時間

unit - timeout 參數的時間單位

返回：

如果鎖是自由的並且由當前執行緒獲取，或者當前執行緒已經保持該鎖，則返回 true；如果在獲取該鎖之前已經到達等待時間，則返回 false

拋出：

InterruptedException - 如果當前執行緒被中斷

NullPointerException - 如果時間單位為 null

unlock

public void unlock()

試圖釋放此鎖。

如果當前執行緒是此鎖所有者，則將保持計數減 1。如果保持計數現在為 0，則釋放該鎖。如果當前執行緒不是此鎖的持有者，則拋出 IllegalMonitorStateException。

指定者：

介面 Lock 中的 unlock

拋出：

IllegalMonitorStateException - 如果當前執行緒沒有保持此鎖

newCondition

public Condition newCondition()

返回用來與此 Lock 實例一起使用的 Condition 實例。

在使用內置監視器鎖時，返回的 Condition 實例支持與 Object 的監視器方法（wait、notify 和 notifyAll）相同的用法。

• 在調用 Condition、waiting 或 signalling 這些方法中的任意一個方法時，如果沒有保持此鎖，則將拋出 IllegalMonitorStateException。
• 在調用 waiting 條件方法時，將釋放鎖，並在這些方法返回之前，重新獲取該鎖，將鎖保持計數恢復為調用方法時所持有的值。
• 如果執行緒在等待時被中斷，則等待將終止，並將拋出 InterruptedException，清除執行緒的中斷狀態。
• 等待執行緒按 FIFO 順序收到信號。
• 等待方法返回的執行緒重新獲取鎖的順序與執行緒最初獲取鎖的順序相同，在預設情況下，未指定此順序，但對於公平 鎖，它們更傾向於那些等待時間最長的執行緒。

指定者：

介面 Lock 中的 newCondition

返回：

Condition 物件

getHoldCount

public int getHoldCount()

查詢當前執行緒保持此鎖的次數。

對於與解除鎖操作不比對的每個鎖操作，執行緒都會保持一個鎖。

保持計數資訊通常只用於測試和除錯。例如，如果不應該使用已經保持的鎖進入程式碼的某一部分，則可以宣告如下：

 class X {
   ReentrantLock lock = new ReentrantLock();
   // ...     
   public void m() { 
     assert lock.getHoldCount() == 0;
     lock.lock();
     try {
       // ... method body
     } finally {
       lock.unlock();
     }
   }
 }
 

返回：

當前執行緒保持此鎖的次數，如果此鎖未被當前執行緒保持過，則返回 0

isHeldByCurrentThread

public boolean isHeldByCurrentThread()

查詢當前執行緒是否保持此鎖。

與內置監視器鎖的 Thread.holdsLock(java.lang.Object) 方法類似，此方法通常用於除錯和測試。例如，只在保持某個鎖時才應調用的方法可以宣告如下：

 class X {
   ReentrantLock lock = new ReentrantLock();
   // ...

   public void m() { 
       assert lock.isHeldByCurrentThread();
       // ... method body
   }
 }
 

還可以用此方法來確保某個重入鎖是否以非重入方式使用的，例如：

 class X {
   ReentrantLock lock = new ReentrantLock();
   // ...

   public void m() { 
       assert !lock.isHeldByCurrentThread();
       lock.lock();
       try {
           // ... method body
       } finally {
           lock.unlock();
       }
   }
 }
 

返回：

如果當前執行緒保持此鎖，則返回 true；否則返回 false

isLocked

public boolean isLocked()

查詢此鎖是否由任意執行緒保持。此方法用於監視系統狀態，不用於同步控制。

返回：

如果任意執行緒保持此鎖，則返回 true；否則返回 false

isFair

public final boolean isFair()

如果此鎖的公平設置為 true，則返回 true。

返回：

如果此鎖的公平設置為 true，則返回 true

getOwner

protected Thread getOwner()

返回目前擁有此鎖的執行緒，如果此鎖不被任何執行緒擁有，則返回 null。當此方法被不是擁有者的執行緒調用，返回值反映當前鎖狀態的最大近似值。 例如，擁有者可以暫時為 null，也就是說有些執行緒試圖獲取該鎖，但還沒有實作。此方法用於加快子類別的建構速度，提供更多的鎖監視設施。

返回：

擁有者，如果沒有，則返回 null

hasQueuedThreads

public final boolean hasQueuedThreads()

查詢是否有些執行緒正在等待獲取此鎖。注意，因為隨時可能發生取消，所以返回 true 並不保證有其他執行緒將獲取此鎖。此方法主要用於監視系統狀態。

返回：

如果可能有其他執行緒正在等待獲取鎖，則返回 true

hasQueuedThread

public final boolean hasQueuedThread(Thread thread)

查詢給定執行緒是否正在等待獲取此鎖。注意，因為隨時可能發生取消，所以返回 true 並不保證此執行緒將獲取此鎖。此方法主要用於監視系統狀態。

參數：

thread - 執行緒

返回：

如果給定執行緒已加入佇列並且正在等待此鎖，則返回 true

拋出：

NullPointerException - 如果 thread 為 null

getQueueLength

public final int getQueueLength()

返回正等待獲取此鎖的執行緒估計數。該值僅是估計的數字，因為在此方法遍歷內部資料結構的同時，執行緒的數目可能動態地變化。此方法用於監視系統狀態，不用於同步控制。

返回：

正在等待此鎖的執行緒估計數

getQueuedThreads

protected Collection<Thread> getQueuedThreads()

返回一個 collection，它包含可能正等待獲取此鎖的執行緒。因為在建構此結果的同時實際的執行緒 set 可能動態地變化，所以返回的 collection 僅是盡力的估計值。所返回 collection 中的元素沒有特定的順序。此方法用於加快子類別的建構速度，以提供更多的監視設施。

返回：

執行緒的 collection

hasWaiters

public boolean hasWaiters(Condition condition)

查詢是否有些執行緒正在等待與此鎖有關的給定條件。注意，因為隨時可能發生逾時和中斷，所以返回 true 並不保證將來某個 signal 將喚醒執行緒。此方法主要用於監視系統狀態。

參數：

condition - 條件

返回：

如果有任何等待的執行緒，則返回 true

拋出：

IllegalMonitorStateException - 如果沒有保持此鎖

IllegalArgumentException - 如果給定 condition 與此鎖無關

NullPointerException - 如果 condition 為 null

getWaitQueueLength

public int getWaitQueueLength(Condition condition)

返回等待與此鎖相關的給定條件的執行緒估計數。注意，因為隨時可能發生逾時和中斷，所以只能將估計值作為實際等待執行緒數的上邊界。此方法用於監視系統狀態，不用於同步控制。

參數：

condition - 條件

返回：

等待執行緒的估計數

拋出：

IllegalMonitorStateException - 如果沒有保持此鎖

IllegalArgumentException - 如果給定 condition 與此鎖無關

NullPointerException - 如果 condition 為 null

getWaitingThreads

protected Collection<Thread> getWaitingThreads(Condition condition)

返回一個 collection，它包含可能正在等待與此鎖相關給定條件的那些執行緒。因為在建構此結果的同時實際的執行緒 set 可能動態地變化，所以返回 collection 的元素只是盡力的估計值。所返回 collection 中的元素沒有特定的順序。此方法用於加快子類別的建構速度，提供更多的條件監視設施。

參數：

condition - 條件

返回：

執行緒的 collection

拋出：

IllegalMonitorStateException - 如果沒有保持此鎖

IllegalArgumentException - 如果給定 condition 與此鎖無關

NullPointerException - 如果 condition 為 null

toString

public String toString()

返回標識此鎖及其鎖定狀態的字元串。該狀態括在括號中，它包括字元串 "Unlocked" 或字元串 "Locked by"，後跟擁有執行緒的名稱。

覆寫：

類別 Object 中的 toString

返回：

標識此鎖及其鎖定狀態的字元串。