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
타이머 기간(밀리초)입니다. 이 매개 변수가 0이면 타이머에 한 번 신호가 전송됩니다. 이 매개 변수가 0보다 크면 타이머가 주기적입니다. 주기적 타이머는 타이머가 취소될 때까지 기간이 경과할 때마다 자동으로 다시 활성화됩니다.
[in] Flags
이 매개 변수는 WinNT.h의 다음 값 중 하나 이상일 수 있습니다.
| 값 | 의미 |
|---|---|
|
기본적으로 콜백 함수는 I/O가 아닌 작업자 스레드에 큐에 대기됩니다. |
|
콜백 함수는 타이머 스레드 자체에 의해 호출됩니다. 이 플래그는 짧은 작업에만 사용하거나 다른 타이머 작업에 영향을 줄 수 있습니다.
콜백 함수는 APC로 큐에 대기됩니다. 경고 가능한 대기 작업을 수행해서는 안 됩니다. |
|
이 플래그는 사용되지 않습니다.
Windows Server 2003 및 Windows XP: 콜백 함수는 I/O 작업자 스레드에 큐에 대기됩니다. 경고 가능한 상태에서 대기하는 스레드에서 함수를 실행해야 하는 경우 이 플래그를 사용해야 합니다. I/O 작업자 스레드는 Windows Vista 및 Windows Server 2008부터 제거되었습니다. |
|
콜백 함수는 종료되지 않는 스레드에 큐에 대기됩니다. 매번 동일한 스레드가 사용된다는 보장은 없습니다. 이 플래그는 짧은 작업에만 사용하거나 다른 타이머 작업에 영향을 줄 수 있습니다.
스레드가 APC를 사용하는 함수를 호출하는 경우 이 플래그를 설정해야 합니다. 자세한 내용은 비동기 프로시저 호출을 참조하세요. 보류 중인 I/O 요청이 있는 경우 작업자 스레드가 종료되지 않지만 현재는 어떤 작업자 스레드도 실제로 지속되지 않습니다. |
|
콜백 함수는 긴 대기를 수행할 수 있습니다. 이 플래그는 시스템에서 새 스레드를 만들어야 하는지 여부를 결정하는 데 도움이 됩니다. |
|
타이머는 신호가 지정된 상태로 한 번만 설정됩니다. 이 플래그가 설정되면 Period 매개 변수는 0이어야 합니다. |
|
콜백 함수는 프로세스든 가장 토큰이든 관계없이 현재 액세스 토큰을 사용합니다. 이 플래그를 지정하지 않으면 콜백 함수는 프로세스 토큰으로만 실행됩니다.
Windows XP: 이 플래그는 WINDOWS XP SP2 및 Windows Server 2003까지 지원되지 않습니다. |
반환 값
함수가 성공하면 반환 값이 0이 아닙니다.
함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.
설명
DueTime 및 Period 매개 변수가 모두 0이 아닌 경우 타이머는 기한에 먼저 신호를 받은 다음 주기적으로 신호를 보냅니다. 콜백은 이전 콜백 실행이 완료되었는지 여부에 관계없이 기간이 경과할 때마다 호출됩니다. 콜백 함수는 스레드 풀에 큐에 대기됩니다. 이러한 스레드는 예약 지연의 영향을 받으므로 애플리케이션 또는 시스템에서 발생하는 다른 사항에 따라 타이밍이 달라질 수 있습니다.
시스템이 절전 모드 또는 최대 절전 모드에서 소비하는 시간은 타이머 만료에 포함되지 않습니다. 타이머는 시스템이 절전 모드에서 소비하는 누적 경과 시간이 타이머의 기한 또는 기간과 일치할 때 신호를 보냅니다.
Windows Server 2003 및 Windows XP: 시스템이 절전 모드 또는 최대 절전 모드에서 소비하는 시간은 타이머 만료 횟수입니다. 시스템이 절전 모드인 동안 타이머가 만료되면 시스템이 절전 모드에서 해제될 때 타이머가 즉시 신호를 보냅니다.
타이머를 취소하려면 DeleteTimerQueueTimer 함수를 호출합니다. 타이머 큐의 모든 타이머를 취소하려면 DeleteTimerQueueEx 함수를 호출합니다.
기본적으로 스레드 풀에는 최대 500개의 스레드가 있습니다. 이 제한을 높이려면 WinNT.h에 정의된 WT_SET_MAX_THREADPOOL_THREAD 매크로를 사용합니다.
#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 |
| 헤더 | threadpoollegacyapiset.h |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |