/**
 * @file hal_thread.h
 * @brief 线程/任务 HAL 接口（支持消息队列模式）
 */

#ifndef HAL_THREAD_H
#define HAL_THREAD_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

/** 线程句柄 */
typedef void *hal_thread_t;

#define HAL_THREAD_MSG_PARAM_MAX  4  /* 消息最大参数个数 */

/** 线程入口函数（简单模式）*/
typedef void (*hal_thread_entry_t)(void *arg);

/** 消息处理函数（消息队列模式）*/
typedef void (*hal_thread_msg_handler_t)(int msg_id, int *params, int param_count, void *user_ctx);

/** 线程配置（entry 和 msg_handler 二选一）*/
typedef struct {
    const char               *name;         /* 线程名 */
    hal_thread_entry_t        entry;        /* 简单模式入口（消息模式填 NULL）*/
    hal_thread_msg_handler_t  msg_handler;  /* 消息处理函数（简单模式填 NULL）*/
    void                     *arg;          /* entry 参数 */
    void                     *user_ctx;     /* msg_handler 上下文 */
    uint32_t                  stack_size;   /* 栈大小（字节）*/
    uint8_t                   priority;     /* 优先级 */
    uint16_t                  queue_size;   /* 消息队列深度（简单模式填 0）*/
} hal_thread_config_t;

/**
 * @brief 创建并启动线程
 * @return 句柄，失败返回 NULL
 */
hal_thread_t hal_thread_create(const hal_thread_config_t *config);

/**
 * @brief 向线程消息队列投递消息
 * @param msg_id 消息 ID
 * @param argc   参数个数（0 ~ HAL_THREAD_MSG_PARAM_MAX）
 * @return 0 成功，负值失败
 */
int hal_thread_post_msg(hal_thread_t thread, int msg_id, int argc, ...);

/** @brief 销毁线程（等待退出后释放资源）*/
void hal_thread_destroy(hal_thread_t thread);

/** @brief 当前线程休眠指定毫秒 */
void hal_thread_sleep_ms(uint32_t ms);

#ifdef __cplusplus
}
#endif

#endif /* HAL_THREAD_H */
