Share via

RegisterWaitForSingleObject 함수(winbase.h)

  • 아티클

스레드 풀 의 대기 스레드가 개체를 대기하도록 지시합니다. 대기 스레드는 다음 중 하나가 발생할 때 지정된 콜백 함수를 스레드 풀에 큐에 대기합니다.

  • 지정된 개체가 신호 상태입니다.
  • 제한 시간 간격이 경과합니다.

구문

BOOL RegisterWaitForSingleObject(
  [out]          PHANDLE             phNewWaitObject,
  [in]           HANDLE              hObject,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Context,
  [in]           ULONG               dwMilliseconds,
  [in]           ULONG               dwFlags
);

매개 변수

[out] phNewWaitObject

반환 시 대기 핸들을 수신하는 변수에 대한 포인터입니다. CloseHandle과 같은 개체 핸들이 필요한 함수에서는 대기 핸들을 사용할 수 없습니다.

[in] hObject

개체에 대한 핸들입니다. 핸들을 지정할 수 있는 개체 형식 목록은 다음 주의 섹션을 참조하세요.

대기가 보류 중인 동안 이 핸들이 닫히면 함수의 동작이 정의되지 않습니다.

핸들에는 SYNCHRONIZE 액세스 권한이 있어야 합니다. 자세한 내용은 표준 액세스 권한을 참조하세요.

[in] Callback

hObject가 신호 상태이거나 dwMilliseconds가 경과할 때 실행할 WAITORTIMERCALLBACK 형식의 애플리케이션 정의 함수에 대한 포인터입니다. 자세한 내용은 WaitOrTimerCallback을 참조하세요.

[in, optional] Context

콜백 함수에 전달되는 단일 값입니다.

[in] dwMilliseconds

제한 시간 간격(밀리초)입니다. 함수는 개체의 상태가 서명되지 않은 경우에도 간격이 경과하면 를 반환합니다. dwMilliseconds가 0이면 함수는 개체의 상태를 테스트하고 즉시 반환합니다. dwMilliseconds가 INFINITE이면 함수의 제한 시간 간격이 경과하지 않습니다.

[in] dwFlags

이 매개 변수는 다음 값 중 하나 이상일 수 있습니다.

이러한 값을 신호로 유지되는 개체와 함께 사용하는 방법에 대한 자세한 내용은 주의 섹션을 참조하세요.

값 의미
WT_EXECUTEDEFAULT
0x00000000
 기본적으로 콜백 함수는 I/O가 아닌 작업자 스레드로 큐에 대기됩니다.
WT_EXECUTEINIOTHREAD
0x00000001
 이 플래그는 사용되지 않습니다.

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

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

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

보류 중인 I/O 요청이 있는 경우 작업자 스레드가 종료되지 않지만 현재는 작업자 스레드가 실제로 지속되지 않습니다.
WT_EXECUTEINWAITTHREAD
0x00000004
 콜백 함수는 대기 스레드 자체에 의해 호출됩니다. 이 플래그는 짧은 작업에만 사용하거나 다른 대기 작업에 영향을 줄 수 있습니다.

콜백 함수가 동일한 잠금을 획득하려고 하는 동안 일부 다른 스레드가 배타적 잠금을 획득하고 UnregisterWait 또는 UnregisterWaitEx 함수를 호출하는 경우 교착 상태가 발생할 수 있습니다.
WT_EXECUTELONGFUNCTION
0x00000010
 콜백 함수는 긴 대기를 수행할 수 있습니다. 이 플래그는 시스템에서 새 스레드를 만들어야 하는지 여부를 결정하는 데 도움이 됩니다.
WT_EXECUTEONLYONCE
0x00000008
 콜백 함수가 한 번 호출된 후 스레드는 더 이상 핸들에서 대기하지 않습니다. 그렇지 않으면 대기 작업이 취소될 때까지 대기 작업이 완료될 때마다 타이머가 다시 설정됩니다.
WT_TRANSFER_IMPERSONATION
0x00000100
 콜백 함수는 프로세스이든 가장 토큰이든 관계없이 현재 액세스 토큰을 사용합니다. 이 플래그를 지정하지 않으면 콜백 함수는 프로세스 토큰으로만 실행됩니다.

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

반환 값

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

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

설명

필요한 경우 새 대기 스레드가 자동으로 만들어집니다. 대기 작업은 스레드 풀의 대기 스레드에 의해 수행됩니다. 콜백 루틴은 개체의 상태가 신호를 받거나 시간 제한 간격이 경과할 때 작업자 스레드에 의해 실행됩니다. dwFlags가 WT_EXECUTEONLYONCE 않으면 이벤트가 신호되거나 시간 제한 간격이 경과할 때마다 타이머가 다시 설정됩니다.

대기가 완료되면 UnregisterWait 또는 UnregisterWaitEx 함수를 호출하여 대기 작업을 취소해야 합니다. ( WT_EXECUTEONLYONCE 사용하는 대기 작업도 취소해야 합니다.) 콜백 함수 내에서 이러한 함수 중 하나에 대한 차단 호출을 수행하지 마세요.

대기 스레드가 다시 설정되기 전에 이벤트가 신호를 수신한다는 것을 감지하지 못할 수 있으므로 RegisterWaitForSingleObject에 전달된 이벤트 개체를 펄스하면 안 됩니다. WT_EXECUTEONLYONCE 또는 WT_EXECUTEINWAITTHREAD 플래그를 설정하지 않는 한 신호가 남아 있는 개체(예: 수동 재설정 이벤트 또는 종료된 프로세스)를 등록하면 안 됩니다. 다른 플래그의 경우 이벤트가 다시 설정되기 전에 콜백 함수를 너무 많이 호출할 수 있습니다.

함수는 일부 유형의 동기화 개체의 상태를 수정합니다. 신호 상태가 대기 조건을 충족하는 개체에 대해서만 수정이 발생합니다. 예를 들어 세마포 개체의 개수가 1씩 감소합니다.

RegisterWaitForSingleObject 함수는 다음 개체를 기다릴 수 있습니다.

  • 변경 알림
  • 콘솔 입력
  • 이벤트
  • 메모리 리소스 알림
  • Mutex
  • 프로세스
  • 세마포
  • 스레드
  • 대기 가능한 타이머
자세한 내용은 동기화 개체를 참조하세요.

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

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

dwFlags 매개 변수를 지정할 때 이 매크로를 사용합니다. 매크로 매개 변수는 원하는 플래그와 새 제한(최대 (2<<16)-1 스레드)입니다. 그러나 애플리케이션은 작업자 스레드 수를 낮게 유지하여 성능을 향상시킬 수 있습니다.

작업 항목 및 호출하는 모든 함수는 스레드 풀에 안전해야 합니다. 따라서 기본 콜백 환경에서 RegNotifyChangeKeyValue 함수와 같은 영구 스레드가 필요한 비동기 호출을 호출할 수 없습니다. 대신 , SetThreadpoolThreadMaximum 및 SetThreadpoolThreadMinimum 함수를 사용하여 스레드 풀 최댓값을 스레드 풀 최소값과 동일하게 설정하거나 CreateThread 함수를 사용하여 사용자 고유의 스레드를 만듭니다. 원래 스레드 풀 API의 경우 QueueUserWorkItem 함수를 사용하여 WT_EXECUTEINPERSISTENTTHREAD 지정합니다.

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

요구 사항

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

참고 항목

동기화 함수

스레드 풀링

UnregisterWait

UnregisterWaitEx

대기 함수

WaitOrTimerCallback