/**
 * @file timer.h
 * @brief 
 * @author dfs 
 * @version 1.0
 * @date 2023-12-06
 * 
 * @copyright Copyright (c) 2023  杭州科技股份有限公司
 * 
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-06 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
#ifndef __TIMER_H__
#define __TIMER_H__

#include "define_base.h"

typedef struct bs_timer_s* bs_timer_t;

typedef void (*bs_timer_cb)(void *arg);


/*
    场景1:申请一个定时器，每个定时器回调为单独线程，时间到了给个回调处理，对触发的精度与响应的要求较高
    */
/**
 * @brief   单实例的定时器
 *          每个定时器新开启一个新的线程；
 *          当定时处理任务中有阻塞操作时；或者定时器处理任务需要临时添加与删除的情况下使用； 
 *          ！！！！定时器不再使用时，请使用close操作!!!!!!!!
 * 
 * @param timeout_cb      回调函数
 * @param timeout         超时时间 
 * @param repeat          是否重复操作
 * @param arg             参数
 * @return        返回的单实例定时器; NULL: 失败；
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
bs_timer_t timer_single_init(bs_timer_cb timeout_cb, uint32_t timeout, uint32_t repeat, void *arg);

/**
 * @brief 暂停定时器，可以根据期望后面可以任然开启
 * 
 * @param timer_single 
 * @return int     <0 失败 0:正常
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_single_stop(bs_timer_t timer_single);


/**
 * @brief 启动定时器
 * 
 * @param timer_single 
 * @return int     <0 失败 0:正常
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_single_start(bs_timer_t timer_single);

/**
 * @brief 删除定时器
 * 
 * @param timer_single 
 * @return int     <0 失败 0:正常
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_single_close(bs_timer_t timer_single);


typedef struct timer_list_s* timer_list_t;
/**
 * @brief  申请一个定时器，可以对该定时器扩展硬件定时功能，CPU消耗较小,一个timer_list回调在一个线程中
           使用timer fd 实现，消耗了较多系统资源 
           !!!!!使用完成后必须timer_list_close回收资源!!!!
 * 
 * 
 * 
 * @param sw_tmr_num       包含的软件定时器个数
 * @return timer_list_t   软件定时器的列表指针
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
timer_list_t timer_list_create(int sw_tmr_num);

/**
 * @brief  向定时器列表中添加一个定时器任务
 * 
 * @param tmr         定时器列表
 * @param timeout_cb  回调函数
 * @param timeout     超时时间
 * @param repeat      是否重复
 * @param arg         用户参数
 * @return int        > 0 返回当前软件定时器的id;
 *                    其它错误
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_list_add_one(timer_list_t tmr, bs_timer_cb timeout_cb, uint32_t timeout, uint32_t repeat, void *arg);

/**
 * @brief           暂停一个软件定时器
 * 
 * @param tmr       定时器列表
 * @param id        定时器ID
 * @return int      0:成功
 *                  非0:失败
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_list_stop_one(timer_list_t tmr, int id);

/**
 * @brief           启动一个定时器
 * 
 * @param tmr       定时器列表
 * @param id        定时器ID
 * @return int      0:成功
 *                  非0:失败  
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_list_start_one(timer_list_t tmr, int id);

/**
 * @brief           删除一个定时器
 * 
 * @param tmr       定时器列表
 * @param id        定时器ID
 * @return int 
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_list_remove_one(timer_list_t tmr, int id);

/**
 * @brief           !!!!!!关闭一个定时器列表!!!!!!!
 *                  使用定时器的进程退出前必须要调用，否则会导致定时器fd会不断创建
 * 
 * @param tmr 
 * @return int      0:成功
 *                  非0:失败  
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2023-12-11 <td>1.0     <td>dfs     <td>内容
 * </table>
 */
int timer_list_close(timer_list_t tmr);




#endif //__TIMER_H__