147 lines
3.9 KiB
Markdown
147 lines
3.9 KiB
Markdown
# libtask — 任务框架 API 参考
|
||
|
||
## 模块概述
|
||
|
||
libtask 是嵌入式装置的通用任务调度框架，包含三个子系统：
|
||
- **定时器**：基于 timerfd + epoll 精确毫秒级定时
|
||
- **事件**：基于位图 + pthread 条件变量的同步原语
|
||
- **消息队列**：基于环形缓冲区的线程安全 FIFO
|
||
|
||
## 常量与类型
|
||
|
||
### 定时器标志
|
||
| 宏 | 值 | 说明 |
|
||
|----|-----|------|
|
||
| `TASK_TIMER_FLAG_ONCE` | 0x01 | 单次触发 |
|
||
| `TASK_TIMER_FLAG_PERIODIC` | 0x02 | 周期触发 |
|
||
|
||
### 事件标志
|
||
| 宏 | 值 | 说明 |
|
||
|----|-----|------|
|
||
| `TASK_EVENT_WAIT_FOREVER` | 0xFFFFFFFF | 永久等待 |
|
||
| `TASK_EVENT_FLAG_AND` | 0x01 | AND 模式（所有位都置位） |
|
||
| `TASK_EVENT_FLAG_OR` | 0x02 | OR 模式（任意位置位） |
|
||
| `TASK_EVENT_FLAG_CLEAR` | 0x04 | 接收后自动清除 |
|
||
|
||
### 回调类型
|
||
```c
|
||
typedef void (*timer_func_cb)(void *arg);
|
||
```
|
||
|
||
### 不透明句柄
|
||
```c
|
||
typedef void *stru_task_timer_t;
|
||
typedef void *stru_task_event_t;
|
||
typedef void *stru_task_msg_queue_t;
|
||
```
|
||
|
||
## 接口函数
|
||
|
||
### 通用延时
|
||
|
||
#### task_sleep_ms(ms)
|
||
毫秒级精度延时（内部使用 nanosleep）。
|
||
|
||
### 定时器
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `task_timer_create(name, cb, arg, timeout_ms, flags)` | 创建定时器（不自动启动） |
|
||
| `task_timer_start(pt)` | 启动 |
|
||
| `task_timer_stop(pt)` | 停止 |
|
||
| `task_timer_restart(pt, timeout_ms)` | 重启（可改周期） |
|
||
| `task_timer_destroy(pt)` | 销毁 |
|
||
| `task_timer_is_active(pt)` | 查询运行状态 |
|
||
|
||
### 事件
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `task_event_create(name)` | 创建事件对象 |
|
||
| `task_event_destroy(pe)` | 销毁 |
|
||
| `task_event_send(pe, bits)` | 发送（置位+广播） |
|
||
| `task_event_recv(pe, set, opt, timeout_ms, recved)` | 等待 |
|
||
| `task_event_clear(pe, bits)` | 清除位 |
|
||
| `task_event_query(pe)` | 查询当前位（非阻塞） |
|
||
|
||
### 消息队列
|
||
|
||
| 函数 | 说明 |
|
||
|------|------|
|
||
| `task_msg_queue_create(name, msg_size, msg_num)` | 创建 |
|
||
| `task_msg_queue_destroy(pq)` | 销毁 |
|
||
| `task_msg_queue_send(pq, msg, size)` | 发送（阻塞） |
|
||
| `task_msg_queue_send_timeout(pq, msg, size, timeout_ms)` | 发送（超时） |
|
||
| `task_msg_queue_recv(pq, msg, size, timeout_ms)` | 接收（超时） |
|
||
| `task_msg_queue_try_recv(pq, msg, size)` | 非阻塞接收 |
|
||
| `task_msg_queue_get_count(pq)` | 获取消息数 |
|
||
| `task_msg_queue_space(pq)` | 获取剩余空间 |
|
||
|
||
## 使用示例
|
||
|
||
### 定时器
|
||
```c
|
||
#include "myTask.h"
|
||
#include <stdio.h>
|
||
|
||
static int tick_count = 0;
|
||
|
||
void on_tick(void *arg)
|
||
{
|
||
tick_count++;
|
||
printf("定时器触发: %d 次\n", tick_count);
|
||
}
|
||
|
||
int main(void)
|
||
{
|
||
// 创建周期定时器：每 100ms 触发一次
|
||
stru_task_timer_t pt = task_timer_create(
|
||
"heartbeat", on_tick, NULL, 100, TASK_TIMER_FLAG_PERIODIC
|
||
);
|
||
|
||
task_timer_start(pt);
|
||
task_sleep_ms(500); // 等待 500ms（预计触发 5 次）
|
||
task_timer_destroy(pt);
|
||
|
||
return 0;
|
||
}
|
||
```
|
||
|
||
### 事件
|
||
```c
|
||
stru_task_event_t pe = task_event_create("ev1");
|
||
|
||
// 线程 A: 发送事件
|
||
task_event_send(pe, 0x03); // 设置 bit0 和 bit1
|
||
|
||
// 线程 B: 等待事件（OR 模式 + 自动清除）
|
||
uint32_t recved = 0;
|
||
task_event_recv(pe, 0x03,
|
||
TASK_EVENT_FLAG_OR | TASK_EVENT_FLAG_CLEAR,
|
||
TASK_EVENT_WAIT_FOREVER, &recved);
|
||
printf("收到事件: 0x%02X\n", recved); // 0x03
|
||
|
||
task_event_destroy(pe);
|
||
```
|
||
|
||
### 消息队列
|
||
```c
|
||
// 创建队列：每条 64 字节，容量 10 条
|
||
stru_task_msg_queue_t pq = task_msg_queue_create("q1", 64, 10);
|
||
|
||
char tx[] = "Hello";
|
||
char rx[64];
|
||
|
||
task_msg_queue_send(pq, tx, 6); // 发送
|
||
task_msg_queue_recv(pq, rx, 64, 1000); // 接收（1 秒超时）
|
||
|
||
printf("收到: %s, 队列中: %u 条\n", rx, task_msg_queue_get_count(pq));
|
||
task_msg_queue_destroy(pq);
|
||
```
|
||
|
||
## 依赖关系
|
||
|
||
- **依赖**: liblog (错误日志)
|
||
- **系统依赖**: `<sys/timerfd.h>`, `<sys/epoll.h>`, `<sys/eventfd.h>`, `<pthread.h>`
|
||
- **被依赖**: 所有需要定时/同步/通讯的模块
|