WaitForSingleObject Function

728x90

출처: https://docs.microsoft.com/en-us/windows/desktop/api/synchapi/nf-synchapi-waitforsingleobject

WaitForSingleObject function (synchapi.h)

 

가. 지정된 개체가 신호 상태에 있거나 시간 초과 간격이 경과할 때까지 대기한다.

나. 경고 가능한 대기 상태를 입력하려면 WaitForSingleObjectEx 함수를 이용해라. 여러 개체를 기다리려면 WaitForMultipleObjects를 이용해라.

 

Syntax

DWORD WaitForSingleObject(
  HANDLE hHandle,
  DWORD  dwMilliseconds
);

 

Parameters

 (1) hHandle

  1) 개체애 데한 핸들. 핸들을 지정할 수 있는 개체 유형의 목록은 Remarks 섹션을 참조해라.

 

  2) 대기 상태가 아직 보류 중인 동안 핸들이 닫힌 경우 함수의 동작이 정의되지 않은 것이다.

 

  3) 핸들은 SYNCHRONIZE 액세스 권한이 있어야 한다. 자세한 내용은 Standard Access Rights를 참조해라.

 

 (2) dwMilliseconds

  1) 초과 시간 간격, milliseconds. 0이 아닌 값을 지정하면 함수는 개체가 신호를 받거나 간격이 경과할 때까지 대기한다. dwMilliseconds가 0인 경우 개체가 신호를 받지 않으면 함수는 대기 상태로 전환되지 않는다. 그것은 항상 즉시 반환한다. dwMilliseconds가 INFINITE인 경우 함수는 신호를 받을 때만 반환될 것이다.

 

  2) Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008, Windows Server 2008 R2

   dwMilliseconds 값은 저전력 상태에서 소비되는 시간을 포함한다. 예를 들어, 시스템이 절전 상태인 동안 시간 timeout이 계속 카운트 다운된다.

 

  3) Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10, Windows Server 2016

   dwMilliseconds 값은 저전력 상태에서 소비되는 시간을 포함하지 않는다. 예를 들어, 시스템이 절전 상태인 동안 timeout이 계속 카운트 다운되지 않는다.

 

Return Value

 함수가 성공하면, return value는 함수를 반환하게 한 이벤트를 나타낸다. 다음 값 중 하나가 될 수 있다. (세부내용은 맨 위 출처 참조)

  WAIT_ABANDONED(0x00000080L), WAIT_OBJECT_0(0x00000000L), WAIT_TIMEOUT(0x00000102L), WAIT_FAILED(DWORD(0xFFFFFFFF))

 

Remarks

 (1) WaitForSingleObject 함수는 지정된 개체의 현재 상태를 점검한다. 개체의 상태가 신호가 아닌 경우 개체가 신호를 받거나 시간 초과 간격이 경과할 때까지 호출 thread가 대기 상태로 들어간다.

 

 (2) 이 함수는 일부 동기화 개체 유형의 상태를 수정한다. 신호 상태의 개체에 대한 수정은 함수를 반환하도록 한다. 예를 들어, 세마포어 개체의 개수는 한 개씩 줄어든다.

 

 (3) WaitForSingleObject 함수는 다음 개체를 기다릴 수 있다.

  1) Change notification

  2) Console input

  3) Event

  4) Memory resource notification

  5) Mutext

  6) Process

  7) Semaphore

  8) Thread

  9) Waitable timer

 

 (4) Windows를 직간접적으로 생성하는 코드와 대기 함수를 호출할 때는 주의해라. thread가 windows를 생성하면 process messages여야만 한다. Message broadcasts는 시스템의 모든 windows로 보내진다. 시간 초과 간격이 없는 대기 함수를 사용하는 thread는 시스템을 교착 상태로 만들 수 있다. 간접적으로 windows를 만드는 코드의 두 가지 예는 DDE와 CoInitialize 함수이다. 다라서 windows를 생성하는 thread가 있는 경우 WaitForSingleObject 대신 MsgWaitForMultipleObjects 또는 MsgWaitForMultipleObjectsEx를 사용해라.

 

Requirements

 (1) Minimum supported client

  Windows XP [desktop apps | UWSP apps}

 

 (2) Minimum supported server

  Windows Server 2003 [desktop apps | UWP apps]

 

 (3) Target Platform

  Windows

 

 (4) Header

  synchapi.h (include Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008, Windows Server 2008 R2, Windows.h)

 

 (5) Library

  Kernel32.lib

 

 (6) DLL

  Kernel32.dll