Функция UnregisterWaitEx

Статья
06/13/2023

Отменяет зарегистрированную операцию ожидания, выданную функцией RegisterWaitForSingleObject .

Синтаксис

BOOL WINAPI UnregisterWaitEx(
  _In_     HANDLE WaitHandle,
  _In_opt_ HANDLE CompletionEvent
);

Параметры

WaitHandle [in]

Дескриптор ожидания. Этот дескриптор возвращается функцией RegisterWaitForSingleObject .

CompletionEvent [in, необязательный]

Дескриптор объекта события, который должен быть сигнализован при отмене регистрации операции ожидания. Этот параметр может принимать значение NULL.

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

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

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

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

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Невозможно выполнить блокирующий вызов UnregisterWaitEx из функции обратного вызова для той же операции ожидания. В противном случае обратный вызов будет ожидать завершения. Как правило, блокирующий вызов UnregisterWaitEx создает зависимость между текущим потоком и обратным вызовом, поэтому, чтобы выполнить блокирующий вызов отмены регистрации для другой операции ожидания, необходимо убедиться, что функции обратного вызова не зависят друг от друга и что вторая операция ожидания также не выполняет блокирующий вызов отмены регистрации в первой операции.

Будьте внимательны при выполнении блокирующего вызова UnregisterWaitEx в постоянном потоке. Если операция ожидания, отменяемая регистрация, была создана с WT_EXECUTEINPERSISTENTTHREAD, может возникнуть взаимоблокировка.

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

В некоторых случаях функция завершится сбоем с ERROR_IO_PENDING , если параметр CompletionEvent имеет значение NULL. Это означает, что существуют неоплаченные функции обратного вызова. Эти обратные вызовы либо выполняются, либо находятся в середине выполнения.

Если CompletionEvent является дескриптором события, предоставленного вызывающим элементом, функция может завершиться успешно, завершиться сбоем с ERROR_IO_PENDING или с другим кодом ошибки. Если функция завершается успешно или если функция завершается сбоем с ERROR_IO_PENDING, вызывающий объект всегда должен ждать, пока событие не получит сигнал о закрытии события. Если функция завершается сбоем с другим кодом ошибки, не нужно ждать, пока событие будет показано, чтобы закрыть событие.

Windows XP: Если CompletionEvent является дескриптором события, предоставленного вызывающим, и функция завершается сбоем с ERROR_IO_PENDING, вызывающий объект должен подождать, пока событие не будет поймечено о закрытии события. Это поведение изменилось, начиная с Windows Vista.

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0500 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Заголовок	Threadpoollegacyapiset.h в Windows 8 и Windows Server 2012 (включая Windows.h); WinBase.h в Windows 7, Windows Server 2008 R2, Windows Vista, Windows Server 2008, Windows XP и Windows Server 2003 (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

RegisterWaitForSingleObject
Функции синхронизации
Группировка потоков в пул