diff --git a/util/include/util/tc_epoller.h b/util/include/util/tc_epoller.h index 8fda42a..143d03e 100755 --- a/util/include/util/tc_epoller.h +++ b/util/include/util/tc_epoller.h @@ -40,11 +40,13 @@ namespace tars /** * @file tc_epoller.h * @brief epoll操作封装类 + * @brief Epoll operation encapsulation class */ ///////////////////////////////////////////////// /** * @brief epoll异常类 +* @brief epoll exception class */ struct TC_Epoller_Exception : public TC_Exception { @@ -54,12 +56,14 @@ struct TC_Epoller_Exception : public TC_Exception /** * @brief epoller操作类，已经默认采用了EPOLLET方式做触发 + * @brief epoller operation class, EPOLLET has been used by default for triggering */ class TC_Epoller { public: /** * @brief 通知epoll从wait中醒过来 + * @brief Notice epoll to wake up from 'wait' */ class NotifyInfo { @@ -69,31 +73,37 @@ public: /** * 初始化 + * Initialization */ void init(TC_Epoller *ep); /** * 添加关联数据 + * Add corresponding data */ void add(uint64_t data); /** * 通知notify醒过来 + * Notice notify to wake up */ void notify(); /** * 释放掉 + * Diposit */ void release(); /** * 获取通知fd + * Get notifyFd */ int notifyFd(); /** * 清除通知, 否则会一直响应 + * Clear up notice, otherwise, it will always respond */ // void clear(); protected: @@ -103,26 +113,32 @@ public: // bool _clear = true; TC_Epoller *_ep; + /*Events associated with the notification handle*/ uint64_t _data; //关联到通知句柄的事件 }; /** * @brief 构造函数. + * @brief Constructor Function * * @param bEt 默认是ET模式，当状态发生变化的时候才获得通知 + * @param bEt The default is et mode, which is notified when the status changes */ TC_Epoller(); /** * @brief 析够函数. + * @brief Destructor */ ~TC_Epoller(); /** * @brief 生成epoll句柄. + * @brief Generate epoll handle. * * @param max_connections epoll服务需要支持的最大连接数 + * @param max_connections Maximum number of connections the epoll service needs to support */ void create(int max_connections); @@ -135,49 +151,66 @@ public: /** * @brief 添加监听句柄. + * @brief Add listening handle. * * @param fd 句柄 + * @param fd handle * @param data 辅助的数据, 可以后续在epoll_event中获取到 + * @param data auxiliary data that can be obtained in epoll_event subsequently * @param event 需要监听的事件EPOLLIN|EPOLLOUT + * @param event Events to be listened on EPOLLIN|EPOLLOUT * */ void add(SOCKET_TYPE fd, uint64_t data, int32_t event); /** * @brief 修改句柄事件. + * @brief Modify handle event * * @param fd 句柄 + * @param fd handle * @param data 辅助的数据, 可以后续在epoll_event中获取到 + * @param data auxiliary data that can be obtained in epoll_event subsequently * @param event 需要监听的事件EPOLLIN|EPOLLOUT + * @param event Events to be listened on EPOLLIN|EPOLLOUT */ void mod(SOCKET_TYPE fd, uint64_t data, int32_t event); /** * @brief 删除句柄事件. + * @brief Delete handle event. * * @param fd 句柄 + * @param fd handle * @param data 辅助的数据, 可以后续在epoll_event中获取到 + * @param data auxiliary data that can be obtained in epoll_event subsequently * @param event 需要监听的事件EPOLLIN|EPOLLOUT + * @param event Events to be listened on EPOLLIN|EPOLLOUT */ void del(SOCKET_TYPE fd, uint64_t data, int32_t event); /** * @brief 等待时间. + * @brief wait time * * @param millsecond 毫秒 * @return int 有事件触发的句柄数 + * @return int Number of handles triggered by events */ int wait(int millsecond); /** * @brief 获取被触发的事件. + * @brief Get the triggered handle * * @return struct epoll_event&被触发的事件 + * @return Struct epoll_event& triggered event */ epoll_event& get(int i);// { assert(_pevs != 0); return _pevs[i]; } /** * @brief 是否有读事件 + * @brief whether it have event to read * * @return */ @@ -185,6 +218,7 @@ public: /** * @brief 是否有写事件 + * @brief whether it have event to write * * @return */ @@ -192,6 +226,7 @@ public: /** * @brief 是否有异常事件 + * @brief whether it have eception event * * @return */ @@ -199,13 +234,16 @@ public: /** * @brief 获取低位/高位数据 + * @brief Get low/high bit data * @param high: true:高位, false:低位 + * @param high: true:high level, false:low level * @return */ static uint32_t getU32(const epoll_event &ev, bool high); /** * @brief 获取64bit数据 + * @brief Get 64 bit data * @return */ static uint64_t getU64(const epoll_event &ev); @@ -214,12 +252,19 @@ protected: /** * @brief 控制epoll，将EPOLL设为边缘触发EPOLLET模式 + * @brief Control epoll, set EPOLL to Edge Trigger EPOLLET mode * @param fd 句柄，在create函数时被赋值 + * @param fd Handle, assigned when creating function * @param data 辅助的数据, 可以后续在epoll_event中获取到 + * @param data auxiliary data that can be obtained in epoll_event subsequently * @param event 需要监听的事件 + * @param event the event to be listened * @param op EPOLL_CTL_ADD： 注册新的fd到epfd中； * EPOLL_CTL_MOD：修改已经注册的fd的监听事件； * EPOLL_CTL_DEL：从epfd中删除一个fd； + * @param op EPOLL_CTL_ADD：Register new FD into EPFD + * EPOLL_CTL_MOD：Modify the monitoring events for registered fd + * EPOLL_CTL_DEL：Delete an FD from epfd * */ void ctrl(SOCKET_TYPE fd, uint64_t data, uint32_t events, int op); @@ -237,11 +282,13 @@ protected: /** * 最大连接数 + * The max amount of connections */ int _max_connections; /** * 事件集 + * Event Set */ epoll_event *_pevs; }; diff --git a/util/include/util/tc_ex.h b/util/include/util/tc_ex.h index 089d8a5..6015697 100644 --- a/util/include/util/tc_ex.h +++ b/util/include/util/tc_ex.h @@ -28,40 +28,52 @@ namespace tars /** * @file tc_ex.h * @brief 异常类 +* @brief Exception Class */ ///////////////////////////////////////////////// /** * @brief 异常类. +* @brief Exception Class */ class TC_Exception : public exception { public: /** * @brief 构造函数，提供了一个可以传入errno的构造函数 + * @brief Constructor , provide a constructor which can pass errno * @param err, 是否附带系统错误信息(linux版本, 用errno获取错误码, windows版本, 用GetLastError()获取错误) + * @param err Whether system error information is included(linux: use errno to get error code, windows: use GetLastError() to get errors) * * @param buffer 异常的告警信息 + * @param buffer alert information of exceptions */ explicit TC_Exception(const string &buffer); /** - * @brief 构造函数,提供了一个可以传入errno的构造函数， + * @brief 构造函数,提供了一个可以传入errno的构造函数， + * @brief Constructor , provider a constructor to pass errno * * 异常抛出时直接获取的错误信息 + * get error message directly when throw exception * - * @param buffer 异常的告警信息 + * @param buffer 异常的告警信息 + * @param buffer alert information of exceptions + * * @param errno 传入:errno, windows版本 传入:GetLastError() + * @param errno pass:errno, windows version pass:GetLastError() */ TC_Exception(const string &buffer, int err); /** * @brief 析够数函 + * @brief Destructor */ virtual ~TC_Exception() throw(); /** * @brief 错误信息. + * @brief Error Message * * @return const char* */ @@ -69,22 +81,28 @@ public: /** * @brief 获取错误码 + * @brief Get error code * * @return 成功获取返回0 + * @return if get successfully , return 0 */ int getErrCode() { return _code; } /** * @brief 获取错误字符串(linux是errno, windows是GetLastError()) + * @brief Get the error string (linux: errno, windows: GetLastError()) * * @return 成功获取返回0 + * @return if get successfully , return 0 */ static string parseError(int err); /** * @brief 获取系统错误码(linux是errno, windows是GetLastError) + * @brief Get system error code(linux: errno, windows: GetLastError()) * * @return 成功获取返回0 + * @return if get successfully , return 0 */ static int getSystemCode(); @@ -95,18 +113,23 @@ private: /** * 错误码 + * Error Code */ int _code; /** * 异常的相关信息 + * Information about exceptions */ string _buffer; }; //为了避免windows平台GetLastError()获取不对的问题, 因为抛异常, throw TC_Exception("xxxx", TC_Exception::getSystemCode())时 +//In order to avoid getting the wrong getlasterror() on Windows platform, throw TC_ Exception("xxxx", TC_ Exception:: getsystemcode()) //回调用系统函数分配内存, 导致错误码被改写, 因此专门定义宏来抛出异常 +//Callback uses system function to allocate memory, which causes error code to be rewritten, so it specially defines macro to throw exception //先获取到错误码, 再throw +//Get the error code first, and then throw #define THROW_EXCEPTION_SYSCODE(EX_CLASS, buffer) \ { \ int ret = TC_Exception::getSystemCode(); \ diff --git a/util/include/util/tc_fifo.h b/util/include/util/tc_fifo.h index 0a35f4e..b6967ee 100644 --- a/util/include/util/tc_fifo.h +++ b/util/include/util/tc_fifo.h @@ -29,11 +29,13 @@ namespace tars /** *@file tc_fifo.h *@brief FIFO封装类. + *@brief FIFO encapsulation class */ ///////////////////////////////////////////////// /** *@brief 管道操作类. + *@brief Pipeline operation. */ class TC_Fifo { @@ -42,6 +44,8 @@ public: /** * @brief 管道操作的枚举类型. * 定义了对管道的操作类型，EM_WRITE：写管道，EM_READ ：读管道 + * @brief Enumeration types for pipeline operations + * Defines the type of operation on the pipeline, EM_ Write: write pipe, EM_ Read: read pipe */ enum ENUM_RW_SET { @@ -52,75 +56,99 @@ public: public: /** * @brief 构造函数. + * @brief Constructor * * @param bOwener : 是否拥有管道，默认为ture + * @param bOwener : Whether the pipeline is owned, the default is ture */ TC_Fifo(bool bOwener = true); /** * @brief 析构函数. + * @brief Constructor */ ~TC_Fifo(); public: /** * @brief 打开FIFO. + * @brief Open FIFO * * @param sPath 要打开的FIFO文件的路径 + * @param sPath the file path of the FIFO to open * @param enRW 管道操作类型 + * @param enRN Pipe opration type * @param mode 该FIFO文件的权限 ，默认为可读可写 + * @param mode The permissions of this FIFO file are read-write by default * @return 0-成功,-1-失败 + * @return 0 - successfull, -1 - failed */ int open(const std::string & sPath, ENUM_RW_SET enRW, mode_t mode = 0777); /** * @brief 关闭fifo + * @brief Close FIFO */ void close(); /** * @brief 获取FIFO的文件描述符. + * @brief Get the file descriptor of FIFO * * @return FIFO的文件描述符 + * @return the file descriptor of FIFO */ int fd() const { return _fd; } /** * @brief 读数据, 当读取成功时，返回实际读取的字节数，如果返回的值是0，代表已经读到文件的结束；小于0表示出现了错误 + * @brief read data, when read successfully, return the actual number of bytes read, if the value returned is 0, the end of the file has been read; less than 0 indicates an error * @param buffer 读取的内容 + * @param buffer the content to be read * @param max_size 读取数据的大小 + * @param max_size size of the data to be read * @return 读到的数据长度 ,小于0则表示失败 + * @return the length of the read data , if it is less then 0, read failed */ int read(char * szBuff, const size_t sizeMax); /** * @brief 向管道写数据. + * @brief Write data to the pipeline * * @param szBuff 要写入的数据 + * @param szBuff data to be wrote * @param sizeBuffLen 数据的大小 + * @param sizeBuffLen size of data * @return 大于0：表示写了部分或者全部数据 * 小于0：表示出现错误 + * @return geater than 0: Some or all of the data are shown and written + * less than 0: Error */ int write(const char * szBuff, const size_t sizeBuffLen); private: /** * FIFO文件的路径 + * file path of FIFO */ std::string _sPathName; /** * 是否拥有FIFO + * whether it have FIFO */ bool _bOwner; /** * FIFO的文件的操作类型 + * file opration type of FIFO */ ENUM_RW_SET _enRW; /** * FIFO的文件描述符 + * file descriptor of FIFO */ int _fd; }; diff --git a/util/include/util/tc_file_mutex.h b/util/include/util/tc_file_mutex.h index e45efed..e1b2320 100644 --- a/util/include/util/tc_file_mutex.h +++ b/util/include/util/tc_file_mutex.h @@ -46,6 +46,7 @@ struct TC_FileMutex_Exception : public TC_Lock_Exception /** * @brief 文件锁, 注意:只能在进程间加锁. + * @brief file lock , attion : You can only lock between processes */ class TC_FileMutex { @@ -53,45 +54,56 @@ public: /** * @brief 构造函数. + * @brief Constructor */ TC_FileMutex(); /** * @brief 析够函数. + * @brief Desturctor */ virtual ~TC_FileMutex(); /** * @brief 初始化文件锁. + * @brief Initialize file lock * * @param filename 欲操作的文件的名字 + * @param filename file name of the file to be operated */ void init(const std::string& filename); /** * @brief 加读锁. + * @brief Add read lock * *@return 0-成功加锁，-1-加锁失败 + *@return 0 - lock successfully, -1 - failed to lock */ int rlock(); /** * @brief 解读锁. + * @brief Unlock * * @return 0-成功解锁，-1-解锁失败 + * @return 0 - unlock successfully, -1 - failed to unlock */ int unrlock(); /** * @brief 尝试读锁. + * @brief Try read lock. * * @throws TC_FileMutex_Exception - * @return 加锁成功则返回false, 否则返回false + * @return 加锁成功则返回true, 否则返回false + * @return return true: lock successfully, return false: failed to lock */ bool tryrlock(); /** * @brief 加写锁. + * @brief Add write lock * * @return int */ @@ -99,60 +111,83 @@ public: /** * @brief 解写锁. + * @brief Unlock */ int unwlock(); /** * @brief 尝试写锁. + * @brief Try write lock. * - * @return bool，加锁成功则返回false, 否则返回false + * @return bool，加锁成功则返回true, 否则返回false + * @return return true: lock successfully, return false: failed to lock * @throws TC_FileMutex_Exception */ bool trywlock(); /** * @brief 写锁. + * @brief Read Lock. * * @return int, 0 正确 + * @return int, 0 - correct */ int lock(){return wlock();}; /** * @brief 解写锁. + * @brief Unlock */ int unlock(); /** * @brief 尝试解锁. + * @brief Try unlock * * @throws TC_FileMutex_Exception * @return int, 0 正确 + * @return int, 0 - correct */ bool trylock() {return trywlock();}; protected: /** * @brief 设置锁. + * @brief Set a lock. * * @param fd 欲设置的文件描述词 + * @param fd the file descriptor of the lock to be set * @param cmd 欲操作的指令 + * @param cmd opeational order * @param type 三种状态，分别为F_RDLCK ,F_WRLCK ,F_UNLCK + * @param type three states: F_RDLCK ,F_WRLCK ,F_UNLCK * @param offset 偏移量 + * @param offset the offset * @param whence 锁定的起始位置，三种方式 + * @param whence the starting position pf the lock,three ways * @param len 锁定区域的大小 + * @param len the size of the locked area * @return int：成功则返回0，若有错误则返回-1. + * @return int: successfully,return 0; else return -1 */ int lock(int fd, int cmd, int type, off_t offset, int whence, off_t len); /** * @brief 是否被其他进程锁了. + * @brief Whether it is locked by other threads * * @param fd 欲设置的文件描述词 + * @param fd the file desciptor to be set * @param type 三种状态，分别为F_RDLCK ,F_WRLCK ,F_UNLCK + * @param type three types: F_RDLCK ,F_WRLCK ,F_UNLCK * @param offset 偏移量 + * @param offset the offset * @param whence 锁定的起始位置，三种方式 + * @param whence the starting position of the lock ,three ways * @param len 锁定区域的大小 - * @return bool 有所返回true，无锁返回false. + * @param len the size of the locked area + * @return bool 有所返回true，无锁返回false. + * @return int: successfully,return 0; else return -1 */ bool hasLock(int fd, int type, off_t offset, int whence, off_t len);