Share via

QueueUserWorkItem 함수(threadpoollegacyapiset.h)

  • 아티클

스레드 풀의 작업자 스레드에 작업 항목을 큐에 대기합니다.

구문

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

매개 변수

[in] Function

스레드 풀의 스레드에서 실행할 LPTHREAD_START_ROUTINE 형식의 애플리케이션 정의 콜백 함수에 대한 포인터입니다. 이 값은 스레드의 시작 주소를 나타냅니다. 이 콜백 함수는 TerminateThread 함수를 호출해서는 안됩니다.

콜백 함수의 반환 값은 사용되지 않습니다.

자세한 내용은 ThreadProc을 참조하세요.

[in, optional] Context

스레드 함수에 전달할 단일 매개 변수 값입니다.

[in] Flags

실행을 제어하는 플래그입니다. 이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

값 의미
WT_EXECUTEDEFAULT
0x00000000
 기본적으로 콜백 함수는 I/O가 아닌 작업자 스레드에 큐에 대기됩니다.

콜백 함수는 I/O 완료 포트를 사용하는 스레드에 큐에 대기합니다. 즉, 경고 대기를 수행할 수 없습니다. 따라서 I/O가 APC를 완료하고 생성하는 경우 콜백이 완료된 후 스레드가 경고 대기 상태가 될 것이라는 보장이 없으므로 APC는 무기한 대기할 수 있습니다.
WT_EXECUTEINIOTHREAD
0x00000001
 이 플래그는 사용되지 않습니다.

Windows Server 2003 및 Windows XP: 콜백 함수는 I/O 작업자 스레드에 큐에 대기됩니다. 경고 가능한 상태에서 대기하는 스레드에서 함수를 실행해야 하는 경우 이 플래그를 사용해야 합니다.

I/O 작업자 스레드는 Windows Vista 및 Windows Server 2008부터 제거되었습니다.
WT_EXECUTEINPERSISTENTTHREAD
0x00000080
 콜백 함수는 종료되지 않는 스레드에 큐에 대기됩니다. 매번 동일한 스레드가 사용된다는 보장은 없습니다. 이 플래그는 짧은 작업에만 사용하거나 다른 타이머 작업에 영향을 줄 수 있습니다.

스레드가 APC를 사용하는 함수를 호출하는 경우 이 플래그를 설정해야 합니다. 자세한 내용은 비동기 프로시저 호출을 참조하세요.

보류 중인 I/O 요청이 있는 경우 작업자 스레드가 종료되지 않지만 현재는 작업자 스레드가 실제로 지속되지 않습니다.
WT_EXECUTELONGFUNCTION
0x00000010
 콜백 함수는 긴 대기를 수행할 수 있습니다. 이 플래그는 시스템에서 새 스레드를 만들어야 하는지 여부를 결정하는 데 도움이 됩니다.
WT_TRANSFER_IMPERSONATION
0x00000100
 콜백 함수는 프로세스든 가장 토큰이든 관계없이 현재 액세스 토큰을 사용합니다. 이 플래그를 지정하지 않으면 콜백 함수는 프로세스 토큰으로만 실행됩니다.

Windows XP: 이 플래그는 Windows XP SP2 및 Windows Server 2003까지 지원되지 않습니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

DLL의 함수가 작업자 스레드에 큐에 대기 중인 경우 DLL이 언로드되기 전에 함수가 실행을 완료했는지 확인합니다.

기본적으로 스레드 풀에는 프로세스당 최대 512개의 스레드가 있습니다. 큐 제한을 높이려면 WinNT.h에 정의된 WT_SET_MAX_THREADPOOL_THREAD 매크로를 사용합니다.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

QueueUserWorkItem 호출에서 이 매크로를 사용하여 Flags 매개 변수를 지정합니다. 매크로 매개 변수는 원하는 플래그와 새 제한(최대 (2<<16)-1 스레드입니다. 그러나 큐의 크기는 페이징되지 않은 커널 풀의 크기로 제한됩니다. 애플리케이션은 작업자 스레드 수를 낮게 유지하여 성능을 향상시킬 수 있습니다.

이 함수를 사용하는 애플리케이션을 컴파일하려면 _WIN32_WINNT 0x0500 이상으로 정의합니다. 자세한 내용은 Windows 헤더 사용을 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows XP [데스크톱 앱만 해당]
지원되는 최소 서버 Windows Server 2003 [데스크톱 앱만 해당]
대상 플랫폼 Windows
헤더 threadpoollegacyapiset.h(Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2의 Windows.h 포함)
라이브러리 Kernel32.lib
DLL Kernel32.dll

참고 항목

프로세스 및 스레드 함수

스레드 풀링

ThreadProc