InitOnceExecuteOnce, fonction (synchapi.h)

Article
03/02/2024

Lorsque plusieurs threads appellent InitOnceExecuteOnce en passant le même bloc d’initialisation à usage unique, un seul thread exécute la fonction de rappel spécifiée par InitFn. Les threads restants se bloquent jusqu’à ce que la fonction de rappel se termine. Si la fonction de rappel retourne TRUE pour indiquer la réussite, InitOnceExecuteOnce retourne TRUE à tous les appelants à la fois. Toutefois, si le rappel retourne FALSE pour indiquer un échec, InitOnceExecuteOnce retourne FALSE uniquement au thread unique qui a exécuté la fonction de rappel. Dans le même temps, l’un des threads bloqués restants débloque et exécute à nouveau InitFn . Par conséquent, dans un scénario où InitFn peut échouer par intermittence et où de nouvelles tentatives sont souhaitées, tous les threads doivent continuer à appeler InitOnceExecuteOnce jusqu’à ce que TRUE soit retourné.

Syntaxe

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

Paramètres

[in, out] InitOnce

Pointeur vers la structure d’initialisation à usage unique.

[in] InitFn

Pointeur vers une fonction InitOnceCallback définie par l’application.

[in, optional] Parameter

Paramètre à passer à la fonction de rappel.

[in, out, optional] Context

Paramètre qui reçoit des données stockées avec la structure d’initialisation à usage unique en cas de réussite. Les bits de INIT_ONCE_CTX_RESERVED_BITS de données de bas ordre sont toujours nuls. Si Context pointe vers une structure de données, la structure de données doit être alignée sur DWORD. Le contexte ne doit pas être un pointeur de code sur Arm32, car les pointeurs de code Arm32 ont toujours le bit le moins significatif défini. Pour plus d’informations, consultez l’ABI Arm32 .

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Cette fonction est utilisée pour l’initialisation synchrone à usage unique. Pour une initialisation asynchrone à usage unique, utilisez la fonction InitOnceBeginInitialize avec l’indicateur INIT_ONCE_ASYNC .

Un seul thread à la fois peut exécuter la fonction de rappel spécifiée par InitFn. Autres threads qui spécifient le même bloc de structure d’initialisation unique jusqu’à la fin du rappel.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0600 ou version ultérieure. Pour plus d’informations, consultez Utilisation des en-têtes Windows.

Exemples

Pour obtenir un exemple qui utilise cette fonction, consultez Utilisation de One-Time Initialisation.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	synchapi.h (inclure Windows.h sur Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll