共用方式為

CThreadPool 類別

  • 發行項

這個類別提供處理工作專案佇列的背景工作執行緒集區。

語法

template <class Worker, class ThreadTraits = DefaultThreadTraits>
class CThreadPool : public IThreadPoolConfig

參數

工人
符合背景工作原型 的 類別，提供用來處理執行緒集區上佇列的工作專案的程式碼。

ThreadTraits
類別，提供用來在集區中建立執行緒的函式。

成員

公用建構函式

名稱 描述
CThreadPool：：CThreadPool 執行緒集區的建構函式。
CThreadPool：：~CThreadPool 執行緒集區的解構函式。

公用方法

名稱 描述
CThreadPool：：AddRef 的實作 IUnknown::AddRef 。
CThreadPool：：GetNumThreads 呼叫此方法以取得集區中的執行緒數目。
CThreadPool：：GetQueueHandle 呼叫這個方法，以取得用來將工作專案排入佇列之 IO 完成埠的控制碼。
CThreadPool：：GetSize 呼叫此方法以取得集區中的執行緒數目。
CThreadPool：：GetTimeout 呼叫這個方法，以毫秒為單位取得執行緒集區等候執行緒關閉的最大時間。
CThreadPool：：Initialize 呼叫此方法以初始化執行緒集區。
CThreadPool：：QueryInterface 的實作 IUnknown::QueryInterface 。
CThreadPool：：QueueRequest 呼叫這個方法，將工作專案排入佇列，以由集區中的執行緒。
CThreadPool：：Release 的實作 IUnknown::Release 。
CThreadPool：：SetSize 呼叫此方法以設定集區中的執行緒數目。
CThreadPool：：SetTimeout 呼叫這個方法，以毫秒為單位設定執行緒集區等候執行緒關閉的最大時間。
CThreadPool：：Shutdown 呼叫此方法以關閉執行緒集區。

備註

集區中的執行緒會在集區初始化、調整大小或關閉時建立和終結。 背景工作 角色類別 的實例將會建立在集區中每個背景工作執行緒的堆疊上。 每個實例都會存留執行緒的存留期。

建立執行緒之後， 會在與該執行緒相關聯的物件上呼叫 Worker ：： Initialize 。 緊接線上程解構之前， 將會呼叫 Worker ：： Terminate 。 這兩種方法都必須接受 自 void* 變數。 這個引數的值會透過 CThreadPool：：Initialize 的 pvWorkerParam 參數傳遞至執行緒集區 。

當佇列中有工作專案和背景工作執行緒可供工作使用時，背景工作執行緒會從佇列提取專案，並呼叫 Execute 該執行緒的背景 工作 物件方法。 接著會將三個專案傳遞至 方法：佇列中的專案、傳遞至 Worker：： Initialize 和 Worker ：： Terminate 的相同 pvWorkerParam 專案，以及 IO 完成埠佇列所使用的 OVERLAPPED 結構的指標 。

Worker 類別會藉由提供 typedef： ： 來宣告執行緒集區上佇列的專案類型。 RequestType 此類型必須能夠轉換至ULONG_PTR和轉換。

Worker 類別的 範例是 CNonStatelessWorker 類別 。

繼承階層架構

IUnknown

IThreadPoolConfig

CThreadPool

需求

標頭： atlutil.h

CThreadPool：：AddRef

的實作 IUnknown::AddRef 。

ULONG STDMETHODCALLTYPE AddRef() throw();

傳回值

一律會傳回 1。

備註

這個類別不會使用參考計數來實作存留期控制。

CThreadPool：：CThreadPool

執行緒集區的建構函式。

CThreadPool() throw();

備註

將逾時值初始化為ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT。 預設時間為 36 秒。 如有必要，您可以先定義這個符號的正整數值，再包含 atlutil.h。

CThreadPool：：~CThreadPool

執行緒集區的解構函式。

~CThreadPool() throw();

備註

呼叫 CThreadPool：：Shutdown 。

CThreadPool：：GetNumThreads

呼叫此方法以取得集區中的執行緒數目。

int GetNumThreads() throw();

傳回值

傳回集區中的執行緒數目。

CThreadPool：：GetQueueHandle

呼叫這個方法，以取得用來將工作專案排入佇列之 IO 完成埠的控制碼。

HANDLE GetQueueHandle() throw();

傳回值

如果執行緒集區尚未初始化，則傳回佇列控制碼或 Null。

CThreadPool：：GetSize

呼叫此方法以取得集區中的執行緒數目。

HRESULT STDMETHODCALLTYPE GetSize(int* pnNumThreads) throw();

參數

pnNumThreads
[out]成功時接收集區中線程數目的變數位址。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

CThreadPool：：GetTimeout

呼叫這個方法，以毫秒為單位取得執行緒集區等候執行緒關閉的最大時間。

HRESULT STDMETHODCALLTYPE GetTimeout(DWORD* pdwMaxWait) throw();

參數

pdwMaxWait
[out]成功時，執行緒集區將等候執行緒關閉的最大時間，以毫秒為單位來接收變數位址。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

如果未提供任何其他值給該方法，CThreadPool：：Shutdown 就會使用此 逾時值。

CThreadPool：：Initialize

呼叫此方法以初始化執行緒集區。

HRESULT Initialize(
    void* pvWorkerParam = NULL,
    int nNumThreads = 0,
    DWORD dwStackSize = 0,
    HANDLE hCompletion = INVALID_HANDLE_VALUE) throw();

參數

pvWorkerParam
要傳遞至背景工作執行緒物件的 Initialize 、 Execute 和 Terminate 方法的背景工作參數。

nNumThreads
集區中要求的執行緒數目。

如果 nNumThreads 為負數，其絕對值會乘以機器中的處理器數目，以取得執行緒總數。

如果 nNumThreads 為零，ATLS_DEFAULT_THREADSPERPROC將會乘以機器中的處理器數目，以取得執行緒總數。 預設值是每個處理器 2 個執行緒。 如有必要，您可以先定義這個符號的正整數值，再包含 atlutil.h。

dwStackSize
集區中每個執行緒的堆疊大小。

hCompletion
要與完成埠產生關聯的 物件控制碼。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

CThreadPool：：QueryInterface

的實作 IUnknown::QueryInterface 。

HRESULT STDMETHODCALLTYPE QueryInterface(REFIID riid, void** ppv) throw();

備註

此類別的物件可以成功查詢 IUnknown 和 IThreadPoolConfig 介面。

CThreadPool：：QueueRequest

呼叫這個方法，將工作專案排入佇列，以由集區中的執行緒。

BOOL QueueRequest(Worker::RequestType request) throw();

參數

request
要排入佇列的要求。

傳回值

在成功時傳回 TRUE，失敗時傳回 FALSE。

備註

這個方法會將工作專案新增至佇列。 集區中的執行緒會依照接收的順序，從佇列中挑選項目。

CThreadPool：：Release

的實作 IUnknown::Release 。

ULONG STDMETHODCALLTYPE Release() throw();

傳回值

一律會傳回 1。

備註

這個類別不會使用參考計數來實作存留期控制。

CThreadPool：：SetSize

呼叫此方法以設定集區中的執行緒數目。

HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw();

參數

nNumThreads
集區中要求的執行緒數目。

如果 nNumThreads 為負數，其絕對值會乘以機器中的處理器數目，以取得執行緒總數。

如果 nNumThreads 為零，ATLS_DEFAULT_THREADSPERPROC將會乘以機器中的處理器數目，以取得執行緒總數。 預設值是每個處理器 2 個執行緒。 如有必要，您可以先定義這個符號的正整數值，再包含 atlutil.h。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

如果指定的執行緒數目小於集區中目前線程數目，物件會將關機訊息放在佇列上，以便由等候的執行緒挑選。 當等候的執行緒將訊息從佇列中提取時，它會通知執行緒集區並結束執行緒程式。 此程式會重複執行，直到集區中的執行緒數目達到指定的數目，或直到 GetTimeout SetTimeout / 指定的 期間內沒有結束任何執行緒為止。 在此情況下，方法會傳回對應至WAIT_TIMEOUT的 HRESULT，並解除擱置的關機訊息。

CThreadPool：：SetTimeout

呼叫這個方法，以毫秒為單位設定執行緒集區等候執行緒關閉的最大時間。

HRESULT STDMETHODCALLTYPE SetTimeout(DWORD dwMaxWait) throw();

參數

dwMaxWait
要求的最大時間，以毫秒為單位，執行緒集區會等待中的執行緒關閉。

傳回值

傳回成功時S_OK，或在失敗時傳回錯誤 HRESULT。

備註

逾時會初始化為ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT。 預設時間為 36 秒。 如有必要，您可以先定義這個符號的正整數值，再包含 atlutil.h。

請注意， dwMaxWait 是集區等候單一線程關閉的時間。 從集區中移除多個執行緒所花費的時間上限可能會略低於 dwMaxWait 乘以執行緒數目。

CThreadPool：：Shutdown

呼叫此方法以關閉執行緒集區。

void Shutdown(DWORD dwMaxWait = 0) throw();

參數

dwMaxWait
要求的最大時間，以毫秒為單位，執行緒集區會等待中的執行緒關閉。 如果提供 0 或未提供任何值，這個方法將會使用 CThreadPool：：SetTimeout 所設定的 逾時。

備註

此方法會將關機要求張貼至集區中的所有線程。 如果逾時過期，此方法會在未結束的任何執行緒上呼叫 TerminateThread 。 這個方法會自動從 類別的解構函式呼叫。

另請參閱

IThreadPoolConfig 介面
DefaultThreadTraits
類別