Klasa CThreadPool

Ta klasa udostępnia pulę wątków roboczych, które przetwarzają kolejkę elementów roboczych.

Składnia

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

Parametry

Pracownik
Klasa zgodna z archetypem procesu roboczego dostarczającym kod używany do przetwarzania elementów roboczych znajdujących się w kolejce w puli wątków.

ThreadTraits
Klasa udostępniająca funkcję używaną do tworzenia wątków w puli.

Elementy członkowskie

Konstruktory publiczne

Metody publiczne

Uwagi

Wątki w puli są tworzone i niszczone po zainicjowaniu, zmianie rozmiaru lub zamknięciu puli. Wystąpienie klasy Worker zostanie utworzone na stosie każdego wątku roboczego w puli. Każde wystąpienie będzie aktywne przez cały okres istnienia wątku.

Natychmiast po utworzeniu wątku proces roboczy:Initialize zostanie wywołany w obiekcie skojarzonym z tym wątkiem. Bezpośrednio przed zniszczeniem wątku, Worker::Terminate zostanie wywołany. Obie metody muszą zaakceptować void* argument. Wartość tego argumentu jest przekazywana do puli wątków za pośrednictwem parametru pvWorkerParam CThreadPool::Initialize.

Gdy istnieją elementy robocze w kolejce i wątki procesu roboczego dostępne do pracy, wątek procesu roboczego ściągnie element z kolejki i wywoła Execute metodę obiektu Worker dla tego wątku. Trzy elementy są następnie przekazywane do metody: element z kolejki, ten sam pvWorkerParam przekazany do procesu roboczego:: i Worker:: TerminateInitialize oraz wskaźnik do struktury OVERLAPPED używanej dla kolejki portów uzupełniania operacji we/wy.

Klasa Proces roboczy deklaruje typ elementów, które zostaną w kolejce w puli wątków, podając definicję typów, Worker:: RequestType. Ten typ musi być w stanie rzutować do i z ULONG_PTR.

Przykładem klasy Worker jest klasa CNonStatelessWorker.

Hierarchia dziedziczenia

IUnknown

IThreadPoolConfig

CThreadPool

Wymagania

Nagłówek: atlutil.h

CThreadPool::AddRef

Implementacja .IUnknown::AddRef

ULONG STDMETHODCALLTYPE AddRef() throw();

Wartość zwracana

Zawsze zwraca wartość 1.

Uwagi

Ta klasa nie implementuje kontrolki okresu istnienia przy użyciu zliczania odwołań.

CThreadPool::CThreadPool

Konstruktor puli wątków.

CThreadPool() throw();

Uwagi

Inicjuje wartość limitu czasu na ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. Domyślny czas to 36 sekund. W razie potrzeby można zdefiniować własną dodatnią wartość całkowitą dla tego symbolu przed dołączeniem atlutil.h.

CThreadPool::~CThreadPool

Destruktor puli wątków.

~CThreadPool() throw();

Uwagi

Wywołuje klasę CThreadPool::Shutdown.

CThreadPool::GetNumThreads

Wywołaj tę metodę, aby uzyskać liczbę wątków w puli.

int GetNumThreads() throw();

Wartość zwracana

Zwraca liczbę wątków w puli.

CThreadPool::GetQueueHandle

Wywołaj tę metodę, aby uzyskać dojście do portu ukończenia operacji we/wy używanego do kolejkowania elementów roboczych.

HANDLE GetQueueHandle() throw();

Wartość zwracana

Zwraca uchwyt kolejki lub wartość NULL, jeśli pula wątków nie została zainicjowana.

CThreadPool::GetSize

Wywołaj tę metodę, aby uzyskać liczbę wątków w puli.

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

Parametry

pnNumThreads
[out] Adres zmiennej, która w przypadku powodzenia otrzymuje liczbę wątków w puli.

Wartość zwracana

Zwraca S_OK powodzenia lub błąd HRESULT w przypadku niepowodzenia.

CThreadPool::GetTimeout

Wywołaj tę metodę, aby uzyskać maksymalny czas w milisekundach, który pula wątków będzie czekać na zamknięcie wątku.

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

Parametry

pdwMaxWait
[out] Adres zmiennej, która po powodzeniu otrzymuje maksymalny czas w milisekundach, który pula wątków będzie czekać na zamknięcie wątku.

Wartość zwracana

Zwraca S_OK powodzenia lub błąd HRESULT w przypadku niepowodzenia.

Uwagi

Ta wartość limitu czasu jest używana przez klasę CThreadPool::Shutdown , jeśli żadna inna wartość nie jest dostarczana do tej metody.

CThreadPool::Initialize

Wywołaj tę metodę, aby zainicjować pulę wątków.

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

Parametry

pvWorkerParam
Parametr procesu roboczego, który ma zostać przekazany do obiektów Initializewątku roboczego , Executei Terminate metod.

nNumThreads
Żądana liczba wątków w puli.

Jeśli nNumThreads jest ujemna , jego wartość bezwzględna zostanie pomnożona przez liczbę procesorów na maszynie w celu uzyskania całkowitej liczby wątków.

Jeśli nNumThreads ma wartość zero, ATLS_DEFAULT_THREADSPERPROC zostanie pomnożona przez liczbę procesorów na maszynie w celu uzyskania całkowitej liczby wątków. Wartość domyślna to 2 wątki na procesor. W razie potrzeby można zdefiniować własną dodatnią wartość całkowitą dla tego symbolu przed dołączeniem atlutil.h.

dwStackSize
Rozmiar stosu dla każdego wątku w puli.

hCompletion
Uchwyt obiektu do skojarzenia z portem ukończenia.

Wartość zwracana

Zwraca S_OK powodzenia lub błąd HRESULT w przypadku niepowodzenia.

CThreadPool::QueryInterface

Implementacja .IUnknown::QueryInterface

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

Uwagi

Obiekty tej klasy można pomyślnie odpytować dla IUnknown interfejsów IThreadPoolConfig.

CThreadPool::QueueRequest

Wywołaj tę metodę, aby w kolejce element roboczy był obsługiwany przez wątek w puli.

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

Parametry

prosić
Żądanie do kolejkowania.

Wartość zwracana

Zwraca wartość TRUE w przypadku powodzenia, FALSE w przypadku niepowodzenia.

Uwagi

Ta metoda dodaje element roboczy do kolejki. Wątki w puli pobierają elementy z kolejki w kolejności, w jakiej są odbierane.

CThreadPool::Release

Implementacja .IUnknown::Release

ULONG STDMETHODCALLTYPE Release() throw();

Wartość zwracana

Zawsze zwraca wartość 1.

Uwagi

Ta klasa nie implementuje kontrolki okresu istnienia przy użyciu zliczania odwołań.

CThreadPool::SetSize

Wywołaj tę metodę, aby ustawić liczbę wątków w puli.

HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw();

Parametry

nNumThreads
Żądana liczba wątków w puli.

Jeśli nNumThreads jest ujemna , jego wartość bezwzględna zostanie pomnożona przez liczbę procesorów na maszynie w celu uzyskania całkowitej liczby wątków.

Jeśli nNumThreads ma wartość zero, ATLS_DEFAULT_THREADSPERPROC zostanie pomnożona przez liczbę procesorów na maszynie w celu uzyskania całkowitej liczby wątków. Wartość domyślna to 2 wątki na procesor. W razie potrzeby można zdefiniować własną dodatnią wartość całkowitą dla tego symbolu przed dołączeniem atlutil.h.

Wartość zwracana

Zwraca S_OK powodzenia lub błąd HRESULT w przypadku niepowodzenia.

Uwagi

Jeśli określona liczba wątków jest mniejsza niż liczba wątków znajdujących się obecnie w puli, obiekt umieszcza komunikat zamknięcia w kolejce, który ma zostać odebrany przez wątek oczekiwania. Gdy wątek oczekujący ściąga komunikat z kolejki, powiadamia pulę wątków i zamyka procedurę wątku. Ten proces jest powtarzany do momentu osiągnięcia określonej liczby wątków w puli lub do momentu zakończenia wątku w przedziale określonym przez parametr GetTimeout SetTimeout/ . W takiej sytuacji metoda zwróci wartość HRESULT odpowiadającą WAIT_TIMEOUT, a oczekujący komunikat zamknięcia zostanie anulowany.

CThreadPool::SetTimeout

Wywołaj tę metodę, aby ustawić maksymalny czas w milisekundach, który pula wątków będzie czekać na zamknięcie wątku.

HRESULT STDMETHODCALLTYPE SetTimeout(DWORD dwMaxWait) throw();

Parametry

dwMaxWait
Żądany maksymalny czas w milisekundach, który pula wątków będzie czekać na zamknięcie wątku.

Wartość zwracana

Zwraca S_OK powodzenia lub błąd HRESULT w przypadku niepowodzenia.

Uwagi

Limit czasu jest inicjowany do ATLS_DEFAULT_THREADPOOLSHUTDOWNTIMEOUT. Domyślny czas to 36 sekund. W razie potrzeby można zdefiniować własną dodatnią wartość całkowitą dla tego symbolu przed dołączeniem atlutil.h.

Należy pamiętać, że dwMaxWait to czas oczekiwania puli na zamknięcie pojedynczego wątku. Maksymalny czas potrzebny do usunięcia wielu wątków z puli może być nieco krótszy niż dwMaxWait pomnożony przez liczbę wątków.

CThreadPool::Shutdown

Wywołaj tę metodę, aby zamknąć pulę wątków.

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

Parametry

dwMaxWait
Żądany maksymalny czas w milisekundach, który pula wątków będzie czekać na zamknięcie wątku. Jeśli zostanie podana wartość 0 lub żadna, ta metoda użyje limitu czasu ustawionego przez klasę CThreadPool::SetTimeout.

Uwagi

Ta metoda publikuje żądanie zamknięcia do wszystkich wątków w puli. Jeśli limit czasu wygaśnie, ta metoda wywoła metodę TerminateThread w każdym wątku, który nie zakończył działania. Ta metoda jest wywoływana automatycznie z destruktora klasy.

Zobacz też

Interfejs IThreadPoolConfig
DefaultThreadTraits
Klasy