ThreadPoolExecutor 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
一個 ExecutorService 會用可能的多個池執行緒執行每個提交任務，通常透過 Executors 工廠方法配置。
[Android.Runtime.Register("java/util/concurrent/ThreadPoolExecutor", DoNotGenerateAcw=true)]
public class ThreadPoolExecutor : Java.Util.Concurrent.AbstractExecutorService[<Android.Runtime.Register("java/util/concurrent/ThreadPoolExecutor", DoNotGenerateAcw=true)>]
type ThreadPoolExecutor = class
inherit AbstractExecutorService- 繼承
- 衍生
- 屬性
備註
一個 ExecutorService 會用可能的多個池執行緒執行每個提交任務，通常透過 Executors 工廠方法配置。
執行緒池解決了兩個不同的問題：它們通常在執行大量非同步任務時，因為每個任務調用的負擔較低，能提升效能;同時也提供一種綁定和管理執行任務集合時所消耗的資源（包括執行緒）的方法。 每個任務 ThreadPoolExecutor 還會維護一些基本統計數據，例如完成的任務數量。
為了在各種情境下都實用，這個類別提供了許多可調整參數和可擴充性鉤子。 然而，程式設計師被建議使用更方便 Executors 的工廠方法 Executors#newCachedThreadPool （無界執行緒池，具備自動執行緒回收）、 Executors#newFixedThreadPool （固定大小執行緒池）及 Executors#newSingleThreadExecutor （單一背景執行緒），這些方法預先設定了最常見的使用情境。 否則，手動設定和調整此類別時，請參考以下指南：
<DL>
<dt>核心與最大池大小</dt>
<dd>A ThreadPoolExecutor 會自動根據 corePoolSize（見#getPoolSize）和 maximumPoolSize（見#getCorePoolSize）設定的界限調整池大小（見#getMaximumPoolSize）。
當以方法 #execute(Runnable)提交新任務時，若執行執行緒少於 corePoolSize 執行緒，則會建立新執行緒來處理該請求，即使其他工作執行緒處於閒置狀態。 否則，如果執行的執行緒少於 maximumPoolSize 執行緒，則只有在隊列已滿時才會建立新執行緒來處理請求。 將 corePoolSize 與 maximumPoolSize 設定相同，即可建立固定大小的執行緒池。 透過將 maximumPoolSize 設定為幾乎無界的值，例如 Integer.MAX_VALUE，你就能讓池容納任意數量的同時進行任務。 通常，核心與最大池大小僅在建構時設定，但也可利用 #setCorePoolSize 和 #setMaximumPoolSize動態調整。
</dd>
<dt>按需建設</dt>
<dd>預設情況下，核心執行緒也會在新任務抵達時先建立並啟動，但此操作可透過方法 #prestartCoreThread 或 #prestartAllCoreThreads動態覆寫。 如果你建構的池子裡有非空佇列，你可能會想預先啟動執行緒。
</dd>
<dt>建立新執行緒</dt>
<dd>新執行緒是使用 ThreadFactory. 若未另行指定，則使用 a Executors#defaultThreadFactory ，該執行緒皆位於相同 ThreadGroup 且具有相同 NORM_PRIORITY 優先權且非守護程序狀態。 透過提供不同的 ThreadFactory，你可以更改執行緒的名稱、執行緒群組、優先權、守護進程狀態等。如果 ThreadFactory 在回傳 null newThread時無法建立執行緒，執行者會繼續執行，但可能無法執行任何任務。 執行緒應該擁有「modifyThread」 RuntimePermission這個功能。 若工作執行緒或其他使用池的其他執行緒未擁有此權限，服務可能會降級：組態變更可能無法及時生效，關機池也可能處於可終止但未完成的狀態。</dd>
<dt>保持生命時間</dt>
<dd>如果池目前有超過 corePoolSize 執行緒，過剩執行緒若閒置超過keepAliveTime，將會被終止（參見 #getKeepAliveTime(TimeUnit)）。 這提供了一種在池子未被積極使用時減少資源消耗的方法。 如果池子後期變得更活躍，將會建立新的執行緒。 此參數也可利用方法 #setKeepAliveTime(long, TimeUnit)動態變更。 使用一個 Long.MAX_VALUETimeUnit#NANOSECONDS 值，實際上會讓閒置執行緒在關機前永遠無法終止。 預設情況下，keep-alive 政策僅在執行緒數超過 corePoolSize 時適用，但 #allowCoreThreadTimeOut(boolean) 只要 keepAliveTime 值非零，則可將此逾時策略套用於核心執行緒。
</dd>
<dt>排隊</dt>
<dd>任何 BlockingQueue 都可以用來轉移和保存已提交的任務。 使用此佇列與池大小互動：
<UL>
<如果>執行的執行緒少於 corePoolSize，執行者總是偏好新增執行緒而非排隊。
<li>如果有 corePoolSize 或更多執行緒在執行，執行者總是偏好排隊請求，而不是新增執行緒。
<如果>請求無法排隊，則會建立一個新執行緒，除非超過最大池大小（maximumPoolSize），否則該任務將被拒絕。
</ul>
排隊有三種一般策略： <ol>
<直接><>交接。</em> 一個不錯的預設工作佇列選擇是SynchronousQueue將任務交接給執行緒，且不會自行持有。 此時，若任務無法立即執行執行緒，排隊嘗試將失敗，因此會建構新執行緒。 此策略避免在處理可能有內部依賴的請求集合時發生鎖機。 直接交接通常需要無限最大池大小，以避免拒絕新提交的任務。 這也承認當指令平均到達速度超過處理速度時，執行緒可能無限成長。
<li><em> 無限佇列。</em> 使用無界隊列（例如沒有預設容量的 a LinkedBlockingQueue ）會導致新任務在所有 corePoolSize 執行緒都忙碌時等待佇列。 因此，最多只會建立 corePoolSize 執行緒。 （因此 maximumPoolSize 的值不會產生影響。）當每個任務完全獨立於其他任務，任務無法影響彼此執行時，這可能適用;例如，在網頁伺服器中。 雖然這種排隊方式有助於平滑短暫的請求突發，但也承認當指令平均速度超過處理速度時，工作隊列可能無限成長。
<li><em>有界排隊。</em> 有界隊列（例如 an ArrayBlockingQueue）在有限 maximumPoolSizes 下可防止資源耗盡，但調整與控制可能較為困難。 佇列大小與最大池大小可能會相互取捨：使用大型佇列與較小池可減少 CPU 使用率、作業系統資源及上下文切換負擔，但可能導致人為降低吞吐量。 如果任務經常阻塞（例如I/O受限），系統可能會排程比你原本允許的更多執行緒的時間。 使用小型佇列通常需要較大的池大小，這會讓 CPU 保持更忙碌，但可能會遇到不可接受的排程開銷，進而降低吞吐量。
</ol>
</dd>
<dt>被拒絕的任務</dt>
<dd>在執行器關閉、執行器對最大執行緒與工作隊列容量使用有限界限且飽和時，方法中提交 #execute(Runnable) 的新任務會被 <em>拒絕</em> 。 無論哪種情況，該 execute 方法都會 RejectedExecutionHandler#rejectedExecution(Runnable, ThreadPoolExecutor) 調用其 RejectedExecutionHandler的方法。 提供四種預設的處理策略：
<進攻線>
<在>預設 ThreadPoolExecutor.AbortPolicy情況下，處理器在拒絕時拋出一個執行時間 RejectedExecutionException 。
<在>ThreadPoolExecutor.CallerRunsPolicy 中，呼叫自身的執行緒execute執行任務。 這提供了一個簡單的回饋控制機制，能減緩新任務提交的速度。
<在>ThreadPoolExecutor.DiscardPolicy ，無法執行的任務會直接被丟棄。 此政策僅針對極少數不依賴任務完成的情況設計。
<在>ThreadPoolExecutor.DiscardOldestPolicy 中，若執行器未關閉，工作佇列頂端的任務會被丟棄，然後執行會被重試（但執行可能會再次失敗，導致重複）。這種政策很少被接受。 幾乎所有情況下，你也應該取消任務，以在等待完成的元件中觸發異常，和/或記錄失敗，如文件所示 ThreadPoolExecutor.DiscardOldestPolicy 。
</ol>
也可以定義並使用其他類型的 RejectedExecutionHandler 類別。 此舉需要謹慎，尤其當政策設計僅在特定容量或排隊政策下運作時。
</dd>
<dt>鉤子方法</dt>
<dd>這個類別提供 protected 可 #beforeExecute(Thread, Runnable) 覆寫和 #afterExecute(Runnable, Throwable) 方法，這些方法會在每個任務執行前後被呼叫。 這些裝置可用來操控執行環境;例如，重新初始化 ThreadLocals、收集統計資料或新增日誌條目。 此外，該方法 #terminated 可被覆寫，以執行執行者完全終止後執行任何特殊處理。
若 hook、callback 或 BlockingQueue 方法拋出異常，內部工作執行緒可能會失敗、突然終止，甚至可能被替換。</dd>
<dt>排隊維修</dt>
<dd>方法 #getQueue() 允許存取工作佇列以進行監控與除錯。 強烈不建議將此方法用於其他用途。 提供兩種方法， #remove(Runnable)#purge 可用於協助大量待命任務取消時的儲存回收。</dd>
<dt>填海</dt>
<dd>一個已不再被<程式 em><> 且 em 已無剩餘執行緒的池，可以被回收（垃圾回收），而不會被明確關閉。 你可以設定一個池，讓所有未使用的執行緒最終都會死掉，方法是設定適當的保持存活時間、使用零核心執行緒的下限，和/或設定 #allowCoreThreadTimeOut(boolean)。
</dd>
</dl>
<b>擴充範例。</b> 此類別的大多數擴充覆蓋一個或多個受保護的掛鉤方法。 舉例來說，這裡有一個子職業加入了簡單的暫停/繼續功能：
{@code
class PausableThreadPoolExecutor extends ThreadPoolExecutor {
private boolean isPaused;
private ReentrantLock pauseLock = new ReentrantLock();
private Condition unpaused = pauseLock.newCondition();
public PausableThreadPoolExecutor(...) { super(...); }
protected void beforeExecute(Thread t, Runnable r) {
super.beforeExecute(t, r);
pauseLock.lock();
try {
while (isPaused) unpaused.await();
} catch (InterruptedException ie) {
t.interrupt();
} finally {
pauseLock.unlock();
}
}
public void pause() {
pauseLock.lock();
try {
isPaused = true;
} finally {
pauseLock.unlock();
}
}
public void resume() {
pauseLock.lock();
try {
isPaused = false;
unpaused.signalAll();
} finally {
pauseLock.unlock();
}
}
}}
已在1.5中新增。
的 java.util.concurrent.ThreadPoolExecutorJava 檔。
本頁部分內容為基於 Open Source Project 所創建與分享的作品，並依授權條款所描述的使用進行修改。
建構函式
| 名稱 | Description |
|---|---|
| ThreadPoolExecutor(Int32, Int32, Int64, TimeUnit, IBlockingQueue, IRejectedExecutionHandler) |
建立 |
| ThreadPoolExecutor(Int32, Int32, Int64, TimeUnit, IBlockingQueue, IThreadFactory, IRejectedExecutionHandler) |
建立 |
| ThreadPoolExecutor(Int32, Int32, Int64, TimeUnit, IBlockingQueue, IThreadFactory) |
建立 |
| ThreadPoolExecutor(Int32, Int32, Int64, TimeUnit, IBlockingQueue) |
建立 |
| ThreadPoolExecutor(IntPtr, JniHandleOwnership) |
用於建立 JNI 物件受管理表示的建構器;由執行時呼叫。 |
屬性
| 名稱 | Description |
|---|---|
| ActiveCount |
回傳正在執行任務的執行緒數量。 |
| Class |
回傳此 |
| CompletedTaskCount |
回傳已完成執行任務的大致總數。 |
| CorePoolSize |
回傳核心執行緒數。 -或- 設定執行緒的核心數量。 |
| Handle |
基礎Android實例的句柄。 (繼承來源 Object) |
| IsShutdown | |
| IsTerminated | |
| IsTerminating |
若該執行人正在終止或 |
| JniIdentityHashCode |
取得由互通執行時指派給此 Java 對等端的身份雜湊碼。 (繼承來源 Object) |
| JniManagedPeerState |
一個 |
| JniPeerMembers |
一個 |
| LargestPoolSize |
回傳有史以來同時進入池中最多的執行緒。 |
| MaximumPoolSize |
回傳最大允許執行緒數。 -或- 設定最大允許執行緒數。 |
| PeerReference |
取得這個 Java 節點的 JNI 物件參考。 (繼承來源 Object) |
| PoolSize |
回傳池中目前執行緒的數量。 |
| Queue |
回傳該執行者使用的任務佇列。 |
| RejectedExecutionHandler |
回傳目前無法執行任務的處理器。 -或- 為不可執行任務設定新的處理器。 |
| TaskCount |
回傳曾經排程執行過的任務總數。 |
| ThreadFactory |
回傳用於建立新執行緒的執行緒工廠。 -或- 設定用於建立新執行緒的執行緒工廠。 |
| ThresholdClass |
此 API 支援適用於 Android 的 Mono 基礎結構，並不適合直接從您的程式代碼使用。 |
| ThresholdType |
此 API 支援適用於 Android 的 Mono 基礎結構，並不適合直接從您的程式代碼使用。 |
方法
| 名稱 | Description |
|---|---|
| AfterExecute(IRunnable, Throwable) |
執行完成給定 Runnable 後會呼叫的方法。 |
| AllowCoreThreadTimeOut(Boolean) |
設定政策，規定若核心執行緒在保持有效時間內無任務抵達，是否可逾時終止，若有新任務抵達，則可重新啟用。 |
| AllowsCoreThreadTimeOut() |
若此池允許核心執行緒逾時，則在 keepAlive 時間內無任務抵達時終止，若有新任務到達，則會被替換。 |
| AwaitTermination(Int64, TimeUnit) | |
| AwaitTerminationAsync(Int64, TimeUnit) |
一個 |
| BeforeExecute(Thread, IRunnable) |
在執行給定執行緒中執行給定 Runnable 之前，呼叫的方法。 |
| Clone() |
建立並回傳此物件的副本。 (繼承來源 Object) |
| Construct(JniObjectReference, JniObjectReferenceOptions) |
一個 |
| Dispose() |
釋放該 Java 節點所持有的資源。 (繼承來源 Object) |
| Dispose(Boolean) |
釋放該 Java 節點所持有的資源。 (繼承來源 Object) |
| DisposeUnlessReferenced() |
一個 |
| Equals(Object) |
一個 |
| Equals(Object) |
表示是否有其他物體「等同」於此物。 (繼承來源 Object) |
| Execute(IRunnable) |
未來某個時候執行該任務。 |
| GetHashCode() |
回傳物件的雜湊碼值。 (繼承來源 Object) |
| GetKeepAliveTime(TimeUnit) |
回傳執行緒保持存活時間，也就是執行緒在終止前可閒置的時間。 |
| InvokeAll(ICollection, Int64, TimeUnit) |
執行指定任務，並在所有任務完成或超時結束時（以先發生者為準）返回一份保存狀態與結果的未來清單。 (繼承來源 AbstractExecutorService) |
| InvokeAll(ICollection) |
執行指定任務，完成後回傳一份包含狀態與結果的未來清單。 (繼承來源 AbstractExecutorService) |
| InvokeAny(ICollection, Int64, TimeUnit) |
執行給定任務，若有任務在逾時期內完成，則回傳成功完成的任務結果（即未拋出例外）。 (繼承來源 AbstractExecutorService) |
| InvokeAny(ICollection) |
執行給定任務，若有任務成功完成（即未拋出例外），則回傳結果。 (繼承來源 AbstractExecutorService) |
| JavaFinalize() |
已淘汰.
當垃圾回收判定該物件不再有相關參考時，由垃圾回收器呼叫。 (繼承來源 Object) |
| NewTaskFor(ICallable) |
回傳給定可呼叫任務的 a |
| NewTaskFor(IRunnable, Object) |
回傳給定可執行且預設值的 a |
| Notify() |
喚醒一個正在該物件監視器上等待的執行緒。 (繼承來源 Object) |
| NotifyAll() |
喚醒所有等待該物件監視器的執行緒。 (繼承來源 Object) |
| PrestartAllCoreThreads() |
啟動所有核心執行緒，導致它們閒置等待工作。 |
| PrestartCoreThread() |
啟動核心執行緒，導致它閒置等待工作。 |
| Purge() |
嘗試從工作佇列中移除所有 |
| Remove(IRunnable) |
如果該任務存在，會從執行者的內部佇列中移除，因此如果任務尚未啟動，則不會執行。 |
| SetHandle(IntPtr, JniHandleOwnership) |
設定 Handle 屬性。 (繼承來源 Object) |
| SetKeepAliveTime(Int64, TimeUnit) |
設定執行緒保持存活時間，也就是執行緒在終止前可閒置的時間。 |
| SetPeerReference(JniObjectReference, JniObjectReferenceOptions) |
一個 |
| Shutdown() |
啟動有序關機，執行先前提交的任務，但不再接受新的任務。 |
| ShutdownNow() |
嘗試停止所有正在執行的任務，停止等待任務的處理，並回傳等待執行的任務清單。 |
| Submit(ICallable) |
提交一個值回傳任務以供執行，並回傳一個代表該任務待處理結果的未來。 (繼承來源 AbstractExecutorService) |
| Submit(IRunnable, Object) |
提交一個可執行的任務，並回傳代表該任務的 Future。 (繼承來源 AbstractExecutorService) |
| Submit(IRunnable) |
提交一個可執行的任務，並回傳代表該任務的 Future。 (繼承來源 AbstractExecutorService) |
| Terminated() |
當執行人終止時會被呼叫的方法。 |
| ToArray<T>() |
從這個 Java 陣列包裝器建立一個受管理陣列。 (繼承來源 Object) |
| ToString() |
回傳物件的字串表示。 (繼承來源 Object) |
| UnregisterFromRuntime() |
將此 Java 節點從互通執行時中取消註冊。 (繼承來源 Object) |
| Wait() |
導致目前執行緒等待被喚醒，通常是透過 <em>通知</><em 或 em>中斷</em> 來喚醒。 (繼承來源 Object) |
| Wait(Int64, Int32) |
會讓目前執行緒等待喚醒，通常是透過 <em>通知</><em 或 em>中斷</em>，或是經過一定的真實時間。 (繼承來源 Object) |
| Wait(Int64) |
會讓目前執行緒等待喚醒，通常是透過 <em>通知</><em 或 em>中斷</em>，或是經過一定的真實時間。 (繼承來源 Object) |
明確介面實作
| 名稱 | Description |
|---|---|
| IJavaPeerable.Disposed() |
一個 |
| IJavaPeerable.Finalized() |
一個 |
| IJavaPeerable.JniObjectReferenceControlBlock |
一個 |
| IJavaPeerable.SetJniIdentityHashCode(Int32) |
一個 |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) |
一個 |
| IJavaPeerable.SetPeerReference(JniObjectReference) |
一個 |
| IJavaPeerable.UnregisterFromRuntime() |
一個 |
擴充方法
| 名稱 | Description |
|---|---|
| AwaitTerminationAsync(IExecutorService, Int64, TimeUnit) |
一個 |
| GetJniTypeName(IJavaPeerable) |
取得實例 |
| InvokeAnyAsync(IExecutorService, ICollection, Int64, TimeUnit) |
一個 |
| InvokeAnyAsync(IExecutorService, ICollection) |
一個 |
| JavaAs<TResult>(IJavaPeerable) |
試著強制 |
| JavaCast<TResult>(IJavaObject) |
執行 Android 執行時間檢查的類型轉換。 |
| JavaCast<TResult>(IJavaObject) |
一個 |
| TryJavaCast<TResult>(IJavaPeerable, TResult) |
試著強制 |