Merge pull request #86 from Douwanna/release/2.4

Update notes.

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;
 };

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 Constructor , provider a constructor to pass errno 
 	 *  
 	 *  	  异常抛出时直接获取的错误信息
+     *        get error message directly when throw exception
 	 *  
      * @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(); \

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;
 };

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     锁定区域的大小
+     * @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);