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
類別