Funzione TlsGetValue (processthreadsapi.h)

Articolo
11/18/2024

Recupera il valore nello slot tls (Thread Local Storage) del thread chiamante per l'indice TLS specificato. Ogni thread di un processo ha un proprio slot per ogni indice TLS.

Sintassi

LPVOID TlsGetValue(
  [in] DWORD dwTlsIndex
);

Parametri

[in] dwTlsIndex

Indice TLS allocato dalla funzione TlsAlloc.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è il valore archiviato nello slot TLS del thread chiamante associato all'indice specificato. Se dwTlsIndex è un indice valido allocato da una chiamata riuscita a TlsAlloc, questa funzione ha sempre esito positivo.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

I dati archiviati in uno slot TLS possono avere un valore pari a 0 perché ha ancora il valore iniziale o perché il thread ha chiamato la funzione TlsSetValue con 0. Pertanto, se il valore restituito è 0, è necessario verificare se GetLastError restituisce ERROR_SUCCESS prima di determinare che la funzione non è riuscita. Se GetLastError restituisce ERROR_SUCCESS, la funzione ha avuto esito positivo e i dati archiviati nello slot TLS sono 0. In caso contrario, la funzione non è riuscita.

Funzioni che restituiscono indicazioni sulla chiamata di errore SetLastError quando hanno esito negativo. In genere non chiamano SetLastError quando hanno esito positivo. La funzione TlsGetValue è un'eccezione a questa regola generale. La funzione tlsGetValue chiama SetLastError per cancellare l'ultimo errore di un thread quando ha esito positivo. Ciò consente di controllare il recupero senza errori di valori zero.

Osservazioni

Windows 8.1, Windows Server 2012 R2e Windows 10, versione 1507: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e Windows 10, versione 1507. Quando un'app di Windows Store chiama questa funzione, viene sostituita con una chiamata inline a FlsGetValue. Vedere FlsGetValue per la documentazione della funzione.

Windows 10, versione 1511 e Windows 10, versione 1607: questa funzione è completamente supportata per le app UWP (Universal Windows Platform) e non viene più sostituita con una chiamata inline a FlsGetValue.

Gli indici TLS vengono in genere allocati dalla funzione tlsAlloc durante l'inizializzazione di processi o DLL. Dopo aver allocato un indice TLS, ogni thread del processo può usarlo per accedere al proprio slot TLS per tale indice. Un thread specifica un indice TLS in una chiamata a TlsSetValue per archiviare un valore nello slot. Il thread specifica lo stesso indice in una chiamata successiva a TlsGetValue per recuperare il valore archiviato.

TlsGetValue è stato implementato con velocità come obiettivo principale. La funzione esegue la convalida minima dei parametri e il controllo degli errori. In particolare, ha esito positivo se dwTlsIndex è compreso nell'intervallo compreso tra 0 e (TLS_MINIMUM_AVAILABLE- 1). Spetta al programmatore assicurarsi che l'indice sia valido e che il thread chiami TlsSetValue prima di chiamare TlsGetValue.

TlsGetValue imposta sempre l'ultimo errore di un thread. In alcuni casi, un'applicazione ,ad esempio quelle con heap personalizzati che supportano malloc, potrebbe dover chiamare GetLastError prima di chiamare TlsGetValue per salvare l'ultimo errore del thread (seguito da SetLastError per ripristinare l'errore salvato). Sfortunatamente, questo può comportare un costo di prestazioni non semplice su determinate CPU.

Windows 11 24H2 e versioni successive: Usare la funzione TlsGetValue2 , identica a TlsGetValue ad eccezione del fatto che non imposta l'ultimo errore del thread. Le applicazioni che chiamano tlsGetValue2 devono evitare di usare 0 come valore valido perché non è possibile chiamare GetLastError per verificare se TlsGetValue2 non riuscito.

Esempi

Per un esempio, vedere Using Thread Local Storage or Using Thread Local Storage in a Dynamic-Link Library.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	processthreadsapi.h (include Windows.h in Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
libreria	Kernel32.lib; WindowsPhoneCore.lib in Windows Phone 8.1
dll	KernelBase.dll in Windows Phone 8.1; Kernel32.dll