Функция InitOnceExecuteOnce (synchapi.h)

Статья
04/11/2023

Если несколько потоков вызывают Метод InitOnceExecuteOnce, передавая один и тот же блок инициализации, только один поток будет выполнять функцию обратного вызова, указанную параметром InitFn. Остальные потоки будут блокироваться до завершения функции обратного вызова. Если функция обратного вызова возвращает значение TRUE , указывающее на успешное выполнение, InitOnceExecuteOnce возвратит true всем вызывающим абонентам одновременно. Однако если обратный вызов возвращает значение FALSE , указывающее на сбой, InitOnceExecuteOnce вернет значение FALSE только одному потоку, который выполнил функцию обратного вызова. В то же время один из оставшихся заблокированных потоков разблокирует и снова выполнит InitFn . Таким образом, в сценарии, когда InitFn может периодически завершаться сбоем и требуется повторная попытка, все потоки должны продолжать вызывать InitOnceExecuteOnce, пока не будет возвращено значение TRUE .

Синтаксис

BOOL InitOnceExecuteOnce(
  [in, out]           PINIT_ONCE    InitOnce,
  [in]                PINIT_ONCE_FN InitFn,
  [in, optional]      PVOID         Parameter,
  [in, out, optional] LPVOID        *Context
);

Параметры

[in, out] InitOnce

Указатель на структуру одноразовой инициализации.

[in] InitFn

Указатель на определяемую приложением функцию InitOnceCallback .

[in, optional] Parameter

Параметр, передаваемый функции обратного вызова.

[in, out, optional] Context

Параметр, который получает данные, хранящиеся со структурой одноразовой инициализации, после успешного выполнения. В нижнем порядке INIT_ONCE_CTX_RESERVED_BITS биты данных всегда равны нулю. Если Context указывает на структуру данных, структура данных должна быть выровнена по DWORD. Контекст не должен быть указателем кода в Arm32, так как указатели кода Arm32 всегда имеют наименьший набор битов. Дополнительные сведения см. в статье Arm32 ABI .

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

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

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

Эта функция используется для синхронной однократной инициализации. Для асинхронной однократной инициализации используйте функцию InitOnceBeginInitialize с флагом INIT_ONCE_ASYNC .

Только один поток за раз может выполнять функцию обратного вызова, указанную initFn. Другие потоки, указывающие такую же структуру однократной инициализации, блокируются до завершения обратного вызова.

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

Примеры

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

Требования

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

См. также

InitOnceCallback

InitOnceInitialize

Однократная инициализация

Функции синхронизации