TlsGetValue-Funktion (processthreadsapi.h)
Ruft den Wert im threadlokalen Speicherplatz (TLS) des aufrufenden Threads für den angegebenen TLS-Index ab. Jeder Thread eines Prozesses verfügt über einen eigenen Steckplatz für jeden TLS-Index.
Syntax
LPVOID TlsGetValue(
[in] DWORD dwTlsIndex
);
Parameter
[in] dwTlsIndex
Der TLS-Index, der von der TlsAlloc--Funktion zugewiesen wurde.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert der Wert, der im TLS-Steckplatz des aufrufenden Threads gespeichert ist, der dem angegebenen Index zugeordnet ist. Wenn dwTlsIndex- ein gültiger Index ist, der einem erfolgreichen Aufruf von TlsAlloc-zugeordnet ist, ist diese Funktion immer erfolgreich.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Die in einem TLS-Steckplatz gespeicherten Daten können den Wert 0 aufweisen, da sie weiterhin ihren Anfangswert aufweist oder weil der Thread die TlsSetValue- Funktion mit 0 aufgerufen hat. Wenn der Rückgabewert 0 ist, müssen Sie daher überprüfen, ob GetLastError-ERROR_SUCCESS zurückgibt, bevor Sie feststellen, dass die Funktion fehlgeschlagen ist. Wenn GetLastErrorERROR_SUCCESSzurückgibt, ist die Funktion erfolgreich, und die im TLS-Steckplatz gespeicherten Daten sind 0. Andernfalls ist die Funktion fehlgeschlagen.
Funktionen, die Hinweise auf Fehleraufrufe SetLastError- zurückgeben, wenn sie fehlschlagen. Sie rufen SetLastError- im Allgemeinen nicht auf, wenn sie erfolgreich sind. Die funktion TlsGetValue ist eine Ausnahme von dieser allgemeinen Regel. Die TlsGetValue--Funktion ruft SetLastError- auf, um den letzten Fehler eines Threads zu löschen, wenn er erfolgreich ist. Dies ermöglicht die Überprüfung auf den fehlerfreien Abruf von Nullwerten.
Bemerkungen
Windows 8.1, Windows Server 2012 R2und Windows 10, Version 1507: Diese Funktion wird für Windows Store-Apps unter Windows 8.1, Windows Server 2012 R2 und Windows 10, Version 1507, unterstützt. Wenn eine Windows Store-App diese Funktion aufruft, wird sie durch einen Inlineaufruf an FlsGetValueersetzt. Informationen zur Funktionsdokumentation finden Sie unter FlsGetValue-.
Windows 10, Version 1511 und Windows 10, Version 1607: Diese Funktion wird für UWP-Apps (Universelle Windows-Plattform) vollständig unterstützt und wird nicht mehr durch einen Inlineaufruf an FlsGetValueersetzt.
TLS-Indizes werden in der Regel vom TlsAlloc--Funktion während der Prozess- oder DLL-Initialisierung zugewiesen. Nachdem ein TLS-Index zugewiesen wurde, kann jeder Thread des Prozesses ihn verwenden, um auf einen eigenen TLS-Steckplatz für diesen Index zuzugreifen. Ein Thread gibt einen TLS-Index in einem Aufruf von TlsSetValue- an, um einen Wert im Steckplatz zu speichern. Der Thread gibt denselben Index in einem nachfolgenden Aufruf von TlsGetValue an, um den gespeicherten Wert abzurufen.
TlsGetValue wurde mit Geschwindigkeit als primäres Ziel implementiert. Die Funktion führt minimale Parameterüberprüfung und Fehlerüberprüfung durch. Insbesondere ist es erfolgreich, wenn dwTlsIndex- sich im Bereich 0 bis (TLS_MINIMUM_AVAILABLE– 1) befindet. Es liegt bei dem Programmierer, sicherzustellen, dass der Index gültig ist und dass der Thread TlsSetValue- aufruft, bevor TlsGetValue-aufgerufen wird.
TlsGetValue- legt immer den letzten Fehler eines Threads fest. In einigen Fällen muss eine Anwendung (z. B. solche mit benutzerdefinierten Heaps, die malloc unterstützen) möglicherweise GetLastError- aufrufen, bevor Sie TlsGetValue- aufrufen, um den letzten Fehler des Threads zu speichern (gefolgt von SetLastError, um den gespeicherten Fehler wiederherzustellen). Leider kann dies bei bestimmten CPUs zu einem nicht trivialen Leistungsaufwand führen.
Windows 11 24H2 und höher: Verwenden Sie die funktion TlsGetValue2, die mit TlsGetValue- identisch ist, mit der Ausnahme, dass der letzte Fehler des Threads nicht festgelegt wird. Anwendungen, die TlsGetValue2- aufrufen, sollten die Verwendung von 0 als gültigen Wert vermeiden, da GetLastError- nicht aufgerufen werden kann, um zu überprüfen, ob TlsGetValue2 fehlgeschlagen ist.
Beispiele
Ein Beispiel finden Sie unter Using Thread Local Storage or Using Thread Local Storage in a Dynamic-Link Library.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | processthreadsapi.h (enthalten Windows.h unter Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib; WindowsPhoneCore.lib unter Windows Phone 8.1 |
| DLL- | KernelBase.dll unter Windows Phone 8.1; Kernel32.dll |