内核式线程同步之waitable timer

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