WaitForMultipleObjects 함수(synchapi.h)

  • 아티클

지정된 개체 중 하나 또는 전부가 신호 상태 또는 시간 제한 간격이 경과할 때까지 기다립니다.

경고 대기 상태를 입력하려면 WaitForMultipleObjectsEx 함수를 사용합니다.

구문

DWORD WaitForMultipleObjects(
  [in] DWORD        nCount,
  [in] const HANDLE *lpHandles,
  [in] BOOL         bWaitAll,
  [in] DWORD        dwMilliseconds
);

매개 변수

[in] nCount

lpHandles가 가리키는 배열의 개체 핸들 수입니다. 개체 핸들의 최대 수는 MAXIMUM_WAIT_OBJECTS. 이 매개 변수는 0일 수 없습니다.

[in] lpHandles

개체 핸들의 배열입니다. 핸들을 지정할 수 있는 개체 형식 목록은 다음 설명 섹션을 참조하세요. 배열에는 다양한 형식의 개체에 대한 핸들이 포함될 수 있습니다. 동일한 핸들의 여러 복사본을 포함하지 않을 수 있습니다.

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

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

[in] bWaitAll

이 매개 변수가 TRUE이면 lpHandles 배열에 있는 모든 개체의 상태가 신호를 받으면 함수가 반환됩니다. FALSE이면 개체 중 하나의 상태가 신호로 설정되면 함수가 반환됩니다. 후자의 경우 반환 값은 함수가 반환되도록 상태가 된 개체를 나타냅니다.

[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, Windows 8.1, Windows Server 2012 R2, Windows 10 및 Windows Server 2016: 절전 상태에서 소요된 시간이 dwMilliseconds 값에 포함되지 않습니다. 예를 들어 컴퓨터가 절전 모드인 동안에는 제한 시간이 카운트다운되지 않습니다.

반환 값

함수가 성공하면 반환 값은 함수가 반환된 이벤트를 나타냅니다. 다음 값 중 하나일 수 있습니다. (WAIT_OBJECT_0 0으로 정의되고 WAIT_ABANDONED_0 0x00000080L로 정의됩니다.

반환 코드/값 설명
(WAIT_OBJECT_0nCount – 1)에 WAIT_OBJECT_0 +
bWaitAll이 TRUE이면 지정된 범위 내의 반환 값은 지정된 모든 개체의 상태가 신호임을 나타냅니다.

bWaitAll이 FALSE이면 반환 값에서 WAIT_OBJECT_0 뺀 값은 대기를 충족하는 개체의 lpHandles 배열 인덱스를 나타냅니다. 호출 중에 둘 이상의 개체가 신호를 받은 경우 신호가 있는 모든 개체의 인덱스 값이 가장 작은 신호 개체의 배열 인덱스입니다.
(WAIT_ABANDONED_0nCount – 1)에 WAIT_ABANDONED_0 +
bWaitAll이 TRUE이면 지정된 범위 내의 반환 값은 지정된 모든 개체의 상태가 신호를 받고 하나 이상의 개체가 중단된 뮤텍스 개체임을 나타냅니다.

bWaitAll이 FALSE이면 반환 값에서 WAIT_ABANDONED_0 뺀 값은 대기를 충족하는 중단된 뮤텍스 개체의 lpHandles 배열 인덱스를 나타냅니다. 뮤텍스 개체의 소유권은 호출 스레드에 부여되고 뮤텍스는 서명되지 않은 것으로 설정됩니다.

뮤텍스가 영구 상태 정보를 보호하는 경우 일관성을 위해 검사 합니다.
WAIT_TIMEOUT
0x00000102L
 시간 제한 간격이 경과하고 bWaitAll 매개 변수에 지정된 조건이 충족되지 않습니다.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 함수가 실패했습니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

설명

WaitForMultipleObjects 함수는 대기 조건이 충족되었는지 여부를 결정합니다. 조건이 충족되지 않으면 대기 조건의 조건이 충족되거나 시간 제한 간격이 경과할 때까지 호출 스레드가 대기 상태로 들어갑니다.

bWaitAll이 TRUE이면 모든 개체의 상태가 신호로 설정된 경우에만 함수의 대기 작업이 완료됩니다. 함수는 모든 개체의 상태가 신호로 설정될 때까지 지정된 개체의 상태를 수정하지 않습니다. 예를 들어 뮤텍스는 신호를 받을 수 있지만 다른 개체의 상태도 신호로 설정될 때까지 스레드는 소유권을 얻지 못합니다. 그 동안 일부 다른 스레드는 뮤텍스의 소유권을 얻을 수 있으므로 상태를 서명되지 않은 상태로 설정할 수 있습니다.

bWaitAll이 FALSE이면 이 함수는 개체 중 하나가 신호를 보낼 때까지 인덱스 0부터 시작하여 배열의 핸들을 확인합니다. 여러 개체가 신호를 받으면 함수는 개체가 신호를 받은 배열에서 첫 번째 핸들의 인덱스 를 반환합니다.

함수는 일부 유형의 동기화 개체의 상태를 수정합니다. 수정은 신호 상태가 함수가 반환되도록 한 개체 또는 개체에 대해서만 발생합니다. 예를 들어 세마포 개체의 수가 1씩 감소합니다. 자세한 내용은 개별 동기화 개체에 대한 설명서를 참조하세요.

MAXIMUM_WAIT_OBJECTS 개 이상의 핸들을 기다리려면 다음 방법 중 하나를 사용합니다.

  • MAXIMUM_WAIT_OBJECTS 핸들을 대기할 스레드를 만든 다음 해당 스레드와 다른 핸들을 기다립니다. 이 기술을 사용하여 핸들을 MAXIMUM_WAIT_OBJECTS 그룹으로 분리합니다.
  • RegisterWaitForSingleObject 또는 SetThreadpoolWait를 호출하여 각 핸들을 기다립니다. 스레드 풀은 핸들에서 효율적으로 대기하고 개체가 신호를 수신하거나 시간 제한 간격이 만료된 후 작업자 스레드를 할당합니다.
WaitForMultipleObjects 함수는 lpHandles 배열에서 다음 개체 형식의 핸들을 지정할 수 있습니다.
  • 변경 알림
  • 콘솔 입력
  • 이벤트
  • 메모리 리소스 알림
  • Mutex
  • 프로세스
  • 세마포
  • 스레드
  • 대기 가능한 타이머
직접 또는 간접적으로 창을 만드는 대기 함수 및 코드를 호출할 때는 주의해야 합니다. 스레드가 창을 만드는 경우 메시지를 처리해야 합니다. 메시지 브로드캐스트는 시스템의 모든 창으로 전송됩니다. 시간 제한 간격 없이 대기 함수를 사용하는 스레드는 시스템이 교착 상태가 될 수 있습니다. 간접적으로 창을 만드는 코드의 두 가지 예는 DDE 및 CoInitialize 함수입니다. 따라서 창을 만드는 스레드가 있는 경우 WaitForMultipleObjects 대신 MsgWaitForMultipleObjects 또는 MsgWaitForMultipleObjectsEx를 사용합니다.

예제

예를 들어 여러 개체 대기를 참조하세요.

요구 사항

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

참고 항목

WAIT_ABANDONED_0

동기화 함수

대기 함수