高性能秒级定时器SDK编程参考手册
本文档适用于C/C++语言开发人员，用于在开发过程中进行参考，文档详细讲述秒级定时器相关函数的用法以及源码示例。
- 定时器的实现采用双数组和双向链表数据结构。
2、支持超大规模数量定时器
支持设置的定时器的数量没有限制，主要受主机物理内存限制。
3、效率高
设置和删除定时器的操作个定时器的数量操作，只涉及到数组元素地址定位，
和双向数组头部插入操作。
4、支持周期性时钟
1）支持一次性时钟
2) 支持指定周期时钟
3) 支持无限周期时钟
5、指定时刻时钟。
例如: 20200102030405，代表: 2020年1月2日3点4份5秒
6、设置时钟时可同时设置回调函数指针和输入参数。
精度精确到秒的应用场景。例如针对网络服务器程序：
1、连接远程服务器超时。
2、登录服务器超时。
3、周期性发送握手请求。
4、等待握手应答超时。
5、等待ACK超时。
6、其他周期性执行的任务情况。
7、定时执行任务的场景。
1、功能说明
此函数用来生成一个定时器管理器，执行成功后返回定时器管理器句柄，之后的操作都引用此句柄。
2、函数原型
HANDLE TVSysCreate(int nArraySize, time_t dtNow);
3、参数说明
- int nArraySize
输入参数, 时间轮数组的大小，必须大于1, 默认填写: 3600。
- time_t dtNow
输入参数, 当前时间戳。
4、返回值
执行成功时返回非NULL的句柄。
5、相关函数
TVSysDestroy()
示例1：
功能：生成一个定时器管理器。
#include "TimerMng.h"
int main(int argc, char* argv[])
{
time_t dtNow;
time(&dtNow);
HANDLE hTimerVM;
hTimerVM = TVSysCreate(3600, dtNow);
TVSysDestroy(hTimerVM);
return 0;
}
1、功能说明
此函数用来删除定时器管理器，删除后的句柄不能再被引用。
2、函数原型
int TVSysDestroy(HANDLE hTimerVM);
3、参数说明
1）HANDLE hTimerVM
输入参数，定时时钟管理器句柄。
4、返回值
返回0
5、相关函数
TVSysCreate()
1、回调函数调用时机
当定时器超时时执行由TVSetTimerCycle和TVSetTimerAtTime设置的回调函数。
2、回调函数定义
typedef bool (* LPTIMEROUTPROC)(HANDLE hTimerVM, HANDLE hTimerItem, void* pPara);
3、参数说明
1）HANDLE hTimerVM
输入参数, 定时时钟管理器句柄，此句柄由TVSysCreate函数生成。
2）HANDLE hTimer
输入参数， 当前处理定时器句柄，由调用函数TVSetTimerCycle、
TVSetTimerAtTime返回的句柄。
3）void* pPara
输入参数，就是调用调用函数TVSetTimerCycle、TVSetTimerAtTime时的
用户参数。
4、返回值
无。
1、功能说明
此函数用来设置周期性超时时钟。
2、函数原型
HANDLE TVSetTimerCycle(HANDLE hTimerVM, time_t dtNow,
unsigned int dwCycle, unsigned int dwTimes,
LPTIMEROUTPROC pProc, void* pPara);
3、参数说明
1）HANDLE hTimerVM
定时时钟管理器句柄，此句柄由TVSysCreate函数生成。
2）time_t dtNow
当前的时间戳。
3）unsigned int dwCycle
每次超时的间隔时长，单位为秒(s)。
4）unsigned int dwTimes
超时的次数，如果设置为0xFFFFFFFF,则超时的次数无限制。
5）LPTIMEROUTPROC pProc
回调函数指针，在定时器超时时调用此函数，调用此函数的线程为调用
TVCheckTimeOut函数的线程。
6）void* pPara
参数指针，在执行回调函数pProc时使用
4、返回值
返回定时器句柄。
1）NULL，设置定时器失败。
2）其它，设置定时器成功。
5、相关函数
TVSetTimeAtTime()
TVKillTimer()
1、功能说明
此函数用来设置指定时刻的定时器，回调函数只被触发执行一次。
2、函数原型
HANDLE TVSetTimerAtTime(HANDLE hTimerVM, time_t dtNow, char*
sDateTime, LPTIMEROUTPROC pProc, void* pPara);
3、参数说明
1）HANDLE hTimerVM
定时时钟管理器句柄，此句柄由TVSysCreate函数生成。
2）time_t dtNow
当前的时间戳。
3）指定超时时刻
格式为:YYYYMMDDHHMMSS。
分别为：
（1）年（4个字符）、
（2）月（2个字符）
赋值范围：01~12
（3）日（2个字符）
赋值范围：01~31
（4）小时（2个字符）
赋值范围：00~23
（5）分钟（2个字符）
赋值范围：00~59
（6）秒（2个字符）
赋值范围：00~59
例如：如果要设置超时时刻为:2010年1月2日3时4分5秒触发的定
时器，sTimer值为:20100102030405
4）LPTIMEROUTPROC pProc
回调函数指针，在定时器超时时调用此函数，调用此函数的线程为调用
TVCheckTimeOut函数的线程。
5）void* pPara
参数指针，在执行回调函数pProc时使用
4、返回值
返回定时器句柄。
1）NULL，设置定时器失败。
2）其它，设置定时器成功。
5、相关函数
TVSetTimeCycle()
TVKillTimer()
1、功能说明
此函数用来根据定时器句柄删除一个定时器。注意：达到定时触发次数的定时器是由管理器自动删除，不需要也不许可调用TVKillTimer。
2、函数原型
void TVKillTimer(HANDLE hTimerVM, HANDLE hTimer);
3、参数说明
1）HANDLE hTimerVM
定时器管理器句柄，此句柄由TVSysCreate函数生成。
2）HANDLE hTimer
要删除的定时器句柄，由调用函数TVSetTimerCycle、TVSetTimerAtTime
返回的句柄。
4、返回值
无。
5、相关函数
TVSetTimeCycle()
TVSetTimeAtTime()
1、功能说明
此函数用来获取定时器管理器中目前设置的定时器总数。
2、函数原型
int TVGetCount(HANDLE hTimerVM);
3、参数说明
1）HANDLE hTimerVM
定时器管理器句柄，此句柄由TVSysCreate函数生成。
4、返回值
返回定时器的数量，>= 0。
5、相关函数
TVSetTimerCycle()
TVSetTimerAtTime()
TVKillTimer()
1、功能说明
此函数用来检查定时时钟管理器中的所有定时器,按照超时的递增顺序检
查，对每个超时的定时器执行回调函数，然后对超时次数减一，如果达到超
时次数，根据回调函数返回值来决定是否自动删除该定时器。此函数每秒要执行一次。
2、函数原型
void TVCheckTimeOut(HANDLE hTimerVM);
3、参数说明
1）HANDLE hTimerVM
定时时钟管理器句柄，此句柄由TVSysCreate函数生成。
4、返回值
无
5、相关函数
#include <stdio.h>
#include <stdlib.h>
#include <windows.h>
#include "TimerMng.h"
// 回调函数
void TimeOutProc(HANDLE hTimerVM, HANDLE hTimerItem, void* pPara)
{
printf("定时器索引: %d \r\n", int(pPara));
}
int main(int nArgc, char* sArgv[])
{
time_t dtNow;
time(&dtNow);
HANDLE hTimerVM;
hTimerVM = TVSysCreate(3600, dtNow);
HANDLE hTimerArray[10];
hTimerArray[0] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)0);
hTimerArray[1] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)1);
hTimerArray[2] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)2);
hTimerArray[3] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)3);
hTimerArray[4] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)4);
hTimerArray[5] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)5);
hTimerArray[6] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)6);
hTimerArray[7] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)7);
hTimerArray[8] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)8);
hTimerArray[9] = TVSetTimerAtTime(hTimerVM, dtNow, "20200720115200", TimeOutProc,
(void*)9);
while(TVGetCount(hTimerVM) > 0)
{
time_t dtLast;
time(&dtLast);
if(dtLast > dtNow)
{
TVCheckTimeOut(hTimerVM, dtNow);
dtNow = dtLast;
}
Sleep(1);
}
char sKey[32];
gets(sKey);
TVSysDestroy(hTimerVM);
return 0;
}
- demo - 周期性定时器
#include <stdio.h>
#include <stdlib.h>
#include <windows.h>
#include "TimerMng.h"
// 回调函数
void TimeOutProc(HANDLE hTimerVM, HANDLE hTimerItem, void* pPara)
{
printf("定时器索引: %d \r\n", int(pPara));
}
int main(int nArgc, char* sArgv[])
{
time_t dtNow;
time(&dtNow);
HANDLE hTimerVM;
hTimerVM = TVSysCreate(3600, dtNow);
HANDLE hTimerArray[10];
int i;
for (i = 0; i < 10; i++)
{
hTimerArray[i] = TVSetTimerCycle(hTimerVM, dtNow, 1, 10, TimeOutProc, (void *)i);
}
while(TVGetCount(hTimerVM) > 0)
{
time_t dtLast;
time(&dtLast);
if(dtLast > dtNow)
{
TVCheckTimeOut(hTimerVM, dtNow);
dtNow = dtLast;
}
Sleep(1);
}
char sKey[32];
gets(sKey);
TVSysDestroy(hTimerVM);
return 0;
}
1、使用才定时器SDK，系统的时间不可更改，否则会造成软件运行异常。
2、注意，定时器时钟必须删除，否则会造成内存泄漏。
3、时钟管理器是线程不安全，如果是由多线程操作必须加互斥锁。
推荐阅读