# mult_timer **Repository Path**: simpost/mult_timer ## Basic Information - **Project Name**: mult_timer - **Description**: 一个Linux下的超级精简的多重定时器:可实现成千上万个定时任务,定时精度可达纳秒级别,且同一时间点可添加不同的任务!适用于云后台服务和嵌入式等各种环境。 - **Primary Language**: C - **License**: MIT - **Default Branch**: master - **Homepage**: https://gitee.com/simpost/mult_timer - **GVP Project**: No ## Statistics - **Stars**: 252 - **Forks**: 100 - **Created**: 2019-05-05 - **Last Updated**: 2025-06-07 ## Categories & Tags **Categories**: utils **Tags**: None ## README # component template # ## 一、组件介绍 ### 1.1 概述 一个Linux下的超级简洁的定时器:*利用epoll机制和`timerfd`新特性实现的多重、多用、多个定时任务实现*。只需要使用`TIMER_CREATE()`接口创建一个定时器实体,即**可向其添加成千上万个定时任务,定时任务可达到纳秒级别的精度,且可在同一时间点添加不同的定时任务!**。 ### 1.2 分支介绍 - develop:开发主分支, 稳定分支; ### 1.3 版本说明 - *V0.1.0:* - *XXXX* - *XXXX* - *v0.2.0:* - *YYYY* - *YYYY* *列表形式展示组件历史版本及迭代功能说明。* ## 二、使用说明 ### 2.1 软件接口 整个定时器包含如下几类接口。 1. **创建和声明定时器实例**:使用定时器的第一步就是使用`TIMER_CREATE()`创建一个定时器实例,在其它文件使用到该定时器时,使用`TIMER_DECLEAR()`进行声明: ``` TIMER_CREATE(name); TIMER_DECLEAR(name); ``` 2. **初始化和反初始化定时器**:在正式使用定时器之前,首先使用`TIMER_INIT()`初始化前面创建的定时器实例,name是实例名称,max是创建定时器要检测的定时任务数量;当不再使用定时器时,可使用`TIMER_DEINIT()`反初始化定时器(退出定时器,并释放所有资源): ``` TIMER_INIT(name, max); TIMER_DEINIT(name); ``` 3. **添加和删除定时任务**: ``` TIMER_ADD(name, itimespec, repeat, cb, data, rb); TIMER_DEL(name, timerfd); ``` `TIMER_ADD()`用于向定时器实例name中添加一个定时任务,其参数描述如下: - `ittimespec`是定时任务的定时时间和循环时间,其结构体类型如下: ``` struct timespec { time_t tv_sec; // seconds long tv_nsec; // nanoseconds }; struct itimerspec { struct timespec it_value; struct timespec it_interval; }; ``` 其中`it_value`即是超时时间(相对时间),若想定义周期定时任务,则设置`it_interval`成员;若不想定义周期定时任务,则需设置`it_interval`成员都为0。因此,第一次超时和后面周期定时任务是可以使用不同时间的。 - `repeat`是周期定时任务的重复次数,若设置为**-1,代表永远重复;0,代表一次都不执行**;因此`repeat`应至少为1,或者使用-1; - `cb`为定时任务超时回调函数,其类型为:`void (*timer_callback_t)(void *data)`; - `data`为定时任务回调函数的参数,为`void *`类型,用户可指定为自己定义的结构体; `TIMER_ADD()`添加定时任务成功返回新定时任务的文件描述符,失败返回 < 0。返回的文件描述符,可用于在`TIMER_DEL()`中删除定时任务。 4. **查询和清空定时任务** ``` TIMER_COUNT(name); TIMER_CLEAR(name); ``` `TIMER_COUNT(name)`用于查询定时器实例name中现存的定时任务个数;`TIMER_CLEAR(name)`用于清空定时器实例name中的所有定时任务。 ### 2.2 使用实例 下面是一个非常简单的使用示例:共创建了两个定时任务,每个第一次超时都是3S,后面每隔1S超时一次;但第一个定时任务频次为8,第二个定时任务频次为3;当所有定时任务都超时后,输入回车即可退出: ``` #include #include #include #include "mt_timer.h" void timeout_handle(void *arg) { printf("[%ld]:timeout1\n", time(NULL)); } void timeout_handler(void *arg) { printf("[%ld]:timeout2\n", time(NULL)); } TIMER_CREATE(test); int main(void) { int timer; struct itimerspec itimespec; TIMER_INIT(test, 10); itimespec.it_value.tv_sec = 3; itimespec.it_value.tv_nsec = 0; itimespec.it_interval.tv_sec = 1; itimespec.it_interval.tv_nsec = 0; timer = TIMER_ADD(test, &itimespec, 8, timeout_handle, NULL); TIMER_ADD(test, &itimespec, 3, timeout_handler, NULL); printf("[%ld]:timer_add : %d\n", time(NULL), TIMER_COUNT(test)); sleep(4);//getchar(); TIMER_DEL(test, timer); printf("[%ld]:timer_del : %d\n", time(NULL), TIMER_COUNT(test)); TIMER_CLEAR(test); printf("[%ld]:timer_clear : %d\n", time(NULL), TIMER_COUNT(test)); getchar(); TIMER_DEINIT(test); return 0; } ``` ## 三、扩展阅读 - [`cmake`模板使用介绍](./docs/cmake_template.md) - [组件制品目录结构规范](./docs/component_directory.md)