WaitForSingleObject

플랫폼 SDK

WaitForSingleObject

지정한 오브젝트가 시그널 상태가 되거나 타임아웃이 되면 제어를 돌려준다.
(지정한 오브젝트가 비시그널 상태이면 시그널 상태가 될때 까지 설정한 타임아웃 시간 만큼WaitForSingleObject에서 대기한다.
당연한 이야기지만 시그널 상태면 바로 다음으로 넘어간다.)


대기 상태라는 것을 알려주려면 WaitForMultipleObjectsEx 함수를 사용한다.
복수의 오브젝트를 대기하기 위해서는 WaitForMultipleObjects 함수를 사용한다.

DWORD WaitForSingleObject(
  HANDLE hHandle,        // 오브젝트 핸들
  DWORD dwMilliseconds   // 타임아웃 시간
);파라미터

hHandle

오브젝트의 핸들을 지정한다.
핸들을 지정할 수 있는 함수의 해설을 참조

핸들이 대기 상태로 있을때에는 그 핸들을 없앴을 경우 그 함수의 동작은 정의되지않는다.
(If this handle is closed while the wait is still pending, the function's behavior is undefined. : 동작을 안한다는 이야기인가? -.-)

Windows NT/2000：이 핸들에 SYNCHRONIZE 억세스 권을 할당해야만 된다. 상세한 내용은  MSDN 라이브러리의 「Standard Access Rights」를 참조

dwMilliseconds

타임아웃 시간을 밀리초(ms)단위로 지정한다.
타임아웃 시간을 경과하면 오브젝트가 비시그널 상태에 있더라도 제어권을 돌려준다.(WaitForSingleObject함수에서 더 이상 대기하지않는다.)
0으로 지정하면 이 함수는 지정된 오브젝트의 상태를 확인하고 바로 다음 행을 실행한다.
INFINITE를 지정하면 오브젝트가 시그널 상태가 될때까지 기다린다.
 

반환값

함수가 정상적으로 실행되면 함수 제어권을 돌려준 이유를 알려준다.
값은 아래와 같다.

값	의미
WAIT_ABANDONED	지정된 오브젝트는 파기 되어진 뮤텍스  오브젝트 였다. 이 뮤텍스 오브젝트를 소유한 스레드가 뮤텍스 오브젝트의 소유권을 풀어주지 않고 종료했다. 그래서 그 뮤텍스 오브젝트의 소유권이 호출한 쪽 스레드로 옮겨져 그 뮤텍스는 비시그널 상태로 설정되었다.
WAIT_OBJECT_0	지정한 오브젝트가 시그널 상태로 되었다.
WAIT_TIMEOUT	지정한 오브젝트가 타임아웃 시간이 경과할 때까지 시그널 생태가 되지 않았다.

함수가 실패하면 WAIT_FAILED이 돌아온다. 확장 에러 정보를 얻기 위해서는 GetLastError 함수를 사용한다.

해설

WaitForSingleObject 함수는 지정한 오브젝트의 현재의 상태를 체크한다.
그 오브젝트가 비시그널 상태일 때는 호출한 스레드는 대기 상태가 된다.
오브젝트가 시그널 상태가 되거나 타임아웃 시간이 경과하는 것을 기다린다.

이 함수는 특정 타임의 동기 오브젝트의 상태를 바꿈으로
지정된 오브젝트가 시그널 상태가 되고 대기 상태에서 빠져나오게 된다.
그리고 세마포어 오브젝트의 카운트를 하나씩 줄인다.

이 함수는 다음의 오브젝트들을 기다릴 수 있다.

•변경 통지(Change notification)
•콘솔 입력(Console input)
•이벤트(Event)
•Memory resource notification
•뮤텍스(Mutex)
•프로세스(Process)
•세마포어(Semaphore)
•스레드(Thread)
•대기 가능한 타이머(Waitable timer)

상세한 내용은 MSDN 라이브러리의「Synchronization Objects」을 참조

이 대기 함수는 윈도우를 직접적 또는 간접적으로 작성하는 코드를 조합해서 사용하는 경우는 주의가 필요한다.
하나의 스레드가 윈도우를 작성하는 경우, 그 스레드는 그 윈도우에 관계하는 메세지를 처리해야된다. 또 메세지 브로드케스트는 시스템 안의 모든 윈도우에 메세지를 보낸다. 타임아웃 시간으로서 INIFINITEㄹ르 지정해서 대기 함수를 호출할 때, 이와 같은 현상이 발생하면 시스템은 데드록(daedlock) 상태에 빠지게 되는 경우도 있다. 윈도우가 간접적으로 작성한 두개의 예로서 DDE와 COM의 CoInitialize가 있다. 그렇기 때문에 윈도우를 작성한 스레드에서는 WaitForSingleObject 함수 말고 MsgWaitForMultipleObjects 함수 나 MsgWaitForMultipleObjectsEx  함수를 사용한다.

대응정보

Windows NT/2000：Windows NT 3.1 이후
Windows 95/98：Windows 95 이후
헤더：Winbase.h 안에서 선언、Windows.h 을 include
임포트 라이브러리：Kernel32.lib를 사용


원문 참고
http://msdn2.microsoft.com/en-us/library/ms687032.aspx

위 譯은 내맘대로 한 것임으로 잘못 譯한 것에 대한 책임 못짐 -.-;;