Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Замечание
Библиотека активных шаблонов (ATL) продолжает поддерживаться. Однако мы больше не добавляем функции или обновляем документацию.
Этот класс предоставляет пул рабочих потоков, обрабатывающих очередь рабочих элементов.
Синтаксис
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 , используемую для очереди портов завершения ввода-вывода.
Рабочий 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 SetSize(int 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 в любом потоке, который не завершился. Этот метод вызывается автоматически из деструктора класса.