Функция CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Статья
03/08/2023

Освобождает членов указанной группы очистки, ожидает завершения всех функций обратного вызова и при необходимости отменяет все оставшиеся функции обратного вызова.

Синтаксис

void CloseThreadpoolCleanupGroupMembers(
  [in, out]           PTP_CLEANUP_GROUP ptpcg,
  [in]                BOOL              fCancelPendingCallbacks,
  [in, out, optional] PVOID             pvCleanupContext
);

Параметры

[in, out] ptpcg

Указатель на структуру TP_CLEANUP_GROUP , определяющую группу очистки. Функция CreateThreadpoolCleanupGroup возвращает этот указатель.

[in] fCancelPendingCallbacks

Если этот параметр имеет значение TRUE, функция отменяет невыполненные обратные вызовы, которые еще не запущены. Если этот параметр имеет значение FALSE, функция ожидает завершения незавершенных функций обратного вызова.

[in, out, optional] pvCleanupContext

Определяемые приложением данные, передаваемые в функцию обратного вызова группы очистки приложения. Функцию обратного вызова можно указать при вызове SetThreadpoolCallbackCleanupGroup.

Возвращаемое значение

None

Remarks

Функция CloseThreadpoolCleanupGroupMembers упрощает очистку объектов обратного вызова пула потоков, освобождая в одной операции все рабочие объекты, объекты ожидания и объекты таймера, которые являются членами группы очистки. Объект становится членом группы очистки при создании объекта с помощью среды обратного вызова threadpool, указанной при создании группы очистки. Дополнительные сведения см. в разделе CreateThreadpoolCleanupGroup.

Функция CloseThreadpoolCleanupGroupMembers блокируется до тех пор, пока не будут завершены все выполняемые в данный момент функции обратного вызова. Если fCancelPendingCallbacks имеет значение TRUE, необработанные обратные вызовы отменяются; в противном случае функция блокируется до тех пор, пока не будут завершены все невыполненные обратные вызовы. После возврата функции CloseThreadpoolCleanupGroupMembers приложение не должно использовать объекты, которые были членами группы очистки на момент вызова CloseThreadpoolCleanupGroupMembers . Кроме того, приложение не должно освобождать объекты по отдельности путем вызова такой функции, как CloseThreadpoolWork, так как объекты уже освобождены.

Функция CloseThreadpoolCleanupGroupMembers не закрывает саму группу очистки. Вместо этого группа очистки сохраняется до вызова функции CloseThreadpoolCleanupGroup . Кроме того, закрытие группы очистки не влияет на связанную среду обратного вызова пула потоков. Среда обратного вызова сохраняется до тех пор, пока она не будет уничтожена путем вызова DestroyThreadpoolEnvironment.

Пока группа очистки сохраняется, в группу очистки добавляются новые объекты, созданные с помощью среды обратного вызова пула потоков, связанной с группой очистки. Это позволяет приложению повторно использовать группу очистки. Однако это может привести к ошибкам, если приложение не синхронизирует код, вызывающий CloseThreadpoolCleanupGroupMembers , с кодом, который создает новые объекты. Например, предположим, что поток создает два рабочих объекта threadpool: Work1 и Work2. Другой поток вызывает Метод CloseThreadpoolCleanupGroupMembers. В зависимости от того, когда выполняются потоки, может произойти любое из следующих действий:

Work1 и Work2 добавляются в группу очистки после освобождения ее существующих членов. Код, который отправляет Work1 и Work2, завершится успешно.
Work1 добавляется в группу очистки до освобождения ее существующих членов, что приводит к освобождению Work1 вместе с другими участниками. Затем добавляется Work2. Код, который отправляет Work1, создаст исключение; код, который отправляет Work2, завершится успешно.
Work1 и Work2 добавляются в группу очистки до освобождения ее существующих членов, что приводит к освобождению Work1 и Work2. Код, который отправляет Work1 или Work2, создаст исключение.

Чтобы просто дождаться или отменить ожидающие рабочие элементы, не освобождая их, используйте одну из функций обратного вызова threadpool: WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks или WaitForThreadpoolWorkCallbacks.

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0600 или выше.

Примеры

Пример см. в разделе Использование функций пула потоков.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	threadpoolapiset.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll