Поделиться через


Функция CreateTimerQueueTimer (threadpoollegacyapiset.h)

Создает таймер очереди таймера. Срок действия таймера истекает в указанное время, а затем по истечении каждого указанного периода. По истечении срока действия таймера вызывается функция обратного вызова.

Синтаксис

BOOL CreateTimerQueueTimer(
  [out]          PHANDLE             phNewTimer,
  [in, optional] HANDLE              TimerQueue,
  [in]           WAITORTIMERCALLBACK Callback,
  [in, optional] PVOID               Parameter,
  [in]           DWORD               DueTime,
  [in]           DWORD               Period,
  [in]           ULONG               Flags
);

Параметры

[out] phNewTimer

Указатель на буфер, который получает дескриптор таймера очереди таймера при возврате. Когда срок действия этого дескриптора истек и он больше не требуется, отпустите его, вызвав Метод DeleteTimerQueueTimer.

[in, optional] TimerQueue

Дескриптор очереди таймера. Этот дескриптор возвращается функцией CreateTimerQueue .

Если этот параметр имеет значение NULL, таймер связан с очередью таймера по умолчанию.

[in] Callback

Указатель на определяемую приложением функцию типа WAITORTIMERCALLBACK , выполняемую по истечении срока действия таймера. Дополнительные сведения см. в разделе WaitOrTimerCallback.

[in, optional] Parameter

Значение одного параметра, которое будет передано функции обратного вызова.

[in] DueTime

Время в миллисекундах относительно текущего времени, которое должно пройти до первого сигнала таймера.

[in] Period

Период таймера в миллисекундах. Если этот параметр равен нулю, таймер получает сигнал один раз. Если этот параметр больше нуля, таймер является периодическим. Периодический таймер автоматически активируется каждый раз, когда истекает период, пока таймер не будет отменен.

[in] Flags

Этот параметр может иметь одно или несколько из следующих значений из WinNT.h.

Значение Значение
WT_EXECUTEDEFAULT
0x00000000
По умолчанию функция обратного вызова помещается в очередь в рабочий поток, отличный от ввода-вывода.
WT_EXECUTEINTIMERTHREAD
0x00000020
Функция обратного вызова вызывается самим потоком таймера. Этот флаг следует использовать только для коротких задач, иначе он может повлиять на другие операции таймера.

Функция обратного вызова помещается в очередь как APC. Он не должен выполнять операции ожидания с оповещением.

WT_EXECUTEINIOTHREAD
0x00000001
Этот флаг не используется.

Windows Server 2003 и Windows XP: Функция обратного вызова помещается в очередь в рабочий поток ввода-вывода. Этот флаг следует использовать, если функция должна выполняться в потоке, который ожидает оповещения.

Рабочие потоки ввода-вывода были удалены начиная с Windows Vista и Windows Server 2008.

WT_EXECUTEINPERSISTENTTHREAD
0x00000080
Функция обратного вызова помещается в очередь в поток, который никогда не завершается. Это не гарантирует, что один и тот же поток будет использоваться каждый раз. Этот флаг следует использовать только для коротких задач, иначе он может повлиять на другие операции таймера.

Этот флаг необходимо установить, если поток вызывает функции, использующие APC. Дополнительные сведения см. в разделе Асинхронные вызовы процедур.

Обратите внимание, что в настоящее время ни один рабочий поток не является действительно постоянным, хотя ни один рабочий поток не завершит работу, если есть ожидающие запросы ввода-вывода.

WT_EXECUTELONGFUNCTION
0x00000010
Функция обратного вызова может выполнять длительное ожидание. Этот флаг помогает системе решить, следует ли создавать новый поток.
WT_EXECUTEONLYONCE
0x00000008
Таймер будет установлен в состояние сигнала только один раз. Если этот флаг установлен, параметр Period должен быть равен нулю.
WT_TRANSFER_IMPERSONATION
0x00000100
Функции обратного вызова будут использовать текущий маркер доступа, будь то маркер процесса или токен олицетворения. Если этот флаг не указан, функции обратного вызова выполняются только с маркером процесса.

Windows XP: Этот флаг не поддерживается до Windows XP с пакетом обновления 2 (SP2) и Windows Server 2003.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Если параметры DueTime и Period не равны нулю, таймер будет сигнализировать сначала в срок, а затем периодически. Обратный вызов вызывается каждый раз, когда истекает период, независимо от того, завершился ли предыдущий обратный вызов. Функции обратного вызова помещаются в очередь в пул потоков. Эти потоки подвержены задержкам планирования, поэтому время может отличаться в зависимости от того, что еще происходит в приложении или системе.

Время, которое система проводит в спящем режиме или гибернации, не учитывается при истечении срока действия таймера. Таймер получает сигнал, когда совокупное количество затраченного времени, которое система проводит в состоянии пробуждения, соответствует времени или периоду выполнения таймера.

Windows Server 2003 и Windows XP: Время, которое система проводит в спящем режиме или гибернации, учитывается в истечении срока действия таймера. Если срок действия таймера истекает, когда система находится в спящем режиме, таймер немедленно получает сигнал при выходе системы из спящего режима.

Чтобы отменить таймер, вызовите функцию DeleteTimerQueueTimer . Чтобы отменить все таймеры в очереди таймера, вызовите функцию DeleteTimerQueueEx .

По умолчанию пул потоков содержит не более 500 потоков. Чтобы увеличить это ограничение, используйте макрос WT_SET_MAX_THREADPOOL_THREAD , определенный в WinNT.h.

#define WT_SET_MAX_THREADPOOL_THREADS(Flags,Limit) \
    ((Flags)|=(Limit)<<16)

Используйте этот макрос при указании параметра Flags . Параметры макроса — это нужные флаги и новое ограничение (до (2<<16)-1 потоков). Однако обратите внимание, что приложение может повысить свою производительность, сохраняя низкое количество рабочих потоков.

Чтобы скомпилировать приложение, использующее эту функцию, определите _WIN32_WINNT как 0x0500 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

Примеры

Пример использования CreateTimerQueueTimer см. в разделе Использование очередей таймера.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header threadpoollegacyapiset.h
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

CreateTimerQueue

DeleteTimerQueueEx

DeleteTimerQueueTimer

Функции синхронизации

Группировка потоков в пул

Очереди таймера