Share via

initOnceExecuteOnce 函数 (synchapi.h)

  • 项目

当多个线程调用传递同一个一次性初始化块的 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。

注解

此函数用于同步一次性初始化。 对于异步一次性初始化，请使用具有 INIT_ONCE_ASYNC 标志的 InitOnceBeginInitialize 函数。

一次只能有一个线程执行 InitFn 指定的回调函数。 指定相同的一次性初始化结构块的其他线程，直到回调完成。

若要编译使用此函数的应用程序， 请将_WIN32_WINNT 定义为 0x0600 或更高版本。 有关详细信息，请参阅 使用 Windows 标头。

示例

有关使用此函数的示例，请参阅 Using One-Time Initialization。

要求

要求 值
最低受支持的客户端 Windows Vista [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 | UWP 应用]
目标平台 Windows
标头 synchapi.h (包括 Windows 7 上的 Windows.h、Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

InitOnceCallback

InitOnceInitialize

一次性初始化

同步函数