KeWaitForMultipleObjects 함수(wdm.h)

아티클
08/08/2023

KeWaitForMultipleObjects 루틴은 대기 시간이 초과될 때까지 현재 스레드를 경고 가능 또는 비인증 대기 상태로 전환합니다.

구문

NTSTATUS
KeWaitForMultipleObjects (
    ULONG Count,
    PVOID Object[],
    WaitType,
    KWAIT_REASON WaitReason,
    KPROCESSOR_MODE WaitMode,
    BOOLEAN Alertable,
    PLARGE_INTEGER Timeout,
    PKWAIT_BLOCK WaitBlockArray
    );

매개 변수

[in] Count

대기할 개체의 수입니다. 이 매개 변수는 Object 매개 변수가 가리키는 배열의 요소 수를 지정합니다.

[in] Object

호출자가 스토리지를 제공하는 디스패처 개체(이벤트, 뮤텍스, 세마포, 스레드 및 타이머)에 대한 포인터 배열에 대한 포인터입니다. 포인터 배열과 디스패처 개체는 모두 페이지가 없는 시스템 메모리에 있어야 합니다. 자세한 내용은 설명 부분을 참조하세요.

[in] WaitType

수행할 대기 작업의 유형입니다. 대기가 충족되기 전에 지정된 모든 개체가 신호 상태를 달성해야 함을 나타내는 WaitAll을 지정합니다. 또는 WaitAny- 대기가 충족되기 전에 개체 중 하나가 신호 상태를 달성해야 함을 나타냅니다.

[in] WaitReason

대기 이유입니다. 드라이버는 이 값을 Executive 로 설정하거나, 드라이버가 사용자를 대신하여 작업을 수행하고 사용자 스레드의 컨텍스트에서 실행 중인 경우 UserRequest로 설정해야 합니다.

[in] WaitMode

호출자가 KernelMode 또는 UserMode에서 대기하는지 여부입니다. 중간 및 최저 수준 드라이버는 KernelMode를 지정해야 합니다. 대기한 개체 집합에 뮤텍스가 포함된 경우 호출자는 KernelMode를 지정해야 합니다.

[in] Alertable

대기 중인 상태에서 스레드를 경고할 수 있는지 여부를 나타내는 부울 값입니다.

[in, optional] Timeout

대기가 완료될 절대 또는 상대 시간을 100나노초 단위로 지정하는 제한 시간 값에 대한 포인터입니다.

양수 값은 1601년 1월 1일을 기준으로 절대 시간을 지정합니다. 음수 값은 현재 시간을 기준으로 간격을 지정합니다. 절대 만료 시간은 시스템 시간의 변경 내용을 추적합니다. 상대 만료 시간은 시스템 시간 변경의 영향을 받지 않습니다.

*Timeout = 0이면 루틴은 기다리지 않고 반환됩니다. 호출자가 NULL 포인터를 제공하는 경우 루틴은 모든 디스패처 개체가 신호됨 상태로 설정될 때까지 무기한 대기합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[out, optional] WaitBlockArray

호출자가 할당한 KWAIT_BLOCK 배열에 대한 포인터입니다. Count<= THREAD_WAIT_OBJECTS WaitBlockArray는 NULL일 수 있습니다. 그렇지 않으면 이 매개 변수는 sizeof(KWAIT_BLOCK) * Count 바이트의 메모리 버퍼를 가리킵니다. 루틴은 대기 작업을 수행하는 동안 레코드 보관을 위해 이 버퍼를 사용합니다. WaitBlockArray 버퍼는 페이지가 없는 시스템 메모리에 있어야 합니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

KeWaitForMultipleObjects는 다음 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_SUCCESS	호출자가 WaitType 매개 변수에 대해 WaitAll을 지정하고 Object 배열의 모든 디스패처 개체가 신호 상태로 설정되었습니다.
STATUS_ALERTED	호출 스레드에 경고를 전달하기 위해 대기가 중단되었습니다.
STATUS_USER_APC	호출 스레드에 사용자 APC(비동기 프로시저 호출)를 제공하기 위해 대기가 중단되었습니다.
STATUS_TIMEOUT	지정된 대기 조건 집합이 충족되기 전에 시간 초과가 발생했습니다. 명시적 시간 제한 값 0을 지정한 경우 이 값을 반환할 수 있지만 지정된 대기 조건 집합을 즉시 충족할 수 없습니다.
STATUS_WAIT_63 통해 STATUS_WAIT_0	호출자가 WaitType에 대해 WaitAny를 지정하고 Object 배열의 디스패처 개체 중 하나가 신호 상태로 설정되었습니다. 반환 값의 하위 6비트 는 대기를 충족하는 개체의 인덱스(0부터 시작)를 인코딩합니다.
STATUS_ABANDONED_WAIT_63 통해 STATUS_ABANDONED_WAIT_0	호출자가 중단된 뮤텍스를 기다리려고 했습니다. 반환 값의 하위 6비트에서는 Object 배열에서 뮤텍스의 인덱스(0부터 시작)를 인코딩 합니다 .

NT_SUCCESS 매크로는 이러한 모든 상태 값을 "성공" 값으로 인식합니다.

설명

각 스레드 개체에는 여러 개체가 동시에 설정될 때까지 기다리는 데 사용할 수 있는 대기 블록의 기본 제공 배열이 있습니다. 추가 대기 블록 스토리지를 할당하지 않고 나중에 할당을 취소할 필요가 없으므로 가능하면 대기 블록의 기본 제공 배열을 대기 다중 작업에 사용해야 합니다. 그러나 동시에 대기해야 하는 개체 수가 기본 제공 대기 블록 수보다 큰 경우 WaitBlockArray 매개 변수를 사용하여 대기 작업에 사용할 대체 대기 블록 집합을 지정합니다. 드라이버는 WaitBlockArray에 대해 충분히 큰 메모리 버퍼를 할당하기만 하면 됩니다. 버퍼를 초기화할 필요가 없습니다. 그러나 페이지가 없는 시스템 메모리에서 할당해야 합니다. WaitMode 매개 변수가 UserMode인 경우 스택이 메모리 밖으로 교환될 수 있으므로 WaitBlockArray 버퍼를 로컬 스택에 할당하면 안 됩니다. 드라이버는 이 버퍼를 불투명 구조로 처리할 수 있으며 루틴이 반환된 후 해제할 수 있습니다. Count> MAXIMUM_WAIT_OBJECTS 또는 WaitBlockArray가 NULL이고 count> THREAD_WAIT_OBJECTS 경우 시스템에서 버그 검사 0xC(MAXIMUM_WAIT_OBJECTS_EXCEEDED)을 발급합니다.

지정된 각 개체의 현재 상태를 검사하여 대기를 즉시 충족할 수 있는지 여부를 확인합니다. 개체에 필요한 부작용이 수행되면 적절한 값이 반환됩니다.

대기를 즉시 충족할 수 없고 시간 제한 값이나 0이 아닌 시간 제한 값이 지정되지 않은 경우 현재 스레드는 대기 상태에 놓이고 현재 프로세서에서 실행하기 위해 새 스레드가 선택됩니다. 시간 제한이 제공되지 않으면 Object 및 WaitType에서 지정한 조건이 충족될 때까지 호출 스레드가 대기 상태로 유지됩니다.

시간 제한을 지정하면 지정된 간격이 만료될 때 지정된 대기 조건이 충족되지 않으면 대기가 자동으로 충족됩니다.

시간 제한 값이 0이면 대기 조건 집합을 테스트할 수 있으며, 뮤텍스를 획득할 때와 같이 대기가 즉시 충족될 수 있는 경우 조건부로 부작용을 수행할 수 있습니다.

시간 제한 간격은 시스템 클록을 기준으로 측정되며 운영 체제에서 제한 시간 간격의 끝을 검색할 수 있는 정확도는 시스템 클록의 세분성에 의해 제한됩니다. 자세한 내용은 타이머 정확도를 참조하세요.

경고 가능 매개 변수는 스레드를 경고할 수 있는 시기와 대기 상태가 결과적으로 중단되는 시기를 결정합니다. 자세한 내용은 대기 및 APC를 참조하세요.

Objects 매개 변수가 가리키는 배열은 페이지가 없는 시스템 메모리에 있어야 합니다. 일반적으로 드라이버는 로컬 스택의 Objects 배열에 대한 스토리지를 할당합니다. WaitMode 매개 변수 값에 관계없이 개체 배열을 로컬 스택에 할당할 수 있습니다.

개체 배열의 요소가 가리키는 디스패처 개체는 페이지가 없는 시스템 메모리에 있어야 합니다. WaitMode 매개 변수가 UserMode이면 대기 중에 커널 스택을 교환할 수 있습니다. 따라서 호출자는 UserMode 인수를 사용하여 KeWaitForMultipleObjects를 호출할 때 스택에 매개 변수를 전달하려고 시도해서는 안 됩니다. 스택에 이벤트를 할당하는 경우 WaitMode 매개 변수를 KernelMode로 설정해야 합니다.

KeWaitForMultipleObjects에 전달된 Object 매개 변수가 뮤텍스인 경우 특별한 고려 사항이 적용됩니다. 대기한 디스패처 개체가 뮤텍스인 경우 APC 배달은 대기하는 동안 다른 모든 디스패처 개체와 동일합니다. 그러나 KeWaitForMultipleObjects 가 STATUS_SUCCESS 함께 반환되고 스레드가 실제로 뮤텍스를 보유하면 특수 커널 모드 APC만 전달됩니다. 커널 모드와 사용자 모드 모두의 다른 모든 APC 배달은 사용하지 않도록 설정됩니다. APC 배달에 대한 이 제한은 뮤텍스가 해제될 때까지 유지됩니다.

KeWaitForMultipleObjects가 STATUS_USER_APC 또는 STATUS_ALERTED 상태 함께 일찍 반환될 수 있으므로 WaitMode 매개 변수가 UserMode이거나 Alertable이 TRUE인 경우 KeWaitForMultipleObjects의 반환 값을 검사 것이 특히 중요합니다.

사용자가 중단할 수 있는 모든 장기 대기는 UserMode 대기이고 경고 가능 은 FALSE로 설정해야 합니다.

가능한 경우 경고 가능 을 FALSE 로 설정하고 WaitMode 를 KernelMode로 설정하여 드라이버 복잡성을 줄여야 합니다. 이에 대한 주요 예외는 대기가 장기 대기인 경우입니다.

뮤텍스는 MINLONG 시간만 재귀적으로 획득할 수 있습니다. 이 제한을 초과하면 루틴에서 STATUS_MUTANT_LIMIT_EXCEEDED 예외가 발생합니다.

KeWaitForMultipleObjects의 호출자는 IRQL <= DISPATCH_LEVEL 실행할 수 있습니다. 그러나 Timeout = NULL 또는 *Timeout != 0인 경우 호출자는 IRQL <= APC_LEVEL 및 비비타적 스레드 컨텍스트에서 실행되어야 합니다. ( Timeout != NULL 및 *Timeout = 0인 경우 호출자는 IRQL <= DISPATCH_LEVEL 실행되어야 합니다.)

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	설명 섹션을 참조하십시오.
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), IrpProcessingComplete(wdm), IrqlKeWaitForMultipleObjects(wdm), SpNoWait(storport)