add comments

base/heap.h

@@ -1,6 +1,11 @@
 #ifndef HV_HEAP_H_
 #define HV_HEAP_H_
 
+/*
+ * @功能：此头文件实现了大小堆
+ *
+ */
+
 #include <assert.h> // for assert
 #include <stddef.h> // for NULL
 

base/hendian.h

@@ -1,6 +1,11 @@
 #ifndef HV_ENDIAN_H_
 #define HV_ENDIAN_H_
 
+/*
+ * @功能：此头文件封装了跨平台的大小端工具函数
+ *
+ */
+
 #include "hplatform.h"
 #if defined(OS_MAC)
 #include <libkern/OSByteOrder.h>

base/herr.h

@@ -1,6 +1,11 @@
 #ifndef HV_ERR_H_
 #define HV_ERR_H_
 
+/*
+ * @功能：此头文件定义了一些错误码
+ *
+ */
+
 #include <errno.h>
 
 #include "hexport.h"

base/hlog.h

@@ -1,6 +1,11 @@
 #ifndef HV_LOG_H_
 #define HV_LOG_H_
 
+/*
+ * @功能：写日志
+ *
+ */
+
 /*
  * hlog is thread-safe
  */
@@ -15,6 +20,7 @@
 #define DIR_SEPARATOR_STR   "/"
 #endif
 
+// __FILE__是完整路径宏，对于日志来说太长，这里我们提取出文件名__FILENAME__
 #ifndef __FILENAME__
 // #define __FILENAME__  (strrchr(__FILE__, DIR_SEPARATOR) ? strrchr(__FILE__, DIR_SEPARATOR) + 1 : __FILE__)
 #define __FILENAME__  (strrchr(DIR_SEPARATOR_STR __FILE__, DIR_SEPARATOR) + 1)
@@ -26,6 +32,7 @@
 extern "C" {
 #endif
 
+// 定义一些终端颜色宏，方便区分日志级别
 #define CLR_CLR         "\033[0m"       /* 恢复颜色 */
 #define CLR_BLACK       "\033[30m"      /* 黑色字 */
 #define CLR_RED         "\033[31m"      /* 红色字 */
@@ -53,6 +60,7 @@ extern "C" {
     XXX(LOG_LEVEL_ERROR, "ERROR", CLR_RED)       \
     XXX(LOG_LEVEL_FATAL, "FATAL", CLR_RED_WHT)
 
+// 定义日志级别
 typedef enum {
     LOG_LEVEL_VERBOSE = 0,
 #define XXX(id, str, clr) id,
@@ -71,37 +79,58 @@ typedef enum {
 // network_logger() see event/nlog.h
 typedef void (*logger_handler)(int loglevel, const char* buf, int len);
 
+// 实现了几种常见的日志处理器，标准输出、标准错误、写文件
 HV_EXPORT void stdout_logger(int loglevel, const char* buf, int len);
 HV_EXPORT void stderr_logger(int loglevel, const char* buf, int len);
 HV_EXPORT void file_logger(int loglevel, const char* buf, int len);
+// 在event模块中我们还实现了一个网络日志服务，
+// 连上的客户端就会收到日志，是不是有点像android的logcat呢
 // network_logger implement see event/nlog.h
 // HV_EXPORT void network_logger(int loglevel, const char* buf, int len);
 
 typedef struct logger_s logger_t;
+// 创建日志器
 HV_EXPORT logger_t* logger_create();
+// 销毁日志器
 HV_EXPORT void logger_destroy(logger_t* logger);
 
+// 设置日志处理器
 HV_EXPORT void logger_set_handler(logger_t* logger, logger_handler fn);
+// 设置日志级别
 HV_EXPORT void logger_set_level(logger_t* logger, int level);
 // level = [VERBOSE,DEBUG,INFO,WARN,ERROR,FATAL,SILENT]
 HV_EXPORT void logger_set_level_by_str(logger_t* logger, const char* level);
+// 设置一条日志最大的长度
 HV_EXPORT void logger_set_max_bufsize(logger_t* logger, unsigned int bufsize);
+// 启用日志颜色打印
 HV_EXPORT void logger_enable_color(logger_t* logger, int on);
+// 打印日志
 HV_EXPORT int  logger_print(logger_t* logger, int level, const char* fmt, ...);
 
+// 下面是文件日志器的一些设置
 // below for file logger
+// 设置日志文件
 HV_EXPORT void logger_set_file(logger_t* logger, const char* filepath);
+// 设置日志文件最大尺寸
 HV_EXPORT void logger_set_max_filesize(logger_t* logger, unsigned long long filesize);
 // 16, 16M, 16MB
 HV_EXPORT void logger_set_max_filesize_by_str(logger_t* logger, const char* filesize);
+// 设置日志保留天数
 HV_EXPORT void logger_set_remain_days(logger_t* logger, int days);
+// 启用fsync
+// @NOTE: fsync用来强制刷新缓存到磁盘，日志的实时可见性更好，但会影响性能，
+// 在日志很多的场合，建议关闭此选项，可使用定时器定时调用logger_fsync去刷新到磁盘。
 HV_EXPORT void logger_enable_fsync(logger_t* logger, int on);
+// 强制调用fsync刷新缓存到磁盘
 HV_EXPORT void logger_fsync(logger_t* logger);
+// 获取当前的日志文件路径
 HV_EXPORT const char* logger_get_cur_file(logger_t* logger);
 
+// 提供一个默认的日志器
 // hlog: default logger instance
 HV_EXPORT logger_t* hv_default_logger();
 
+// hlog_xxx即使用默认的日志器
 // macro hlog*
 #define hlog                            hv_default_logger()
 #define hlog_set_file(filepath)         logger_set_file(hlog, filepath)
@@ -121,6 +150,7 @@ HV_EXPORT logger_t* hv_default_logger();
 #define hloge(fmt, ...) logger_print(hlog, LOG_LEVEL_ERROR, fmt " [%s:%d:%s]\n", ## __VA_ARGS__, __FILENAME__, __LINE__, __FUNCTION__)
 #define hlogf(fmt, ...) logger_print(hlog, LOG_LEVEL_FATAL, fmt " [%s:%d:%s]\n", ## __VA_ARGS__, __FILENAME__, __LINE__, __FUNCTION__)
 
+// 在android平台，使用__android_log_print
 // below for android
 #if defined(ANDROID) || defined(__ANDROID__)
 #include <android/log.h>
@@ -137,6 +167,7 @@ HV_EXPORT logger_t* hv_default_logger();
 #define hlogf(...) __android_log_print(ANDROID_LOG_FATAL, LOG_TAG, __VA_ARGS__)
 #endif
 
+// 更通用的日志宏
 // macro alias
 #if !defined(LOGD) && !defined(LOGI) && !defined(LOGW) && !defined(LOGE) && !defined(LOGF)
 #define LOGD    hlogd

base/hmath.h

@@ -1,8 +1,14 @@
 #ifndef HV_MATH_H_
 #define HV_MATH_H_
 
+/*
+ * @功能：此头文件补充了一些数学工具函数
+ *
+ */
+
 #include <math.h>
 
+// 向下取2的指数倍, floor2e(3) = 2
 static inline unsigned long floor2e(unsigned long num) {
     unsigned long n = num;
     int e = 0;
@@ -12,6 +18,7 @@ static inline unsigned long floor2e(unsigned long num) {
     return ret;
 }
 
+// 向上取2的指数倍, floor2e(3) = 4
 static inline unsigned long ceil2e(unsigned long num) {
     // 2**0 = 1
     if (num == 0 || num == 1)   return 1;

base/hmutex.h

@@ -1,6 +1,18 @@
 #ifndef HV_MUTEX_H_
 #define HV_MUTEX_H_
 
+/*
+ * @功能：此头文件封装了跨平台的线程同步手段，包括
+ *        互斥量 hmutex_t
+ *        可重入的互斥量 hrecursive_mutex_t
+ *        自旋锁 hspinlock_t
+ *        读写锁 hrwlock_t
+ *        定时锁 htimed_mutex_t
+ *        条件变量 hcondvar_t
+ *        信号量 hsem_t
+ *
+ */
+
 #include "hexport.h"
 #include "hplatform.h"
 #include "htime.h"

base/hproc.h

@@ -1,6 +1,12 @@
 #ifndef HV_PROC_H_
 #define HV_PROC_H_
 
+/*
+ * @功能：衍生进程
+ * @备注：unix使用的多进程、windows下使用的多线程
+ *
+ */
+
 #include "hplatform.h"
 
 typedef struct proc_ctx_s {

base/hsocket.h

@@ -1,6 +1,11 @@
 #ifndef HV_SOCKET_H_
 #define HV_SOCKET_H_
 
+/*
+ * @功能：此头文件封装了跨平台的套接字操作
+ *
+ */
+
 #include "hexport.h"
 #include "hplatform.h"
 
@@ -26,6 +31,7 @@ static inline int socket_errno() {
 }
 HV_EXPORT const char* socket_strerror(int err);
 
+// 屏蔽一些windows和unix下套接字的差异
 #ifdef OS_WIN
 typedef int socklen_t;
 static inline int blocking(int sockfd) {
@@ -52,6 +58,7 @@ typedef int         SOCKET;
 #endif
 
 //-----------------------------sockaddr_u----------------------------------------------
+// 定义了一个包含了IPv4、IPv6、Unix Domain Socket的联合类型
 typedef union {
     struct sockaddr     sa;
     struct sockaddr_in  sin;
@@ -61,10 +68,12 @@ typedef union {
 #endif
 } sockaddr_u;
 
+// 域名解析
 // @param host: domain or ip
 // @retval 0:succeed
 HV_EXPORT int Resolver(const char* host, sockaddr_u* addr);
 
+// 提供了一系列操作sockaddr_u的工具函数
 HV_EXPORT const char* sockaddr_ip(sockaddr_u* addr, char *ip, int len);
 HV_EXPORT uint16_t sockaddr_port(sockaddr_u* addr);
 HV_EXPORT int sockaddr_set_ip(sockaddr_u* addr, const char* host);

base/hssl.h

@@ -1,6 +1,11 @@
 #ifndef HV_SSL_H_
 #define HV_SSL_H_
 
+/*
+ * @功能：提供了统一的SSL/TLS封装接口
+ *
+ */
+
 #include "hexport.h"
 
 typedef void* hssl_ctx_t; ///> SSL_CTX