Класс CThreadPool
Этот класс предоставляет пул рабочих потоков, обрабатывающих очередь рабочих элементов.
Синтаксис
template <class Worker, class ThreadTraits = DefaultThreadTraits>
class CThreadPool : public IThreadPoolConfig
Параметры
Рабочая роль
Класс, соответствующий архетипу рабочей роли, предоставляющий код, используемый для обработки рабочих элементов в очереди в пуле потоков.
ThreadTraits
Класс, предоставляющий функцию, используемую для создания потоков в пуле.
Участники
Открытые конструкторы
| Имя | Описание |
|---|---|
| CThreadPool::CThreadPool | Конструктор пула потоков. |
| CThreadPool::~CThreadPool | Деструктор пула потоков. |
Открытые методы
| Имя | Описание |
|---|---|
| CThreadPool::AddRef | IUnknown::AddRefРеализация . |
| CThreadPool::GetNumThreads | Вызовите этот метод, чтобы получить количество потоков в пуле. |
| CThreadPool::GetQueueHandle | Вызовите этот метод, чтобы получить дескриптор порта завершения ввода-вывода, используемого для очередей рабочих элементов. |
| CThreadPool::GetSize | Вызовите этот метод, чтобы получить количество потоков в пуле. |
| CThreadPool::GetTimeout | Вызовите этот метод, чтобы получить максимальное время в миллисекундах, которое пул потоков будет ожидать завершения работы потока. |
| CThreadPool::Initialize | Вызовите этот метод для инициализации пула потоков. |
| CThreadPool::QueryInterface | IUnknown::QueryInterfaceРеализация . |
| CThreadPool::QueueRequest | Вызовите этот метод для очереди рабочего элемента, который будет обрабатываться потоком в пуле. |
| CThreadPool::Release | IUnknown::ReleaseРеализация . |
| CThreadPool::SetSize | Вызовите этот метод, чтобы задать количество потоков в пуле. |
| CThreadPool::SetTimeout | Вызовите этот метод, чтобы задать максимальное время в миллисекундах, которое пул потоков будет ожидать завершения работы потока. |
| CThreadPool::Shutdown | Вызовите этот метод, чтобы завершить работу пула потоков. |
Замечания
Потоки в пуле создаются и уничтожаются при инициализации, изменении размера или завершении работы пула. Экземпляр рабочей роли класса будет создан на стеке каждого рабочего потока в пуле. Каждый экземпляр будет жить в течение всего времени существования потока.
Сразу после создания потока Рабочая роль::Initialize будет вызываться к объекту, связанному с этим потоком. Непосредственно перед уничтожением потока будет вызываться рабочая роль:Terminate . Оба метода должны принимать void* аргумент. Значение этого аргумента передается в пул потоков через параметр pvWorkerParam cThreadPool ::Initialize.
При наличии рабочих элементов в очереди и рабочих потоках, доступных для работы, рабочий поток извлекает элемент из очереди и вызывает Execute метод объекта Worker для этого потока. Затем три элемента передаются в метод: элемент из очереди, тот же pvWorkerParam , который передается в Worker:: Initialize и Worker:: Terminateи указатель на структуру OVERLAPPED , используемую для очереди портов завершения ввода-вывода.
Рабочий класс объявляет тип элементов, которые будут помещены в пул потоков, предоставляя типдифакт, Worker:: RequestType. Этот тип должен иметь возможность приведения и от ULONG_PTR.
Примером рабочего класса является класс 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
Вызовите этот метод, чтобы получить дескриптор порта завершения ввода-вывода, используемого для очередей рабочих элементов.
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. В этой ситуации метод вернет HRESULT, соответствующий WAIT_TIMEOUT, и ожидается завершение работы.
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 в любом потоке, который не завершился. Этот метод вызывается автоматически из деструктора класса.