diff --git a/util/include/util/tc_autoptr.h b/util/include/util/tc_autoptr.h index e1a46e8..42545cc 100755 --- a/util/include/util/tc_autoptr.h +++ b/util/include/util/tc_autoptr.h @@ -26,6 +26,7 @@ namespace tars { /** +* @brief Null Pointer Exception * @brief 空指针异常 */ struct TC_AutoPtrNull_Exception : public TC_Exception @@ -35,9 +36,11 @@ struct TC_AutoPtrNull_Exception : public TC_Exception }; /** - * @brief 智能指针基类. - * - * 所有需要智能指针支持的类都需要从该对象继承， + * @brief Smart Pointer Base Class + * @brief 智能指针基类 + * + * All classes that require smart pointer support need to inherit from this object. + * 所有需要智能指针支持的类都需要从该对象继承， * */ class UTIL_DLL_API TC_HandleBase @@ -45,7 +48,8 @@ class UTIL_DLL_API TC_HandleBase public: /** - * @brief 复制. + * @brief Copy + * @brief 复制 * * @return TC_HandleBase& */ @@ -55,12 +59,17 @@ public: } /** + * @brief Increase Count * @brief 增加计数 */ void incRef() { ++_atomic; } /** - * @brief 减少计数, 当计数==0时, 且需要删除数据时, 释放对象 + * @brief Decrease Count/减少计数 + * + * 当计数==0时, 且需要删除数据时, 释放对象 + * When 'count==0' and you need to delete data, you can use this to release object. + * */ void decRef() { @@ -72,15 +81,19 @@ public: } /** + * @brief Get Count * @brief 获取计数. * + * @return int value of count * @return int 计数值 */ int getRef() const { return _atomic; } /** - * @brief 设置不自动释放. + * @brief Set Automatically-Release Off + * @brief 设置不自动释放. * + * @param b Determine whether to be deleted automatically or not, true or false. * @param b 是否自动删除,true or false */ void setNoDelete(bool b) { _bNoDelete = b; } @@ -88,13 +101,15 @@ public: protected: /** - * @brief 构造函数 + * @brief Constructor + * @brief 构造函数 */ TC_HandleBase() : _atomic(0), _bNoDelete(false) { } /** + * @brief Copy Constructor * @brief 拷贝构造 */ TC_HandleBase(const TC_HandleBase&) : _atomic(0), _bNoDelete(false) @@ -102,7 +117,8 @@ protected: } /** - * @brief 析够 + * @brief Destructor + * @brief 析构 */ virtual ~TC_HandleBase() { @@ -111,25 +127,32 @@ protected: protected: /** + * Count * 计数 */ std::atomic _atomic; /** + * Determine whether to be deleted automatically or not * 是否自动删除 */ bool _bNoDelete; }; /** + * @brief Smart Pointer Template Class * @brief 智能指针模板类. * + * This template class an product thread-safe smart pointer which can be placed in a container. + * The smart pointer which is defined by this class can be implemented by reference counting. + * The pointer can be passed in a container. + * + * template T MUST BE inherited from TC_HandleBase + * * 可以放在容器中,且线程安全的智能指针. - * * 通过它定义智能指针，该智能指针通过引用计数实现， - * - * 可以放在容器中传递. - * + * 可以放在容器中传递. + * * template T必须继承于TC_HandleBase */ template @@ -138,11 +161,13 @@ class TC_AutoPtr public: /** + * Element Type * 元素类型 */ typedef T element_type; /** + * @brief Initialize with native pointer, count +1 * @brief 用原生指针初始化, 计数+1. * * @param p @@ -158,6 +183,7 @@ public: } /** + * @brief Initialize with the native pointer of other smart pointer r, count +1. * @brief 用其他智能指针r的原生指针初始化, 计数+1. * * @param Y @@ -175,6 +201,7 @@ public: } /** + * @brief Copy constructor, count +1 * @brief 拷贝构造, 计数+1. * * @param r @@ -190,6 +217,7 @@ public: } /** + * @brief Destructor * @brief 析构 */ ~TC_AutoPtr() @@ -201,6 +229,7 @@ public: } /** + * @brief Assignment, normal pointer * @brief 赋值, 普通指针. * * @param p @@ -227,6 +256,7 @@ public: } /** + * @brief Assignment, other type of smart pointer * @brief 赋值, 其他类型智能指针. * * @param Y @@ -255,6 +285,7 @@ public: } /** + * @brief Assignment, other ruling pointer of this type. * @brief 赋值, 该类型其他执政指针. * * @param r @@ -281,6 +312,7 @@ public: } /** + * @brief Replace other types of smart pointers with current types of smart pointers * @brief 将其他类型的智能指针换成当前类型的智能指针. * * @param Y @@ -294,6 +326,7 @@ public: } /** + * @brief Convert pointers of other native types into smart pointers of the current type * @brief 将其他原生类型的指针转换成当前类型的智能指针. * * @param Y @@ -307,6 +340,7 @@ public: } /** + * @brief Get Native Pointer * @brief 获取原生指针. * * @return T* @@ -317,6 +351,7 @@ public: } /** + * @brief Transfer * @brief 调用. * * @return T* @@ -332,6 +367,7 @@ public: } /** + * @brief Reference * @brief 引用. * * @return T& @@ -347,6 +383,7 @@ public: } /** + * @brief To define whether it is effective or not. * @brief 是否有效. * * @return bool @@ -357,7 +394,8 @@ public: } /** - * @brief 交换指针. + * @brief Swap pointer + * @brief 交换指针. * * @param other */ @@ -369,6 +407,7 @@ public: protected: /** + * @brief Throw Exception * @brief 抛出异常 */ void throwNullHandleException() const; @@ -379,6 +418,7 @@ public: }; /** + * @brief Throw Exception * @brief 抛出异常. * * @param T @@ -392,6 +432,7 @@ TC_AutoPtr::throwNullHandleException() const } /** + * @brief Determine '=='. * @brief ==判断. * * @param T @@ -407,11 +448,13 @@ inline bool operator==(const TC_AutoPtr& lhs, const TC_AutoPtr& rhs) T* l = lhs.get(); U* r = rhs.get(); - // 改为直接比较指针，而不是比较值 + // Compare pointers directly instead of comparing values of the two pointers. + // 改为直接比较指针，而不是比较值 return (l == r); } /** + * @brief Determine '!='. * @brief 不等于判断. * * @param T @@ -427,11 +470,13 @@ inline bool operator!=(const TC_AutoPtr& lhs, const TC_AutoPtr& rhs) T* l = lhs.get(); U* r = rhs.get(); - // 改为直接比较指针，而不是比较值 + // Compare pointers directly instead of comparing values of the two pointers. + // 改为直接比较指针，而不是比较值 return (l != r); } /** + * @brief Determine '<', can be used in map and other conrainers. * @brief 小于判断, 用于放在map等容器中. * * @param T @@ -448,7 +493,8 @@ inline bool operator<(const TC_AutoPtr& lhs, const TC_AutoPtr& rhs) U* r = rhs.get(); if(l && r) { - //return *l < *r; + // return *l < *r; + // Compare pointers directly instead of comparing values of the two pointers. // 改为直接比较指针，而不是比较值 return (l < r); } diff --git a/util/include/util/tc_base64.h b/util/include/util/tc_base64.h index 22e288e..3216896 100644 --- a/util/include/util/tc_base64.h +++ b/util/include/util/tc_base64.h @@ -25,21 +25,30 @@ namespace tars { ///////////////////////////////////////////////// /** -* @file tc_base64.h -* @brief base64编解码类. +* @file tc_base64.h +* @brief base64 Codec Class +* @brief base64编解码类. */ ///////////////////////////////////////////////// /** -* @brief 该类提供标准的Base64的编码解码 +* @brief This class provides standard base64 encoding and decoding methods. +* @brief 该类提供标准的base64的编码解码 */ class TC_Base64 { public: /** - * @brief 对字符串进行base64编码. - * + * @brief Encode the string by base64 + * @brief 对字符串进行base64编码. + * + * @param data Data to be encoded + * @param bChangeLine Add line breaks in the final encoded data if necessary, + * (In the RFC, it is recommended to add an 'Enter' after every 76 characters. + * No newline is added by default.) + * @return string the encoded data + * * @param data 需要编码的数据 * @param bChangeLine 是否需要在最终编码数据加入换行符 ， * (RFC中建议每76个字符后加入回车换行，默认为不添加换行 @@ -48,16 +57,28 @@ public: static string encode(const string &data, bool bChangeLine = false); /** - * @brief 对字符串进行base64解码. - * + * @brief Decode the string by base64 + * @brief 对字符串进行base64解码. + * + * @param data Data to be decoded + * @return string the decoded data + * * @param data 需要解码的数据 * @return string 解码后的数据 */ static string decode(const string &data); /** - * @brief 对字符串进行base64编码. - * + * @brief Encode the string by base64 + * @brief 对字符串进行base64编码. + * + * @param buffer buffer pointer + * @param length length + * @param bChangeLine Add line breaks in the final encoded data if necessary, + * (In the RFC, it is recommended to add an 'Enter' after every 76 characters. + * No newline is added by default.) + * @return string the encoded data + * * @param buffer buffer指针 * @param length 长度 * @param bChangeLine 是否需要在最终编码数据加入换行符 ， @@ -67,7 +88,16 @@ public: static string encode(const char *buffer, size_t length, bool bChangeLine = false); /** + * @brief Encode the string by base64 * @brief 对字符串进行base64编码 . + * + * @param pSrc the data to be encoded + * @param nSrcLen the length of the data to be encoded + * @param pDst the encoded data + * @param bChangeLine Add line breaks in the final encoded data if necessary, + * (In the RFC, it is recommended to add an 'Enter' after every 76 characters. + * No newline is added by default.) + * @return the length of the encoded string * * @param pSrc 需要编码的数据 * @param nSrcLen 需要编码的数据长度 @@ -79,8 +109,14 @@ public: static int encode(const unsigned char* pSrc, size_t nSrcLen, char* pDst, bool bChangeLine = false); /** - * @brief 对字符串进行base64解码. - * + * @brief Decode the string by base64 + * @brief 对字符串进行base64解码 + * + * @param pSrc the data to be decoded + * @param nSrcLe the length of the data to be decoded + * @param pDst the decoded data + * @return the length of the decoded string + * * @param pSrc 需要解码的数据 * @param nSrcLe 需要解码的数据长度 * @param pDst 解码后的数据 @@ -91,11 +127,13 @@ public: protected: /** - * base64编码表 + * base64 Code Table + * base64编码表 */ static const char EnBase64Tab[]; /** - * base64解码表 + * base64 Decode Table + * base64解码表 */ static const char DeBase64Tab[]; }; diff --git a/util/include/util/tc_bitmap.h b/util/include/util/tc_bitmap.h index 10896bb..babce72 100644 --- a/util/include/util/tc_bitmap.h +++ b/util/include/util/tc_bitmap.h @@ -29,10 +29,12 @@ namespace tars ///////////////////////////////////////////////// /** * @file tc_bitmap.h + * @brief Multi-bit Bitmap Class * @brief 多位bitmap类. */ ///////////////////////////////////////////////// /** + * @brief Exception * @brief 异常 */ struct TC_BitMap_Exception : public TC_Exception @@ -43,18 +45,25 @@ struct TC_BitMap_Exception : public TC_Exception /** - * @brief 内存bitmap，每个整数1位，可以支持多位，即几个整数多位. + * @brief Memory bitmap, 1 bit for each integer, can support multiple bits, + * that is, several bits for several integers. + * @brief 内存bitmap，每个整数1位，可以支持多位，即几个整数多位. * - * 操作过程不加锁，如果有需要在外面调用的时候加，通常采用群锁策略. + * The process of the operation will not be locked. + * If it needs to be locked when called outside, the group lock strategy is usually adopted. + * 操作过程不加锁，如果有需要在外面调用的时候加，通常采用群锁策略. * - * 注意群锁策略应该/8，然后按照尾号分群锁 + * Attention that according to the group lock strategy, + * memory block address should be divided by 8, + * and then lock the blocks group by the tail number. + * 注意群锁策略应该/8，然后按照尾号分群锁 */ class TC_BitMap { public: /** + * @brief the bitmap of memories, each integer holds 1 bit * @brief 内存的bitmap，每个整数保持1位 - * */ class BitMap { @@ -66,55 +75,85 @@ public: #define _clear_bit(n,m) (n&(~_magic_bits[m])) #define _get_bit(n,m) (n&_magic_bits[m]) + /**the Version of Shared Memories*/ /**共享内存版本*/ #define BM_VERSION 1 /** + * @brief Calculate the size of the required memory based on the number of elements. * @brief 根据元素个数计算需要内存的大小 - * @param iElementCount, 需要保存的元素个数(元素从0开始记) + * + * @param iElementCount The number of elements to be saved (marked start from 0) + * @param iElementCount 需要保存的元素个数(元素从0开始记) * * @return size_t */ static size_t calcMemSize(size_t iElementCount); /** + * @brief Initialize * @brief 初始化 + * + * @param pAddr Absolute address * @param pAddr 绝对地址 + * + * @param iSize size, calculated by (calcMemSize) * @param iSize 大小, 采用(calcMemSize)计算出来 - * @return 0: 成功, -1:内存不够 + * + * @return 0: success, -1: lack of memories + * @return 0: 成功, -1: 内存不够 */ void create(void *pAddr, size_t iSize); /** + * @brief Link to a memory block * @brief 链接到内存块 + * + * @param pAddr Address, calculated by (calcMemSize) * @param pAddr 地址, 采用(calcMemSize)计算出来 - * @return 0, 成功, -1,版本不对, -2:大小不对 + * + * @return 0:success, -1:wrong version, -2:wrong size + * @return 0:成功, -1:版本不对, -2:大小不对 + * */ int connect(void *pAddr, size_t iSize); /** + * @brief Whether it have mark or not * @brief 是否有标识 - * @param i + * + * @param i + * + * @return int, >0:marked, =0:no mark, <0:out of range * @return int, >0:有标识, =0:无标识, <0:超过范围 + * */ int get(size_t i); /** + * @brief Mark * @brief 设置标识 + * * @param i + * + * @return int, >0:marked, =0:no mark, <0:out of range * @return int, >0:有标识, =0:无标识, <0:超过范围 */ int set(size_t i); /** + * @brief Clear Marks * @brief 清除标识 + * * @param i * + * @return int, >0:marked, =0:no mark, <0:out of range * @return int, >0:有标识, =0:无标识, <0:超过范围 */ int clear(size_t i); /** + * @brief Clear all data * @brief 清除所有的数据 * * @return int @@ -122,6 +161,7 @@ public: int clear4all(); /** + * @brief Dump to File * @brief dump到文件 * @param sFile * @@ -130,104 +170,168 @@ public: int dump2file(const string &sFile); /** + * @brief Load from File * @brief 从文件load + * * @param sFile * * @return int */ int load5file(const string &sFile); + /**the Head of Shared Memories*/ /**共享内存头部*/ #pragma pack(1) struct tagBitMapHead { - char _cVersion; /**版本, 当前版本为1*/ - size_t _iMemSize; /**共享内存大小*/ + char _cVersion; /**version, the current version is 1*/ + /**版本, 当前版本为1*/ + size_t _iMemSize; /**the size of the shared memory*/ + /**共享内存大小*/ }; #pragma pack() /** - * @brief 获取头部地址 + * @brief get the address of the head + * @brief 获取头部地址 + * + * @return tagBitMapHead* the head of the shared memory * @return tagBitMapHead* 共享内存头部 */ BitMap::tagBitMapHead *getAddr() const { return _pHead; } /** - * @brief 获取内存大小 + * @brief get the size of the memory + * @brief 获取内存大小 + * + * @return the size of the memory * @return 内存大小 + * */ size_t getMemSize() const { return _pHead->_iMemSize; } protected: /** + * the Head of the Shared Memory * 共享内存头部 */ tagBitMapHead *_pHead; /** + * pointer of a data block * 数据块指针 */ unsigned char * _pData; }; /** + * @brief Calculate the memory size according to count the number of the elements. * @brief 根据元素个数计算需要内存的大小 + * + * @param iElementCount the number of the elements which needs to be saved(marked started from 0) * @param iElementCount 需要保存的元素个数(元素从0开始记) - * @param iBitCount 每个元素支持几位(默认1位) (位数>=1) + * + * @param iBitCount the max bit value of each element(defualt for 1 bit)(each bit>=1) + * @param iBitCount 每个元素支持几位(默认1位) (位数>=1) + * + * @return the required size of the memory * @return 所需内存的大小 + * */ static size_t calcMemSize(size_t iElementCount, unsigned iBitCount = 1); /** + * @brief Initialize * @brief 初始化 + * + * @param pAddr Absolute Address * @param pAddr 绝对地址 + * + * @param iSize Size, Calculate by (calcMemSize) * @param iSize 大小, 采用(calcMemSize)计算出来 + * + * @return 0: success, -1:lack of memories * @return 0: 成功, -1:内存不够 + * */ void create(void *pAddr, size_t iSize, unsigned iBitCount = 1); /** + * @brief Link to Memory Blocks * @brief 链接到内存块 + * + * @param pAddr Address, Calculate by (calcMemSize) * @param pAddr 地址，采用(calcMemSize)计算出来 + * + * @return 0：success, -1：wrong version, -2:wrong size * @return 0：成功, -1：版本不对, -2:大小不对 + * */ int connect(void *pAddr, size_t iSize, unsigned iBitCount = 1); /** - * @brief 是否有标识 + * @brief Whether it is Marked or not + * @brief 是否有标识 + * + * @param i the value of the element * @param i 元素值 - * @param iBit 第几位 + * + * @param iBit bit number + * @param iBit 第几位 + * + * @return int, >0:maked, =0:no mark, <0:out of range * @return int, >0:有标识, =0:无标识, <0:超过范围 + * */ int get(size_t i, unsigned iBit = 1); /** + * @brief Mark * @brief 设置标识 + * + * @param i the value of the element * @param i 元素值 - * @param iBit 第几位 + * + * @param iBit bit number + * @param iBit 第几位 + * + * @return int, >0:marked, =0:no mark, <0:outof range * @return int, >0:有标识, =0:无标识, <0:超过范围 + * */ int set(size_t i, unsigned iBit = 1); /** + * @brief Clear a mark * @brief 清除标识 + * + * @param i the value of the element * @param i 元素值 + * + * @param iBit bit number * @param iBit 第几位 + * + * @return int, >0:marked, =0:no mark, <0:out of range * @return int, >0:有标识, =0:无标识, <0:超过范围 */ int clear(size_t i, unsigned iBit = 1); /** + * @brief Clear all marks * @brief 清除所有的标识 * + * @param iBit bit number * @param iBit 第几位 + * * @return int */ int clear4all(unsigned iBit = (unsigned)(-1)); /** + * @brief Dump to File * @brief dump到文件 + * * @param sFile * * @return int @@ -235,7 +339,9 @@ public: int dump2file(const string &sFile); /** + * @brief Load from File * @brief 从文件load + * * @param sFile * * @return int