WaitForSingleObject

WaitForSingleObject是一種Windows API函式，當等待仍在掛起狀態時，句柄被關閉，那么函式行為是未定義的。該句柄必須具有 SYNCHRONIZE 訪問許可權。

WaitForSingleObject函式用來檢測hHandle事件的信號狀態，在某一執行緒中調用該函式時，執行緒暫時掛起，如果在掛起的dwMilliseconds毫秒內，執行緒所等待的對象變為有信號狀態，則該函式立即返回；如果逾時時間已經到達dwMilliseconds毫秒，但hHandle所指向的對象還沒有變成有信號狀態，函式照樣返回。

基本介紹

• 中文名：WaitForSingleObject
• 外文名：WaitForSingleObject
• 聲明位置：synchapi.h
• 返回值類型：unsigned long
• 調用方式：__stdcall
• 參數類型：(void*,unsigned long)

對應函式

VC聲明

DWORD WaitForSingleObject(

HANDLE hHandle,

DWORD dwMilliseconds

);

VB聲明

Declare Function WaitForSingleObject Lib "kernel32" (ByVal hHandle As Long, ByVal dwMilliseconds As Long) As Long

說明

DWORD WINAPI WaitForSingleObject(

__in HANDLE hHandle,

__in DWORD dwMilliseconds

);

參數

hHandle[in]對象句柄。可以指定一系列的對象，如Event、Job、Memory resource notification、Mutex、Process、Semaphore、Thread、Waitable timer等。

dwMilliseconds[in]定時時間間隔，單位為milliseconds（毫秒）.如果指定一個非零值，函式處於等待狀態直到hHandle標記的對象被觸發，或者時間到了。如果dwMilliseconds為0，對象沒有被觸發信號，函式不會進入一個等待狀態，它總是立即返回。如果dwMilliseconds為INFINITE，對象被觸發信號後，函式才會返回。

返回值

執行成功，返回值指示出引發函式返回的事件。它可能為以下值：

WAIT_ABANDONED0x00000080L	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread and the mutex state is set to nonsignaled.; If the mutex was protecting persistent state information, you should check it for consistency.
WAIT_OBJECT_00x00000000L	The state of the specified object is signaled.
WAIT_TIMEOUT0x00000102L	The time-out interval elapsed, and the object's state is nonsignaled.
WAIT_FAILED(DWORD)0xFFFFFFFF	The function has failed. To get extended error information, callGetLastError.

參數dwMilliseconds有兩個具有特殊意義的值：0和INFINITE。若為0，則該函式立即返回；若為INFINITE，則執行緒一直被掛起，直到hHandle所指向的對象變為有信號狀態時為止。

WAIT_ABANDONED 0x00000080：當hHandle為mutex時，如果擁有mutex的執行緒在結束時沒有釋放核心對象會引發此返回值。

WAIT_OBJECT_0 0x00000000 ：指定的對象出有有信號狀態

WAIT_TIMEOUT 0x00000102：等待逾時

WAIT_FAILED 0xFFFFFFFF ：出現錯誤，可通過GetLastError得到錯誤代碼

在這裡舉個例子：

先創建一個全局Event對象g_event:

CEvent g_event;

在程式中可以通過調用CEvent::SetEvent設定事件為有信號狀態。

下面是一個執行緒函式MyThreadProc()

UINT CFlushDlg::MyThreadProc( LPVOID pParam ){WaitForSingleObject(g_event,INFINITE);For(;;){………….}return 0;}

在這個執行緒函式中只有設定g_event為有信號狀態時才執行下面的for循環，因為g_event是全局變數，所以我們可以在別的執行緒中通過g_event. SetEvent控制這個執行緒。

還有一種用法就是我們可以通過WaitForSingleObject函式來間隔的執行一個執行緒函式的函式體

UINT CFlushDlg::MyThreadProc( LPVOID pParam ){while(WaitForSingleObject(g_event,MT_INTERVAL)!=WAIT_OBJECT_0){………………}return 0;}

在這個執行緒函式中可以通過設定MT_INTERVAL來控制這個執行緒的函式體多久執行一次，當事件為無信號狀態時函式體隔MT_INTERVAL執行一次，當設定事件為有信號狀態時，執行緒就執行完畢了。