waitable timer
顧名思義，就是隔一段時間被signaled的一種內核對象。waitable timer跟event對象一樣可以在創建的時候指定reset方式，如果是manual-reset，那么當waitable timer對象被signaled時，所有等待這個對象的wait函數都會返回。如果是auto-reset那么就只有一個wait函數會返回。
創建完waitable timer對象后，必須通過SetWaitableTimer函數對它進行時間上的設置。時間格式是個問題，看下面代碼
// Declare our local variables.
HANDLE hTimer;
SYSTEMTIME st;
FILETIME ftLocal, ftUTC;
LARGE_INTEGER liUTC;
// Create an auto-reset timer.
hTimer = CreateWaitableTimer(NULL, FALSE, NULL);
// First signaling is at January 1, 2002, at 1:00 P.M. (local time).
st.wYear = 2002; // Year
st.wMonth = 1; // January
st.wDayOfWeek = 0; // Ignored
st.wDay = 1; // The first of the month
st.wHour = 13; // 1PM
st.wMinute = 0; // 0 minutes into the hour
st.wSecond = 0; // 0 seconds into the minute
st.wMilliseconds = 0; // 0 milliseconds into the second
SystemTimeToFileTime(&st, &ftLocal);
// Convert local time to UTC time.
LocalFileTimeToFileTime(&ftLocal, &ftUTC);
// Convert FILETIME to LARGE_INTEGER because of different alignment.
liUTC.LowPart = ftUTC.dwLowDateTime;
liUTC.HighPart = ftUTC.dwHighDateTime;
// Set the timer.
SetWaitableTimer(hTimer, &liUTC, 6 * 60 * 60 * 1000, NULL, NULL, FALSE);
上面的代碼查下MSDN應該很容易理解，這里要說的是CPU對齊的問題。FILETIME結構必須位于32位邊界，而LARGE_INTEGER必須位于64位邊界，所以不能將FILETIME直接傳給SetWaitableTimer。
SetWaitableTimer也可以使用時間的絕對值，或者使用相對時間值。不過這時的值必須是負的。看下面代碼：
// Declare our local variables.
HANDLE hTimer;
LARGE_INTEGER li;
// Create an auto-reset timer.
hTimer = CreateWaitableTimer(NULL, FALSE, NULL);
// Set the timer to go off 5 seconds after calling SetWaitableTimer.
// Timer unit is 100-nanoseconds.
const int nTimerUnitsPerSecond = 10000000;
// Negate the time so that SetWaitableTimer knows we
// want relative time instead of absolute time.
// This indicate that the timer will be signaled 5 seconds after the call to SetWaitableTimer
li.QuadPart = -(5 * nTimerUnitsPerSecond);
// Set the timer.
SetWaitableTimer(hTimer, &li, 6 * 60 * 60 * 1000, NULL, NULL, FALSE);
清除waitable timer對象需要用到CancelWaitableTimer函數。
特別提出的是waitable timer這節引出了一個新概念：APC(asynchronous procedure call)。按照我的理解，APC應該是線程特有的一個隊列，里面裝的是函數地址。如果一個函數地址被裝入APC，如果這時線程處于待命的等待狀態（alertable wait），那么這個線程就會被喚醒去調用APC里的函數；否則，APC里的函數地址就會被忽略掉。這里的這個線程指的是調用SetWaitableTimer的線程。下面的代碼能說明問題
VOID APIENTRY TimerAPCRoutine(PVOID pvArgToCompletionRoutine,
DWORD dwTimerLowValue, DWORD dwTimerHighValue) 
{
FILETIME ftUTC, ftLocal;
SYSTEMTIME st;
TCHAR szBuf[256];
// Put the time in a FILETIME structure.
ftUTC.dwLowDateTime = dwTimerLowValue;
ftUTC.dwHighDateTime = dwTimerHighValue;
// Convert the UTC time to the user's local time.
FileTimeToLocalFileTime(&ftUTC, &ftLocal);
// Convert the FILETIME to the SYSTEMTIME structure
// required by GetDateFormat and GetTimeFormat.
FileTimeToSystemTime(&ftLocal, &st);
// Construct a string with the
// date/time that the timer went off.
GetDateFormat(LOCALE_USER_DEFAULT, DATE_LONGDATE,
&st, NULL, szBuf, sizeof(szBuf) / sizeof(TCHAR));
_tcscat(szBuf, _ _TEXT(" "));
GetTimeFormat(LOCALE_USER_DEFAULT, 0,
&st, NULL, _tcschr(szBuf, 0),
sizeof(szBuf) / sizeof(TCHAR) - _tcslen(szBuf));
// Show the time to the user.
MessageBox(NULL, szBuf, "Timer went off at", MB_OK);
}
void SomeFunc() {
// Create a timer. (It doesn't matter whether it's manual-reset
// or auto-reset.)
HANDLE hTimer = CreateWaitableTimer(NULL, TRUE, NULL);
// Set timer to go off in 5 seconds.
LARGE_INTEGER li = { 0 };
SetWaitableTimer(hTimer, &li, 5000, TimerAPCRoutine, NULL, FALSE);
// Wait in an alertable state for the timer to go off.
SleepEx(INFINITE, TRUE);
CloseHandle(hTimer);
}
如果指定了APC，那么就不要等待這個waitable timer對象了，因為APC隊列會喚醒線程的，不需要wait函數。