InitOnceExecuteOnce-Funktion (synchapi.h)

  • Artikel

Wenn mehrere Threads InitOnceExecuteOnce aufrufen und denselben einmaligen Initialisierungsblock übergeben, führt nur ein Thread die von InitFn angegebene Rückruffunktion aus. Die restlichen Threads werden blockiert, bis die Rückruffunktion abgeschlossen ist. Wenn die Rückruffunktion TRUE zurückgibt, um den Erfolg anzuzeigen, gibt InitOnceExecuteOnce true an alle Aufrufer zurück. Wenn der Rückruf jedoch FALSE zurückgibt, um auf einen Fehler hinzuweisen, gibt InitOnceExecuteOnce FALSE nur an den einzelnen Thread zurück, der die Rückruffunktion ausgeführt hat. Gleichzeitig hebt einer der verbleibenden blockierten Threads die Blockierung auf und führt InitFn erneut aus. Daher sollten in einem Szenario, in dem InitFn zeitweilig fehlschlagen kann und Wiederholungsversuche gewünscht werden, alle Threads weiterhin InitOnceExecuteOnce aufrufen, bis TRUE zurückgegeben wird.

Syntax

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

Parameter

[in, out] InitOnce

Ein Zeiger auf die einmalige Initialisierungsstruktur.

[in] InitFn

Ein Zeiger auf eine anwendungsdefinierte InitOnceCallback-Funktion .

[in, optional] Parameter

Ein Parameter, der an die Rückruffunktion übergeben werden soll.

[in, out, optional] Context

Ein Parameter, der daten empfängt, die mit der einmaligen Initialisierungsstruktur gespeichert sind, wenn der Erfolg erfolgreich ist. Die INIT_ONCE_CTX_RESERVED_BITS Bits der Daten in niedriger Reihenfolge sind immer 0. Wenn Context auf eine Datenstruktur verweist, muss die Datenstruktur DWORD-ausgerichtet sein. Kontext darf kein Codezeiger auf Arm32 sein, da Arm32-Codezeiger immer das am wenigsten signifikante Bit festgelegt haben. Weitere Informationen finden Sie in der Arm32-ABI .

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Diese Funktion wird für die synchrone einmalige Initialisierung verwendet. Verwenden Sie für die asynchrone einmalige Initialisierung die Funktion InitOnceBeginInitialize mit dem flag INIT_ONCE_ASYNC .

Nur ein Thread gleichzeitig kann die von InitFn angegebene Rückruffunktion ausführen. Andere Threads, die denselben einmaligen Initialisierungsstrukturblock angeben, bis der Rückruf abgeschlossen ist.

Um eine Anwendung zu kompilieren, die diese Funktion verwendet, definieren Sie _WIN32_WINNT als 0x0600 oder höher. Weitere Informationen finden Sie unter Verwenden der Windows-Header.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Verwenden One-Time Initialisierung.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile synchapi.h (Einschließen von Windows.h unter Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

InitOnceCallback

InitOnceInitialize

Einmalige Initialisierung

Synchronisierungsfunktionen