237 lines
7.1 KiB
C
237 lines
7.1 KiB
C
/**
|
||
* @file myTask.h
|
||
* @brief 任务框架接口 — 定时器 + 事件 + 消息队列（C 接口）
|
||
* @details 基于 SPEC §8 原工程分析。
|
||
* 定时器基于 timerfd + epoll 实现，精确到毫秒。
|
||
* 事件基于位图 + pthread 条件变量实现。
|
||
* 消息队列基于环形缓冲区 + 互斥锁 + 条件变量实现。
|
||
*/
|
||
|
||
#ifndef _MY_TASK_H_
|
||
#define _MY_TASK_H_
|
||
|
||
#include <stdint.h>
|
||
|
||
#ifdef __cplusplus
|
||
extern "C"
|
||
{
|
||
#endif
|
||
|
||
/* ================================================================
|
||
* 通用定义
|
||
* ================================================================ */
|
||
|
||
/** 定时器回调函数类型 */
|
||
typedef void (*timer_func_cb)(void *arg);
|
||
|
||
/** 不透明句柄类型 */
|
||
typedef void *stru_task_timer_t;
|
||
typedef void *stru_task_event_t;
|
||
typedef void *stru_task_msg_queue_t;
|
||
|
||
/* ================================================================
|
||
* 定时器标志
|
||
* ================================================================ */
|
||
|
||
/** 单次触发（到期后自动停止） */
|
||
#define TASK_TIMER_FLAG_ONCE 0x01
|
||
|
||
/** 周期触发（到期后自动重新计时） */
|
||
#define TASK_TIMER_FLAG_PERIODIC 0x02
|
||
|
||
/* ================================================================
|
||
* 事件等待方式
|
||
* ================================================================ */
|
||
|
||
/** 永久等待（不超时） */
|
||
#define TASK_EVENT_WAIT_FOREVER 0xFFFFFFFF
|
||
|
||
/** 事件标记：等待所有位都置位（AND 模式） */
|
||
#define TASK_EVENT_FLAG_AND 0x01
|
||
|
||
/** 事件标记：等待任意位置位（OR 模式） */
|
||
#define TASK_EVENT_FLAG_OR 0x02
|
||
|
||
/** 事件标记：接收后自动清除已匹配的位 */
|
||
#define TASK_EVENT_FLAG_CLEAR 0x04
|
||
|
||
/* ================================================================
|
||
* 通用延时
|
||
* ================================================================ */
|
||
|
||
/**
|
||
* @brief 任务延时（毫秒级阻塞等待）
|
||
* @param ms 延时毫秒数
|
||
*/
|
||
void task_sleep_ms(uint32_t ms);
|
||
|
||
/* ================================================================
|
||
* 事件 API
|
||
* ================================================================ */
|
||
|
||
/**
|
||
* @brief 创建事件对象
|
||
* @param name 事件名称（调试用）
|
||
* @return 事件句柄，失败返回 NULL
|
||
*/
|
||
stru_task_event_t task_event_create(const char *name);
|
||
|
||
/**
|
||
* @brief 销毁事件对象
|
||
* @param p_event 事件句柄
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_event_destroy(stru_task_event_t p_event);
|
||
|
||
/**
|
||
* @brief 发送事件（设置事件位）
|
||
* @param p_event 事件句柄
|
||
* @param event 要设置的事件位掩码
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_event_send(stru_task_event_t p_event, uint32_t event);
|
||
|
||
/**
|
||
* @brief 等待事件
|
||
* @param p_event 事件句柄
|
||
* @param set 期望的事件位掩码
|
||
* @param opt 等待选项（TASK_EVENT_FLAG_AND/OR/CLEAR 组合）
|
||
* @param timeout_ms 超时时间（毫秒，TASK_EVENT_WAIT_FOREVER=永久等待）
|
||
* @param recved 输出参数：实际收到的事件位
|
||
* @return 0 成功，-1 超时或失败
|
||
*/
|
||
int task_event_recv(stru_task_event_t p_event, uint32_t set, uint32_t opt,
|
||
uint32_t timeout_ms, uint32_t *recved);
|
||
|
||
/**
|
||
* @brief 清除事件位
|
||
* @param p_event 事件句柄
|
||
* @param event 要清除的事件位掩码
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_event_clear(stru_task_event_t p_event, uint32_t event);
|
||
|
||
/**
|
||
* @brief 查询当前事件位（非阻塞）
|
||
* @param p_event 事件句柄
|
||
* @return 当前事件位掩码
|
||
*/
|
||
uint32_t task_event_query(stru_task_event_t p_event);
|
||
|
||
/* ================================================================
|
||
* 消息队列 API
|
||
* ================================================================ */
|
||
|
||
/**
|
||
* @brief 创建定长消息队列
|
||
* @param name 队列名称（调试用）
|
||
* @param msg_size 每条消息的最大字节数
|
||
* @param msg_num 队列容量（最大消息条数）
|
||
* @return 队列句柄，失败返回 NULL
|
||
*/
|
||
stru_task_msg_queue_t task_msg_queue_create(const char *name,
|
||
uint32_t msg_size, uint32_t msg_num);
|
||
|
||
/**
|
||
* @brief 销毁消息队列
|
||
* @param p_queue 队列句柄
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_msg_queue_destroy(stru_task_msg_queue_t p_queue);
|
||
|
||
/**
|
||
* @brief 发送消息（队列满时阻塞等待）
|
||
* @param p_queue 队列句柄
|
||
* @param msg 消息内容指针
|
||
* @param size 消息实际字节数（<= msg_size）
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_msg_queue_send(stru_task_msg_queue_t p_queue, const void *msg,
|
||
uint32_t size);
|
||
|
||
/**
|
||
* @brief 发送消息（带超时）
|
||
* @param timeout_ms 超时时间（毫秒，TASK_EVENT_WAIT_FOREVER=永久等待）
|
||
* @return 0 成功，-1 超时或失败
|
||
*/
|
||
int task_msg_queue_send_timeout(stru_task_msg_queue_t p_queue, const void *msg,
|
||
uint32_t size, uint32_t timeout_ms);
|
||
|
||
/**
|
||
* @brief 接收消息（带超时）
|
||
* @param timeout_ms 超时时间（毫秒，TASK_EVENT_WAIT_FOREVER=永久等待）
|
||
* @return 0 成功，-1 超时或失败
|
||
*/
|
||
int task_msg_queue_recv(stru_task_msg_queue_t p_queue, void *msg,
|
||
uint32_t size, uint32_t timeout_ms);
|
||
|
||
/**
|
||
* @brief 尝试接收消息（非阻塞，队列空立即返回 -1）
|
||
* @return 0 成功，-1 队列空
|
||
*/
|
||
int task_msg_queue_try_recv(stru_task_msg_queue_t p_queue, void *msg,
|
||
uint32_t size);
|
||
|
||
/**
|
||
* @brief 获取队列中当前消息数
|
||
*/
|
||
uint32_t task_msg_queue_get_count(stru_task_msg_queue_t p_queue);
|
||
|
||
/**
|
||
* @brief 获取队列剩余可用空间（条数）
|
||
*/
|
||
uint32_t task_msg_queue_space(stru_task_msg_queue_t p_queue);
|
||
|
||
/* ================================================================
|
||
* 定时器 API
|
||
* ================================================================ */
|
||
|
||
/**
|
||
* @brief 创建定时器（创建后不会自动启动，需调用 task_timer_start）
|
||
* @param name 定时器名称（调试用）
|
||
* @param fun_cb 到期回调函数
|
||
* @param arg 回调参数
|
||
* @param timeout_ms 定时周期（毫秒）
|
||
* @param flags 标志位（TASK_TIMER_FLAG_ONCE 或 TASK_TIMER_FLAG_PERIODIC）
|
||
* @return 定时器句柄，失败返回 NULL
|
||
*/
|
||
stru_task_timer_t task_timer_create(const char *name, timer_func_cb fun_cb,
|
||
void *arg, uint32_t timeout_ms, int flags);
|
||
|
||
/**
|
||
* @brief 启动定时器
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_timer_start(stru_task_timer_t p_timer);
|
||
|
||
/**
|
||
* @brief 停止定时器
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_timer_stop(stru_task_timer_t p_timer);
|
||
|
||
/**
|
||
* @brief 重启定时器（可修改周期）
|
||
* @param timeout_ms 新的定时周期（毫秒）
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_timer_restart(stru_task_timer_t p_timer, uint32_t timeout_ms);
|
||
|
||
/**
|
||
* @brief 销毁定时器
|
||
* @return 0 成功，-1 失败
|
||
*/
|
||
int task_timer_destroy(stru_task_timer_t p_timer);
|
||
|
||
/**
|
||
* @brief 查询定时器是否在运行
|
||
* @return 1=运行中，0=已停止
|
||
*/
|
||
int task_timer_is_active(stru_task_timer_t p_timer);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
|
||
#endif /* _MY_TASK_H_ */
|