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函数。