/**
 * @file rt_api_def.h
 * @brief SMCC运行时库接口定义
 * 
 * 定义运行时基础API函数指针类型及运行时接口结构体
 */

#ifndef __SMCC_RT_API_DEF_H__
#define __SMCC_RT_API_DEF_H__

#include "rt_type.h"

#ifndef __RT_SIZE_TYPE__
#define __RT_SIZE_TYPE__
/**
 * @typedef rt_size_t
 * @brief 表示内存大小的类型定义
 */
typedef usz_t rt_size_t;
#endif

/**
 * @typedef rt_malloc
 * @brief 内存分配函数指针类型
 * @param size 需要分配的内存大小
 * @return 分配的内存指针，失败返回NULL
 */
typedef void*   (*rt_malloc)(rt_size_t size);

/**
 * @typedef rt_free
 * @brief 内存释放函数指针类型
 * @param ptr 需要释放的内存指针
 */
typedef void    (*rt_free)(void* ptr);

/**
 * @typedef rt_exit
 * @brief 程序退出函数指针类型
 * @param code 退出状态码
 */
typedef void    (*rt_exit)(int code);

/** @defgroup file_io 文件I/O相关类型 */

#ifndef __RT_FILE_TYPE__
#define __RT_FILE_TYPE__
/**
 * @typedef rt_file_t
 * @brief 文件句柄类型定义
 */
typedef void* rt_file_t;
#endif

/** @brief 标准输入文件句柄 */
extern rt_file_t rt_stdin;
/** @brief 标准输出文件句柄 */
extern rt_file_t rt_stdout;
/** @brief 标准错误文件句柄 */
extern rt_file_t rt_stderr;

/**
 * @typedef rt_fopen_t
 * @brief 文件打开函数指针类型
 * @param file_name 文件名
 * @param mode 打开模式（同fopen）
 * @return 文件句柄，失败返回NULL
 */
typedef rt_file_t   (*rt_fopen_t)(const char* file_name, const char* mode);

/**
 * @typedef rt_fflush_t
 * @brief 文件缓冲刷新函数指针类型
 * @param file 文件句柄指针
 * @return 成功返回0，失败返回非0值
 */
typedef int     (*rt_fflush_t)(rt_file_t* file);

/**
 * @typedef rt_fclose_t
 * @brief 文件关闭函数指针类型
 * @param file 文件句柄
 * @return 成功返回0，失败返回EOF
 */
typedef int     (*rt_fclose_t)(rt_file_t file);

/**
 * @typedef rt_fread_t
 * @brief 文件读取函数指针类型
 * @param dst_buf 目标缓冲区
 * @param elem_size 单个元素大小
 * @param count 元素数量
 * @param file 文件句柄
 * @return 实际读取的元素数量
 */
typedef int     (*rt_fread_t)(void * dst_buf, rt_size_t elem_size, rt_size_t count, rt_file_t file);

/**
 * @typedef rt_fwrite_t
 * @brief 文件写入函数指针类型
 * @param buf 源缓冲区
 * @param size 单个元素大小
 * @param count 元素数量
 * @param file 文件句柄
 * @return 实际写入的元素数量
 */
typedef int     (*rt_fwrite_t)(const void * buf, rt_size_t size, rt_size_t count, rt_file_t file);

/** @defgroup utility 实用工具函数 */

/**
 * @typedef rt_fprintf_t
 * @brief 格式化输出函数指针类型
 * @param file 文件句柄
 * @param format 格式化字符串
 * @param ... 可变参数
 * @return 输出的字符数
 */
typedef int     (*rt_fprintf_t)(void * file, const char *format, ...);

/**
 * @typedef rt_snprintf_t
 * @brief 安全格式化字符串函数指针类型
 * @param stream 目标缓冲区
 * @param n 缓冲区大小
 * @param format 格式化字符串
 * @param ... 可变参数
 * @return 写入的字符数（不含终止符）
 */
typedef int     (*rt_snprintf_t)(char * stream, rt_size_t n, const char * format, ...);

/**
 * @typedef rt_realloc_t
 * @brief 内存重分配函数指针类型
 * @param memory 原内存指针
 * @param new_size 新内存大小
 * @return 新内存指针，失败返回NULL
 */
typedef void*   (*rt_realloc_t)(void *memory, rt_size_t new_size);

/**
 * @struct smcc_rt_t
 * @brief 运行时接口集合
 * 
 * 包含内存管理、文件操作等核心运行时函数的指针集合
 */
typedef struct smcc_rt {
    /** @brief 内存分配函数指针 */
    rt_malloc   _malloc;
    /** @brief 内存释放函数指针 */
    rt_free     _free;
    /** @brief 程序退出函数指针 */
    rt_exit     exit;
    
    /** @brief 文件打开函数指针 */
    rt_fopen_t    fopen;
    /** @brief 文件缓冲刷新函数指针 */
    rt_fflush_t   fflush;
    /** @brief 文件关闭函数指针 */
    rt_fclose_t   fclose;
    /** @brief 文件读取函数指针 */
    rt_fread_t    fread;
    /** @brief 文件写入函数指针 */
    rt_fwrite_t   fwrite;
    
    /** @name 可选工具函数 */
    ///@{
    /** @brief 格式化输出函数指针（可选） */
    rt_fprintf_t  fprintf;
    /** @brief 安全格式化字符串函数指针（可选） */
    rt_snprintf_t snprintf;
    /** @brief 内存重分配函数指针（可选） */
    rt_realloc_t  _realloc;
    ///@}
} smcc_rt_t;

/** @brief 全局运行时接口实例 */
extern const smcc_rt_t rt;

/** @brief 空指针定义 */
#define NULL ((void *)0)

#endif // __SMCC_RT_API_DEF_H__