다음을 통해 공유

WaitForSingleObject 함수(synchapi.h)

  • 아티클

지정된 개체가 신호 상태가 되거나 시간 제한 간격이 경과할 때까지 기다립니다.

경고 대기 상태를 입력하려면 WaitForSingleObjectEx 함수를 사용합니다. 여러 개체를 기다리려면 WaitForMultipleObjects사용합니다.

통사론

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

매개 변수

[in] hHandle

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

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

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

[in] dwMilliseconds

시간 제한 간격(밀리초)입니다. 0이 아닌 값을 지정하면 함수는 개체가 신호되거나 간격이 경과할 때까지 기다립니다. dwMilliseconds 0이면 개체가 신호를 받지 않으면 함수가 대기 상태가 되지 않습니다. 항상 즉시 반환됩니다. dwMilliseconds INFINITE경우 함수는 개체가 신호를 받을 때만 반환됩니다.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 및 Windows Server 2008 R2:dwMilliseconds 값에는 저전력 상태에서 소요된 시간이 포함됩니다. 예를 들어 컴퓨터가 절전 모드인 동안 시간 제한은 계속 카운트다운됩니다.

Windows 8 이상 Windows Server 2012 이상:dwMilliseconds 값에는 저전력 상태에서 소요된 시간이 포함되지 않습니다. 예를 들어 컴퓨터가 절전 모드인 동안 시간 제한은 계속 카운트다운되지 않습니다.

반환 값

함수가 성공하면 반환 값은 함수가 반환된 이벤트를 나타냅니다. 다음 값 중 하나일 수 있습니다.

반환 코드/값 묘사
WAIT_ABANDONED
0x00000080L
 지정된 개체는 소유 스레드가 종료되기 전에 뮤텍스 개체를 소유한 스레드에서 해제되지 않은 뮤텍스 개체입니다. 뮤텍스 개체의 소유권은 호출 스레드에 부여되고 뮤텍스 상태는 서명되지 않은 상태로 설정됩니다.

뮤텍스가 영구 상태 정보를 보호하는 경우 일관성을 확인해야 합니다.
WAIT_OBJECT_0
0x00000000L
 지정된 개체의 상태가 신호를 받았습니다.
WAIT_TIMEOUT
0x00000102L
 시간 제한 간격이 경과하고 개체의 상태가 서명되지 않습니다.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 함수가 실패했습니다. 확장 오류 정보를 얻으려면 GetLastError호출합니다.

발언

WaitForSingleObject 함수는 지정된 개체의 현재 상태를 확인합니다. 개체의 상태가 서명되지 않은 경우 호출 스레드는 개체가 신호를 보내거나 제한 시간 간격이 경과할 때까지 대기 상태가 됩니다.

이 함수는 일부 유형의 동기화 개체의 상태를 수정합니다. 수정은 신호를 받은 상태로 인해 함수가 반환된 개체에 대해서만 발생합니다. 예를 들어 세마포 개체의 수는 1씩 감소합니다.

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

  • 변경 알림
  • 콘솔 입력
  • 이벤트
  • 메모리 리소스 알림
  • 뮤텍스 (뮤텍스)
  • 프로세스
  • 세마포
  • 스레드
  • 대기 가능한 타이머
직접 또는 간접적으로 창을 만드는 대기 함수 및 코드를 호출할 때는 주의해야 합니다. 스레드가 창을 만드는 경우 메시지를 처리해야 합니다. 메시지 브로드캐스트는 시스템의 모든 창으로 전송됩니다. INFINITE 시간 제한 간격이 있는 대기 함수를 사용하는 스레드는 시스템이 교착 상태가 될 수 있습니다. 간접적으로 창을 만드는 코드의 두 가지 예는 DDE 및 CoInitialize 함수입니다. 따라서 창을 만드는 스레드가 있는 경우 WaitForSingleObject대신 MsgWaitForMultipleObjects 또는 MsgWaitForMultipleObjectsEx사용합니다.

예제

예를 들어 뮤텍스 개체사용하는 참조하세요.

요구 사항

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

참고 항목

동기화 함수

대기 함수