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 クラスのインスタンスは、プール内の各ワーカー スレッドのスタック上に作成されます。 各インスタンスは、スレッドの有効期間にわたって存続します。
スレッドが作成されるとすぐに、そのスレッドに関連付けられているオブジェクトで Worker::Initialize が呼び出されます。 スレッドが破棄される直前に、Worker::Terminate が呼び出されます。 両方のメソッドで void* 引数を受け入れる必要があります。 この引数の値は、CThreadPool::Initialize の pvWorkerParam パラメーターを通じてスレッド プールに渡されます。
キューに作業項目があり、ワーカー スレッドを作業で使用できる場合、ワーカー スレッドではキューから項目をプルし、そのスレッドの Worker オブジェクトの Execute メソッドを呼び出します。 その後、3 つの項目がメソッドに渡されます。つまり、キューからの項目、Worker:: Initialize および Worker:: Terminate に渡されるものと同じ pvWorkerParam、および IO 完了ポート キューに使用される OVERLAPPED 構造体へのポインターです。
Worker クラスでは、typedef (Worker:: RequestType) を指定することによって、スレッド プールでキューに入れられる項目の型を宣言します。 この型は、ULONG_PTR との間でキャストできる必要があります。
Worker クラスの例として、CNonStatelessWorker クラスがあります。
継承階層
IUnknown
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
[出力] 成功した場合、プール内のスレッドの数を受け取る変数のアドレス。
戻り値
成功した場合は S_OK、失敗した場合はエラー HRESULT を返します。
CThreadPool::GetTimeout
スレッド プールがスレッドのシャットダウンを待機する最大時間 (ミリ秒) を取得するには、このメソッドを呼び出します。
HRESULT STDMETHODCALLTYPE GetTimeout(DWORD* pdwMaxWait) throw();
パラメーター
pdwMaxWait
[出力] 成功した場合、スレッド プールがスレッドのシャットダウンを待機する最大時間 (ミリ秒) を受け取る変数のアドレス。
戻り値
成功した場合は 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 メソッドに渡される worker パラメーター。
nNumThreads
プール内の要求されたスレッド数。
nNumThreads が負の場合、その絶対値にマシン内のプロセッサの数が乗算され、スレッドの総数が取得されます。
nNumThreads が 0 の場合、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 が 0 の場合、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 は、1 つのスレッドがシャットダウンするまでプールが待機する時間であることに注意してください。 プールから複数のスレッドを削除するのにかかる可能性がある最大時間は、dwMaxWait にスレッド数を乗算した時間よりもわずかに小さい場合があります。
CThreadPool::Shutdown
スレッド プールをシャットダウンするには、このメソッドを呼び出します。
void Shutdown(DWORD dwMaxWait = 0) throw();
パラメーター
dwMaxWait
スレッド プールがスレッドのシャットダウンを待機する要求された最大時間 (ミリ秒単位)。 0 が指定されているか、値が指定されていない場合、このメソッドでは CThreadPool::SetTimeout によって設定されたタイムアウトを使用します。
解説
このメソッドでは、プール内のすべてのスレッドにシャットダウン要求をポストします。 タイムアウトになると、このメソッドでは、終了しなかったスレッドに対して TerminateThread を呼び出します。 このメソッドは、クラスのデストラクターから自動的に呼び出されます。