QueueUserWorkItem-Funktion (threadpoollegacyapiset.h)

Artikel
08/26/2023

Stellt ein Arbeitselement in die Warteschlange eines Workerthreads im Threadpool.

Syntax

BOOL QueueUserWorkItem(
  [in]           LPTHREAD_START_ROUTINE Function,
  [in, optional] PVOID                  Context,
  [in]           ULONG                  Flags
);

Parameter

[in] Function

Ein Zeiger auf die anwendungsdefinierte Rückruffunktion vom Typ LPTHREAD_START_ROUTINE , die vom Thread im Threadpool ausgeführt werden soll. Dieser Wert stellt die Startadresse des Threads dar. Diese Rückruffunktion darf die TerminateThread-Funktion nicht aufrufen.

Der Rückgabewert der Rückruffunktion wird nicht verwendet.

Weitere Informationen finden Sie unter ThreadProc.

[in, optional] Context

Ein einzelner Parameterwert, der an die Threadfunktion übergeben werden soll.

[in] Flags

Die Flags, die die Ausführung steuern. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.

Wert	Bedeutung
WT_EXECUTEDEFAULT 0x00000000	Standardmäßig wird die Rückruffunktion in eine Warteschlange für einen Nicht-E/A-Workerthread eingereiht. Die Rückruffunktion wird in die Warteschlange eines Threads eingereiht, der E/A-Vervollständigungsports verwendet. Dies bedeutet, dass sie keinen warnbaren Wartevorgang ausführen können. Wenn E/A abgeschlossen wird und einen APC generiert, wartet der APC möglicherweise unbegrenzt, da es keine Garantie dafür gibt, dass der Thread nach Abschluss des Rückrufs in einen warnbaren Wartezustand wechselt.
WT_EXECUTEINIOTHREAD 0x00000001	Dieses Flag wird nicht verwendet. Windows Server 2003 und Windows XP: Die Rückruffunktion wird in die Warteschlange eines E/A-Workerthreads eingereiht. Dieses Flag sollte verwendet werden, wenn die Funktion in einem Thread ausgeführt werden soll, der in einem warnbaren Zustand wartet. E/A-Workerthreads wurden ab Windows Vista und Windows Server 2008 entfernt.
WT_EXECUTEINPERSISTENTTHREAD 0x00000080	Die Rückruffunktion wird in eine Warteschlange mit einem Thread eingereiht, der nie beendet wird. Es wird nicht garantiert, dass jedes Mal derselbe Thread verwendet wird. Dieses Flag sollte nur für kurze Aufgaben verwendet werden, oder es kann sich auf andere Zeitgebervorgänge auswirken. Dieses Flag muss festgelegt werden, wenn der Thread Funktionen aufruft, die APCs verwenden. Weitere Informationen finden Sie unter Asynchrone Prozeduraufrufe. Beachten Sie, dass derzeit kein Workerthread wirklich persistent ist, obwohl Workerthreads nicht beendet werden, wenn E/A-Anforderungen ausstehen.
WT_EXECUTELONGFUNCTION 0x00000010	Die Rückruffunktion kann eine lange Wartezeit ausführen. Dieses Flag hilft dem System zu entscheiden, ob ein neuer Thread erstellt werden soll.
WT_TRANSFER_IMPERSONATION 0x00000100	Rückruffunktionen verwenden das aktuelle Zugriffstoken, unabhängig davon, ob es sich um ein Prozess- oder Identitätswechseltoken handelt. Wenn dieses Flag nicht angegeben ist, werden Rückruffunktionen nur mit dem Prozesstoken ausgeführt. Windows XP: Dieses Flag wird erst unter Windows XP SP2 und Windows Server 2003 unterstützt.

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

Wenn eine Funktion in einer DLL in die Warteschlange eines Workerthreads eingereiht wird, stellen Sie sicher, dass die Ausführung der Funktion abgeschlossen ist, bevor die DLL entladen wird.

Standardmäßig verfügt der Threadpool über maximal 512 Threads pro Prozess. Verwenden Sie zum Erhöhen des Warteschlangengrenzwerts das in WinNT.h definierte Makro WT_SET_MAX_THREADPOOL_THREAD .

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)&lt;&lt;16)

Verwenden Sie dieses Makro im Aufruf von QueueUserWorkItem , um den Flags-Parameter anzugeben. Die Makroparameter sind die gewünschten Flags und der neue Grenzwert, bis zu (2<<16)-1 Threads. Die Größe der Warteschlange wird jedoch durch die Größe des nicht auslagerten Kernelpools beschränkt. Beachten Sie, dass Ihre Anwendung die Leistung verbessern kann, indem die Anzahl der Workerthreads niedrig gehalten wird.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	threadpoollegacyapiset.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Siehe auch

Prozess- und Threadfunktionen

Pooling von Threads

ThreadProc