QueueUserAPC 함수(processthreadsapi.h)

  • 아티클

지정된 스레드의 APC 큐에 APC(사용자 모드 비동기 프로시저 호출 ) 개체를 추가합니다.

구문

DWORD QueueUserAPC(
  [in] PAPCFUNC  pfnAPC,
  [in] HANDLE    hThread,
  [in] ULONG_PTR dwData
);

매개 변수

[in] pfnAPC

지정된 스레드가 경고 가능한 대기 작업을 수행할 때 호출할 애플리케이션 제공 APC 함수에 대한 포인터입니다. 자세한 내용은 PAPCFUNC 콜백 함수를 참조하세요.

[in] hThread

스레드에 대한 핸들입니다. 핸들에 THREAD_SET_CONTEXT 액세스 권한이 있어야 합니다. 자세한 내용은 동기화 개체 보안 및 액세스 권한을 참조하세요.

[in] dwData

pfnAPC 매개 변수가 가리키는 APC 함수에 전달되는 단일 값입니다.

반환 값

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

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다. Windows Server 2003 및 Windows XP:GetLastError를 호출하여 검색할 수 있는 이 함수에 대해 정의된 오류 값은 없습니다.

설명

특수 사용자 모드 APC에 대한 자세한 내용은 QueueUserAPC2 함수 를 참조하세요.

운영 체제에서 제공되는 APC 지원을 통해 애플리케이션은 APC 개체를 스레드에 큐에 대기할 수 있습니다. APC에서 사용하는 함수를 성공적으로 실행하려면 APC가 호출자 프로세스의 스레드에만 큐에 대기해야 합니다.

참고

여러 가지 이유로 APC를 호출자 프로세스 외부의 스레드에 큐에 대기하는 것은 권장되지 않습니다. DLL 재지정으로 인해 호출자의 프로세스 외부에서 함수가 실행될 때 APC에서 사용하는 함수의 주소가 올바르지 않을 수 있습니다. 마찬가지로 64비트 프로세스가 APC를 32비트 프로세스로 큐에 대기하거나 그 반대로 큐에 대기하는 경우 주소가 올바르지 않으며 애플리케이션이 충돌합니다. 주소가 알려진 경우에도 다른 요인으로 인해 함수 실행이 성공할 수 없습니다.

각 스레드에는 자체 APC 큐가 있습니다. APC의 큐는 스레드가 APC 함수를 호출하도록 요청하는 것입니다. 운영 체제는 소프트웨어 인터럽트 를 실행하여 스레드가 APC 함수를 호출하도록 지시합니다.

사용자 모드 APC가 큐에 대기 중인 경우 스레드는 경고 가능한 상태가 아닌 한 APC 함수를 호출하도록 지시되지 않습니다. 스레드가 경고 가능한 상태이면 스레드는 FIFO(First out) 순서에서 보류 중인 모든 APC를 먼저 처리하고 대기 작업은 WAIT_IO_COMPLETION 반환합니다. 스레드는 SleepEx 함수, SignalObjectAndWait 함수, WaitForSingleObjectEx 함수, WaitForMultipleObjectsEx 함수 또는 MsgWaitForMultipleObjectsEx 함수를 사용하여 경고 가능한 상태로 전환됩니다.

스레드가 실행되기 전에 애플리케이션이 APC를 큐에 대기하는 경우 스레드는 APC 함수를 호출하여 시작합니다. 스레드가 APC 함수를 호출한 후 APC 큐의 모든 APC에 대해 APC 함수를 호출합니다.

APC 내에서 개체를 절전 모드로 또는 대기할 수 있습니다. APC 내에서 경고 대기를 수행하는 경우 APC를 재귀적으로 디스패치합니다. 이로 인해 스택 오버플로가 발생할 수 있습니다.

ExitThread 함수 또는 TerminateThread 함수 함수를 사용하여 스레드가 종료되면 APC 큐의 APC가 손실됩니다. APC 함수는 호출되지 않습니다.

스레드가 종료되는 중이면 QueueUserAPC를 호출하여 스레드의 APC 큐에 추가하면 (31) ERROR_GEN_FAILURE 실패합니다.

ReadFileEx 함수, SetWaitableTimer 함수 및 WriteFileEx 함수는 완료 알림 콜백 메커니즘으로 APC를 사용하여 구현됩니다.

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

요구 사항

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

참고 항목