diff --git a/base/include/ashmem.h b/base/include/ashmem.h index c8ac9a129c9397469a6f25a155238517d4c7e8e5..78d9304734fa028cce6871a5a6286671bd13d591 100644 --- a/base/include/ashmem.h +++ b/base/include/ashmem.h @@ -16,8 +16,8 @@ /** * @file ashmem.h * - * @brief Provide class Ashmem implemented in c_utils to operate the - * Anonymous Shared Memory(Ashmem). + * @brief Provides the Ashmem class implemented in c_utils to operate the + * Anonymous Shared Memory (Ashmem). */ #ifndef UTILS_BASE_ASHMEM_H @@ -42,53 +42,58 @@ std::shared_ptr CreateAshmemStd(const char *name, int32_t size); #endif /** - * @brief Create ashmem in kernel with specified name and size. + * @brief Creates an Ashmem region in the kernel. * - * @param name Name for identifying the ashmem in kernel. - * @param size Size of the ashmem region. - * @return File descriptor of the ashmem. + * @param name Indicates the pointer to the name that will be + * copied and assigned to the Ashmem region in the kernel. + * @param size Indicates the size of the Ashmem region to create. + * @return Returns the file descriptor of the Ashmem region. */ int AshmemCreate(const char *name, size_t size); /** - * @brief Set protection flag of specified ashmem region in kernel. - - * @param fd Corresponding file descriptor. - * @param prot Value of protection flag. - * @return Return 0 on success, -1 on failure. + * @brief Sets the protection flag of an Ashmem region in the kernel. + * + * @param fd Indicates the file descriptor of an Ashmem region. + * @param prot Indicates the value of the protection flag. + * @return Returns 0 if the operation is successful; + * returns -1 otherwise. */ int AshmemSetProt(int fd, int prot); /** - * @brief Get size of specified ashmem region in kernel. + * @brief Obtains the size of a specific Ashmem region in the kernel. * - * @param fd Corresponding file descriptor. - * @return Size of ashmem. + * @param fd Indicates the file descriptor of an Ashmem region. + * @return Returns the size of the Ashmem region. */ int AshmemGetSize(int fd); /** - * @brief Ashmem implemented in c_utils, to operate the - * Anonymous Shared Memory(Ashmem). + * @brief Provides the Ashmem class implemented in c_utils to + * operate the Anonymous Shared Memory (Ashmem). * - * Including create, map an ashmem region and thus write/read to/from it, etc. + * You can use the interfaces in this class to create Ashmem regions + * and map them to implement write and read operations. * - * @note Ashmem object should be unmapped and closed manually, though managed - * by smart pointer. + * @note Ashmem regions should be unmapped and closed manually, + * though managed by a smart pointer. */ class Ashmem : public virtual RefBase { public: /** - * @brief Create an Ashmem object with specified name and region size. + * @brief Creates an Ashmem region in the kernel. + * + * The /dev/ashmem file will be opened, whose file + * descriptor will be held by the created Ashmem region. * - * File '/dev/ashmem' will be opened whose file descriptor will be held by - * this Ashmem object. + * @param name Indicates the pointer to the name that will be + * copied and assigned to the Ashmem region in the kernel. + * @param size Indicates the size of the Ashmem region. + * @return Returns the created Ashmem region referenced by a + * smart pointer. + * @note Before writing/reading data in the region, use `MapAshmem()`. * - * @param name Name for identifying the ashmem in kernel. - * @param size Size of the ashmem region. - * @return An Ashmem object referenced by a smart pointer. - * @note Memory has not been mapped, use `MapAshmem()` before - * writing/reading. */ static sptr CreateAshmem(const char *name, int32_t size); @@ -144,88 +149,92 @@ public: const void *ReadFromAshmem(int32_t size, int32_t offset) const; #else /** - * @brief Close the ashmem(i.e. close it via file descriptor). + * @brief Closes this Ashmem region (through the file descriptor). * * All inner parameters will be cleared. * - * @note An ashmem will be unmapped first by `UnmapAshmem()` before close. + * @note An Ashmem region will be unmapped by `UnmapAshmem()` + * before being closed. */ void CloseAshmem(); /** - * @brief Map the ashmem region in the kernel to user space. + * @brief Maps this Ashmem region in the kernel to user space. * - * @param mapType Protection flag of the mapped region in user space. - * @return True if mapping successful. + * @param mapType Indicates the protection flag of the mapped region in + * user space. + * @return Returns true if mapping is successful. */ bool MapAshmem(int mapType); /** - * @brief Map the ashmem region in Read/Write mode. + * @brief Maps this Ashmem region in read/write mode. * * It calls `MapAshmem(PROT_READ | PROT_WRITE)`. * - * @return True if mapping successful. + * @return Returns true if mapping is successful. */ bool MapReadAndWriteAshmem(); /** - * @brief Map the ashmem region in Read-Only mode. + * @brief Maps this Ashmem region in read-only mode. * * It calls `MapAshmem(PROT_READ)`. * - * @return True if mapping successful. + * @return Returns true if mapping is successful. */ bool MapReadOnlyAshmem(); /** - * @brief Unmap the ashmem. + * @brief Unmaps this Ashmem region. * - * Unmap when mapped ashmem exists, protection flag will be cleared - * meanwhile. + * Unmapping works only when the Ashmem region has been mapped. + * It will clear the protection flag. */ void UnmapAshmem(); /** - * @brief Write data to the `offset` position of ashmem region. - * - * Bounds and protection flag will be checked. - * - * @param data Pointer to input data. - * @param size Size of the input data(bytes). - * @param offset Offset from beginning of the region. - * @return True if writting successful. False if data to be write overflows - * or protection flag is illegal. - * @note Require write authority of both ashmem in kernel and the mapped - * one in user space. + * @brief Writes data to the `offset` position of this Ashmem region. + * + * Bounds and the protection flag will be checked. + * + * @param data Indicates the pointer to the data to write. + * @param size Indicates the size of the data to write, in bytes. + * @param offset Indicates the offset from the start position of the + * Ashmem region. + * @return Returns True if the operation is successful; returns + * False if overflow occurs or the protection flag is illegal. + * @note This operation requires the write permission on both the + * Ashmem region in the kernel and the mapped region in user space. */ bool WriteToAshmem(const void *data, int32_t size, int32_t offset); /** - * @brief Read data from the `offset` position of ashmem region. + * @brief Reads data from the `offset` position of this Ashmem region. * - * Bounds and protection flag will be checked. + * Bounds and the protection flag will be checked. * - * @param size Size of data to be read(bytes). - * @param offset Offset from beginning of the region. - * @return Void-type pointer to the data. `nullptr` returns if data to be - * read overflows or protection flag is illegal. - * @note Require read authority of both ashmem in kernel and the mapped one - * in user space. + * @param size Indicates the size of the data to read, in bytes. + * @param offset Indicates the offset from the start position of + * the Ashmem region. + * @return Returns the void-type pointer to the data. `nullptr` is returned + * if overflow occurs or the protection flag is illegal. + * @note This operation requires the read permission on both the + * Ashmem region in the kernel and the mapped region in user space. */ const void *ReadFromAshmem(int32_t size, int32_t offset); #endif private: #ifdef UTILS_CXX_RUST - mutable int memoryFd_; // corresponding file descriptor of ashmem. - mutable int32_t memorySize_; // size of ashmem. - mutable int flag_; // protection flag of ashmem in user space. - mutable void *startAddr_; // start address of ashmem region. + mutable int memoryFd_; // File descriptor of the Ashmem region. + mutable int32_t memorySize_; // Size of the Ashmem region. + mutable int flag_; // Protection flag of the Ashmem region in user space. + mutable void *startAddr_; // Start address of the Ashmem region. #else - int memoryFd_; // corresponding file descriptor of ashmem. - int32_t memorySize_; // size of ashmem. - int flag_; // protection flag of ashmem in user space. - void *startAddr_; // start address of ashmem region. + int memoryFd_; // File descriptor of the Ashmem region. + int32_t memorySize_; // Size of the Ashmem region. + int flag_; // Protection flag of the Ashmem region in user space. + void *startAddr_; // Start address of the Ashmem region. #endif bool CheckValid(int32_t size, int32_t offset, int cmd) const; diff --git a/base/include/common_errors.h b/base/include/common_errors.h index 02553a2ede27badc9cd76b16f1157ced95f1a36b..89a4666b7b0df2ff54a1d78d7d26317e1ff905c1 100644 --- a/base/include/common_errors.h +++ b/base/include/common_errors.h @@ -16,8 +16,8 @@ /** * @file common_errors.h * - * @brief Provide value of 'Module' segment of ErrCode for all modules in - * commonlibrary subsystem. + * @brief Provides values of the Module segment in ErrCode + * for all modules in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_ERRORS_H @@ -35,12 +35,12 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON". + * In this file, the subsystem is "SUBSYS_COMMON". */ /** - * @brief Value of 'Module' segment of ErrCode for modules in commonlibrary - * subsystem. + * @brief Enumerates the values of the Module segment of ErrCode + * for modules in the commonlibrary subsystem. * * @var MODULE_DEFAULT Default * @var MODULE_TIMER Timer(timer.h) diff --git a/base/include/common_mapped_file_errors.h b/base/include/common_mapped_file_errors.h index 7174fb4c5e180f85f0c6d6426d9b0fe6079af55c..1f50c8a813267bec50dcf6d3ddc4fe7b45a7bd5f 100644 --- a/base/include/common_mapped_file_errors.h +++ b/base/include/common_mapped_file_errors.h @@ -16,19 +16,20 @@ /** * @file common_mapped_file_errors.h * - * @brief Provide value of 'Code' segment of ErrCode for 'MappedFile' module in - * commonlibrary subsystem. + * @brief Provides the values of the Code segment in ErrCode + * for the MappedFile module in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_TIMER_ERRORS_H #define UTILS_COMMON_TIMER_ERRORS_H #include -#include "common_errors.h" #include "errors.h" +#include "common_errors.h" namespace OHOS { namespace Utils { + /** * ErrCode layout * @@ -38,14 +39,16 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON" and module is "MODULE_MAPPED_FILE". + * In this file, the subsystem is "SUBSYS_COMMON", and the module is + * "MODULE_MAPPED_FILE". */ using ErrCode = int; -// offset of mapped file module error, only be used in this file. +// The error codes can be used only for the MappedFile module. /** - * @brief Base ErrCode of module 'MappedFile' in commonlibrary subsystem. + * @brief Provides the base error codes of the MappedFile module + * in the commonlibrary subsystem. */ constexpr ErrCode COMMON_MAPPED_FILE_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON, MODULE_MAPPED_FILE); diff --git a/base/include/common_timer_errors.h b/base/include/common_timer_errors.h index 9c90ccd1a428d73cf6807f259e6c4f6b4d1390ac..522a435ca2d9ef63834e3f0e3d3d36e1867ffcf7 100644 --- a/base/include/common_timer_errors.h +++ b/base/include/common_timer_errors.h @@ -16,8 +16,8 @@ /** * @file common_timer_errors.h * - * @brief Provide value of 'Code' segment of ErrCode for 'Timer' module in - * commonlibrary subsystem. + * @brief Provides the values of the Code segment in ErrCode + * for the Timer module in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_TIMER_ERRORS_H @@ -39,24 +39,27 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON" and module is "MODULE_TIMER". + * In this file, the subsystem is "SUBSYS_COMMON", and the module is + * "MODULE_TIMER". */ using ErrCode = int; -// offset of timer module error, only be used in this file. +// The error codes can be used only for the Timer module. /** - * @brief Base ErrCode of module 'Timer' in commonlibrary subsystem. + * @brief Provides the base error codes of the Timer module + * in the commonlibrary subsystem. */ constexpr ErrCode COMMON_TIMER_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON, MODULE_TIMER); /** - * @brief Value of 'Code' segment of ErrCode for 'Timer'. + * @brief Enumerates the values of the Code segment in ErrCode + * for the Timer module. * - * @var TIMER_ERR_OK Success. - * @var TIMER_ERR_DEAL_FAILED Deal failed. - * @var TIMER_ERR_BADF Bad file descriptor. - * @var TIMER_ERR_INVALID_VALUE Invalid value. + * @var TIMER_ERR_OK Indicates an operation success. + * @var TIMER_ERR_DEAL_FAILED Indicates an operation failure. + * @var TIMER_ERR_BADF Indicates a bad file descriptor. + * @var TIMER_ERR_INVALID_VALUE Indicates an invalid value. */ enum { TIMER_ERR_OK = 0, diff --git a/base/include/datetime_ex.h b/base/include/datetime_ex.h index cc94633d925eef4b465a70061c072303ca13fa3a..7acd8258cfad1ce9f97ecf476d08c1a02687c90b 100644 --- a/base/include/datetime_ex.h +++ b/base/include/datetime_ex.h @@ -24,21 +24,21 @@ namespace OHOS { * Here is the definition of strct tm: * struct tm * { - * int tm_sec; // Seconds. [0-60] (1 leap second) - * int tm_min; // Minutes. [0-59] - * int tm_hour; // Hours. [0-23] - * int tm_mday; // Day. [1-31] - * int tm_mon; // Month. [0-11] + * int tm_sec; // Seconds. Value range: [0-60] (1 leap second) + * int tm_min; // Minutes. Value range: [0-59] + * int tm_hour; // Hours. Value range: [0-23] + * int tm_mday; // Day. Value range: [1-31] + * int tm_mon; // Month. Value range: [0-11] * int tm_year; // Year - 1900. - * int tm_wday; // Day of week. [0-6] - * int tm_yday; // Days in year.[0-365] - * int tm_isdst; // DST. [-1/0/1] + * int tm_wday; // Day of week. Value range: [0-6] + * int tm_yday; // Days in year. Value range: [0-365] + * int tm_isdst; // DST. Value range: [-1/0/1] * #ifdef __USE_BSD - * long int tm_gmtoff; //Seconds east of UTC. - * __const char *tm_zone; //Timezone abbreviation. + * long int tm_gmtoff; // Seconds east of UTC. + * __const char *tm_zone; // Time zone abbreviation. * #else - * long int __tm_gmtoff; //Seconds east of UTC. - * __const char *__tm_zone; //Timezone abbreviation. + * long int __tm_gmtoff; // Seconds east of UTC. + * __const char *__tm_zone; // Time zone abbreviation. * #endif * }; */ @@ -53,7 +53,7 @@ constexpr int SECONDS_PER_HOUR = 3600; // 60 * 60 constexpr int SECONDS_PER_DAY = 86400; // 60 * 60 * 24 /** - * @brief Convert seconds to nanoseconds. + * @brief Converts seconds to nanoseconds. */ constexpr inline int64_t SecToNanosec(int64_t sec) { @@ -61,7 +61,7 @@ constexpr inline int64_t SecToNanosec(int64_t sec) } /** - * @brief Convert milliseconds to nanoseconds. + * @brief Converts milliseconds to nanoseconds. */ constexpr inline int64_t MillisecToNanosec(int64_t millise) { @@ -69,7 +69,7 @@ constexpr inline int64_t MillisecToNanosec(int64_t millise) } /** - * @brief Convert microseconds to nanoseconds. + * @brief Converts microseconds to nanoseconds. */ constexpr inline int64_t MicrosecToNanosec(int64_t microsec) { @@ -77,7 +77,7 @@ constexpr inline int64_t MicrosecToNanosec(int64_t microsec) } /** - * @brief Convert nanoseconds to seconds. + * @brief Converts nanoseconds to seconds. */ constexpr inline int64_t NanosecToSec(int64_t nanosec) { @@ -93,7 +93,7 @@ constexpr inline int64_t NanosecToMillisec(int64_t nanosec) } /** - * @brief Convert nanoseconds to microseconds. + * @brief Converts nanoseconds to microseconds. */ constexpr inline int64_t NanosecToMicrosec(int64_t nanosec) { @@ -101,48 +101,52 @@ constexpr inline int64_t NanosecToMicrosec(int64_t nanosec) } /** - * @brief Get seconds from 1970 to now. + * @brief Obtains the number of seconds from 00:00:00 on January 1, 1970 + * to the current time. */ int64_t GetSecondsSince1970ToNow(); /** - * @brief Get seconds from 1970 to inputtime. + * @brief Obtains the number of seconds from 00:00:00 on January 1, 1970 + * to the specified point of time. */ int64_t GetSecondsSince1970ToPointTime(struct tm inputTm); /** - * @brief Get seconds between inputTm1 and inputTm2. + * @brief Obtains the number of seconds between inputTm1 and inputTm2. */ int64_t GetSecondsBetween(struct tm inputTm1, struct tm inputTm2); /** - * @brief Get days from 1970 to now. + * @brief Obtains the number of days from January 1, 1970 to the current date. */ int64_t GetDaysSince1970ToNow(); /** - * @brief Get current timezone. + * @brief Obtains the local time zone. * - * @param timezone Today the world is divided into 24 timezones, they are - * medium timezone (zero timezone), east 1-12 timezone, west 1-12 timezone.The - * East time zone is +1 to +12 and the West time zone is -1 to -12. - * @return return true if get success, else false. + * @param timezone Indicates the time zone. A total of 24 time zones are + * supported, with the eastern time zones represented by +1 to +12, and + * the western time zones -1 to -12. + * @return Returns true if the operation is successful; + * returns false otherwise. */ bool GetLocalTimeZone(int& timezone); /** - * @brief Get current time. - * @return return true if get success, else false. + * @brief Obtains the current time. + * @return Returns true if the operation is successful; + * returns false otherwise. */ bool GetSystemCurrentTime(struct tm* curTime); /** - * @brief Get current milliseconds since the system was started. + * @brief Obtains the number of milliseconds since the system was started. */ int64_t GetTickCount(); /** - * @brief Get current microseconds since the system was started. + * @brief Obtains the number of microseconds since the system was started. */ int64_t GetMicroTickCount(); } diff --git a/base/include/directory_ex.h b/base/include/directory_ex.h index a7c685cb23ab48fc5009c1940bc38aec7a132640..7cf9482e04660a0dbfb6d71f583d3f1d7b808385 100644 --- a/base/include/directory_ex.h +++ b/base/include/directory_ex.h @@ -38,128 +38,135 @@ void RustGetDirFiles(const rust::String& path, rust::vec& files); #endif /** - * @brief Get the full absolute path to the current program. + * @brief Obtains the full absolute path of this program. * - * /proc/self/exe represents the current program, and its source path can be - * read with the readlink function to get the absolute path of the current - * program. + * /proc/self/exe indicates the program, and you can obtain its absolute + * path by using readlink(). */ std::string GetCurrentProcFullFileName(); /** - * @brief Get the absolute path of the current program. + * @brief Obtains the absolute path of this program. */ std::string GetCurrentProcPath(); /** - * @brief Obtain the path to the corresponding file by the full path. + * @brief Obtains the path of a file based on the full path. */ std::string ExtractFilePath(const std::string& fileFullName); /** - * @brief Obtain the name to the corresponding file by the full path. + * @brief Obtains the name of a file based on the full path. */ std::string ExtractFileName(const std::string& fileFullName); /** - * @brief Obtain the filename extension to the corresponding file by the full - * path. + * @brief Obtains the filename extension based on the full path. + * */ std::string ExtractFileExt(const std::string& fileName); /** - * @brief Exclude the end '/' from the strPath. + * @brief Excludes the trailing path delimiter '/' from the strPath. * - * Determine whether the path has ended with '/', and returns the path after - * removing '/', otherwise returns the path directly. + * If the path ends with '/', returns the path after removing '/'. + * Otherwise, returns the path directly. */ std::string ExcludeTrailingPathDelimiter(const std::string& path); /** - * @brief Include the end '/' from the strPath. + * @brief Includes the trailing path delimiter '/' in the strPath. * - * Determine whether the path has ended with "/", and returns the path after - * adding '/', otherwise returns the path directly. + * If the path ends with "/", returns the path. + * Otherwise, returns the path with an appended delimiter. */ std::string IncludeTrailingPathDelimiter(const std::string& path); /** - * @brief Get names of all files under `path` recursively. + * @brief Obtains the names of all files in the specified directory recursively. * - * @param path Input path. - * @param files Target `std::vector` to store the file names. + * @param path Indicates the target directory. + * @param files Indicates the std::vector to store the file names. */ void GetDirFiles(const std::string& path, std::vector& files); /** - * @brief Judge if the path is empty. + * @brief Checks whether a folder is empty. * - * @return Return true if is empty, else false. + * @return Returns true if the folder is empty; + * returns false otherwise. */ bool IsEmptyFolder(const std::string& path); /** - * @brief Create the dir recursively. + * @brief Creates a directory recursively. * - * Parent directory can be created at the same time when it does not exist. + * The parent directory can be created at the same time when it does not exist. * - * @note If there are problems such as 'Permission Denied', the creation may + * @note If there are errors such as 'Permission Denied', the creation may * also fail. - * @return Return true if create success, else false. + * @return Returns true if the directory is created; + * returns false otherwise. */ bool ForceCreateDirectory(const std::string& path); /** - * @brief Delete the specified dir. + * @brief Deletes a directory. * - * All subdirs and files will also be deleted. + * All subdirectories and files in the specified directory will also be deleted. * * @note It is not necessarily successful to delete. - * @note If there are problems such as 'Permission Denied', the deletion may + * @note If there are errors such as 'Permission Denied', the deletion may * also fail. - * @return Return true if delete success, else false. + * @return Returns true if the directory is deleted; + * returns false otherwise. */ bool ForceRemoveDirectory(const std::string& path); /** - * @brief Remove the file specified by fileName. + * @brief Removes the file specified by fileName. * - * @return Return true if remove success, else false. + * @return Returns true if the file is removed; + * returns false otherwise. */ bool RemoveFile(const std::string& fileName); /** - * @brief Get the folder size(bytes). + * @brief Obtains the folder size, in bytes. */ uint64_t GetFolderSize(const std::string& path); /** - * @brief Change the file authority. + * @brief Changes the access permissions on a file. * - * @param mode Specify the changed permissions, see chmod(). - * @return Return true if change success, else false. + * @param mode Indicates the permissions on the file. + * For details, see chmod(). + * @return Returns true if the permissions are changed; + * returns false otherwise. */ bool ChangeModeFile(const std::string& fileName, const mode_t& mode); /** - * @brief Change authority of the directory specified by path and all of its + * @brief Changes the access permissions on a directory and all its * subdirectories. * - * @param mode Specify the changed permissions, see chmod(). - * @return Return true if change success, else false. + * @param mode Indicates the permissions. For details, see chmod(). + * @return Returns true if the permissions are changed; + * returns false otherwise. */ bool ChangeModeDirectory(const std::string& path, const mode_t& mode); /** - * @brief Get real path from relative path. + * @brief Obtains the real path from a relative path. * - * @return Return true if get success, else false. + * @return Returns true if the real path is obtained; + * returns false otherwise. */ bool PathToRealPath(const std::string& path, std::string& realPath); #if defined(IOS_PLATFORM) || defined(_WIN32) /** - * @brief The TransformFileName function transform the input file name for windows or mac. + * @brief Transforms a file name to that for Windows or macOS. */ std::string TransformFileName(const std::string& fileName); #endif diff --git a/base/include/errors.h b/base/include/errors.h index 56f61fc2508a108a107a18b9a08080ecd4c3e270..121c56f2a85d48a0193ac1192035524f17b5e33e 100644 --- a/base/include/errors.h +++ b/base/include/errors.h @@ -16,7 +16,7 @@ /** * @file errors.h * - * @brief Provide format of error code in OpenHarmony. + * @brief Provides format of error code in OpenHarmony. */ #ifndef UTILS_BASE_ERRORS_H @@ -39,7 +39,8 @@ namespace OHOS { using ErrCode = int; /** - * @brief Value of 'Subsystem' segment of ErrCode for every subsystem. + * @brief Enumerates the values of the Subsystem segment + * of ErrCode for every subsystem. */ enum { SUBSYS_COMMON = 0, @@ -97,13 +98,13 @@ enum { // be used to init the subsystem errorno. /** - * @brief Generate base error code for a specified module in specified - * subsystem. + * @brief Generates the base error codes for a specified module + * in specified subsystem. * - * @param subsystem Value of 'Subsystem' segment. - * @param module Value of 'Module' segment, - * which is 0 by default. - * @return Return base ErrCode for specified module. + * @param subsystem Indicates the subsystem. + * @param module Indicates the module. + * The default value is 0. + * @return Returns the base error codes of the specified module. */ constexpr ErrCode ErrCodeOffset(unsigned int subsystem, unsigned int module = 0) { @@ -114,14 +115,14 @@ constexpr ErrCode ErrCodeOffset(unsigned int subsystem, unsigned int module = 0) // offset of common error, only be used in this file. /** - * @brief Base ErrCode of common(valid for all modules) - * in commonlibrary subsystem. + * @brief Provides the common base error codes, which apply to all modules, + * in the commonlibrary subsystem. */ constexpr ErrCode BASE_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON); /** - * @brief Value of common 'Code' segment of ErrCode - * in commonlibrary subsystem. + * @brief Enumerates the common base error codes + * in the commonlibrary subsystem. * * @see Related error codes defined in errno.h */ diff --git a/base/include/file_ex.h b/base/include/file_ex.h index 9d672c964cd7bcf33a3f55ffde3c287dd6caa465..2ee9b50a8d408e3c3d58c4a2357188c1e11d4052 100644 --- a/base/include/file_ex.h +++ b/base/include/file_ex.h @@ -15,15 +15,16 @@ /** @file file_ex.h * -* @brief Provide global file operation functions implemented in c_utils. +* @brief Provides global file operation functions implemented in c_utils. */ /** * @defgroup FileReadWrite * @{ -* @brief To read from and write to files. +* @brief Provides interfaces for reading data from and writing data to files. * -* Include reading from or writting to files and searching for specified strings. +* You can use the interfaces to read data from a file, write data to a file, +* and search for the specified string. */ #ifndef UTILS_BASE_FILE_EX_H @@ -49,96 +50,107 @@ int RustCountStrInFile(const rust::String& fileName, const rust::String& subStr #endif /** * @ingroup FileReadWrite - * @brief Read contents as a string from the specified file. + * @brief Reads a string from a file. * - * @param filePath Path of the specified file. - * @param content Target `std::string` object to store the result. - * @return Return true on success, false if any error occurs. - * @note Maximum size of the file is 32MB. + * @param filePath Indicates the path of the target file. + * @param content Indicates the std::string object used to hold + * the data read. + * @return Returns true if the string is read successfully; + * returns false otherwise. + * @note The maximum file size is 32 MB. */ bool LoadStringFromFile(const std::string& filePath, std::string& content); /** * @ingroup FileReadWrite - * @brief Write contents of a string to the specified file. + * @brief Writes a string to a file. * - * @param filePath Path of the specified file. - * @param content Target `std::string` object to be written to the file. - * @param truncated Specify if truncated the original file. - * @return Return true on success, false if any error occurs. + * @param filePath Indicates the path of the target file. + * @param content Indicates the std::string object to write. + * @param truncated Indicates whether to truncate the original file. + * @return Returns true if the string is written successfully; + * returns false otherwise. */ bool SaveStringToFile(const std::string& filePath, const std::string& content, bool truncated = true); /** * @ingroup FileReadWrite - * @brief Read contents as a string from the file specified by its fd. + * @brief Reads a string from a file specified by its file descriptor (FD). * - * @param fd File descriptor of the specified file. - * @param content Target `std::string` object to store the result. - * @return Return true on success, false if any error occurs. + * @param fd Indicates the FD of the file to read. + * @param content Indicates the std::string object used to hold + * the data read. + * @return Returns true if the string is read successfully; + * returns false otherwise. */ bool LoadStringFromFd(int fd, std::string& content); /** * @ingroup FileReadWrite - * @brief Write contents of a string to the file specified by its fd. + * @brief Writes a string to a file specified by its FD. * - * @param fd File descriptor of the specified file. - * @param content Target `std::string` object to be written to the file. - * @return Return true on success, false if any error occurs. + * @param fd Indicates the FD of the file to write. + * @param content Indicates the std::string object to write. + * @return Returns true if the string is written successfully; + * returns false otherwise. */ bool SaveStringToFd(int fd, const std::string& content); /** * @ingroup FileReadWrite - * @brief Read contents as a vector from the specified file. + * @brief Reads data as a vector from a file. * - * @param filePath Path of the specified file. - * @param content Target `std::vector` object to store the result. - * @return Return true on success, false if any error occurs. + * @param filePath Indicates the path of the target file. + * @param content Indicates the std::vector object used to hold + * the data read. + * @return Returns true if the data is read successfully; + * returns false otherwise. */ bool LoadBufferFromFile(const std::string& filePath, std::vector& content); /** * @ingroup FileReadWrite - * @brief Write contents of a vector to the specified file. + * @brief Writes data of a vector to a file. * - * @param filePath Path of the specified file. - * @param content Target `std::vector` object to be written to the file. - * @return Return true on success, false if any error occurs. + * @param filePath Indicates the path of the target file. + * @param content Indicates the std::vector object to write. + * @return Returns true if the data is written successfully; + * returns false otherwise. */ bool SaveBufferToFile(const std::string& filePath, const std::vector& content, bool truncated = true); /** * @ingroup FileReadWrite - * @brief Check if the specified file exists + * @brief Checks whether a file exists. * - * @param filePath Path of the specified file. - * @return Return true on success, - * false if any error(e.g. Permission Denied) occurs. + * @param filePath Indicates the file to check. + * @return Returns true if the file exists; returns false + * if any error (e.g. Permission Denied) occurs. */ bool FileExists(const std::string& fileName); /** * @ingroup FileReadWrite - * @brief Check if the file contains specified contents in string. + * @brief Checks whether a file contains the specified string. * - * @param fileName Path of the specified file. - * @param subStr Specified `std::string` object - * @param caseSensitive Specify if case-sensitive - * @return Return true if the file contains the specified string, - * false if any error occurs. + * @param fileName Indicates the path of the target file. + * @param subStr Indicates the std::string object to check. + * @param caseSensitive Indicates whether the string is case-sensitive. + * @return Returns true if the file contains the specified string; + * returns false otherwise. */ bool StringExistsInFile(const std::string& fileName, const std::string& subStr, bool caseSensitive = true); /** * @ingroup FileReadWrite - * @brief Get amount of the specified string in the file. + * @brief Obtains the number of occurrences of the specified string in a file. + * - * @param fileName Path of the specified file. - * @param subStr Specified `std::string` object - * @param caseSensitive Specify if case-sensitive - * @return Return the amount, return 0 if `subStr` is null. + * @param fileName Indicates the path of the target file. + * @param subStr Indicates the std::string object to search. + * @param caseSensitive Indicates whether the string is case-sensitive. + * @return Returns the number of occurrences of the string in the file; + * returns 0 if subStr is null. */ int CountStrInFile(const std::string& fileName, const std::string& subStr, bool caseSensitive = true); } diff --git a/base/include/flat_obj.h b/base/include/flat_obj.h index 5d715ffd02fe65901ff997525e1bf21f8911c825..1691998f83836aee00786717cf6cd36e1ebbbb20 100644 --- a/base/include/flat_obj.h +++ b/base/include/flat_obj.h @@ -16,10 +16,10 @@ /** * @file flat_obj.h * - * @brief Define types and structures for reading and writing object in parcel. + * @brief Defines types and structures for reading and writing objects in parcels. * - * Types are platform-sensitive. Structures is only used for checking the - * validity of data in parcel, not for saving and using of data. + * Types are platform-sensitive. Structures are only used for checking the + * validity of data in parcels, not for saving and using of data. */ #ifndef UTILS_BASE_FLAT_OBJ_H #define UTILS_BASE_FLAT_OBJ_H diff --git a/base/include/mapped_file.h b/base/include/mapped_file.h index 2c0616ac172bb64ecd774331c1e90d233457044d..03394397b4c47978546889d88b8d3e2b94094962 100644 --- a/base/include/mapped_file.h +++ b/base/include/mapped_file.h @@ -16,7 +16,7 @@ /** * @file mapped_file.h * - * @brief Provide classes for memory-mapped file implemented in c_utils. + * @brief Provides classes for memory-mapped files implemented in c_utils. */ #ifndef UTILS_BASE_MAPPED_FILE_H diff --git a/base/include/nocopyable.h b/base/include/nocopyable.h index dfb96cf662a9d934391c6d4d9e1f6f75a5a19be1..75876b5dfba53d00ed2c30151a8f6a5ec629ac80 100644 --- a/base/include/nocopyable.h +++ b/base/include/nocopyable.h @@ -19,21 +19,21 @@ namespace OHOS { /** - * @brief Disable the copy and move construct/assignment method. + * @brief Disables the copy and move construct/assignment method. */ #define DISALLOW_COPY_AND_MOVE(className)\ DISALLOW_COPY(className);\ DISALLOW_MOVE(className) /** - * @brief Disable the copy construct/assignment method. + * @brief Disables the copy construct/assignment method. */ #define DISALLOW_COPY(className)\ className(const className&) = delete;\ className& operator= (const className&) = delete /** - * @brief Disable the move construct/assignment method. + * @brief Disables the move construct/assignment method. */ #define DISALLOW_MOVE(className)\ className(className&&) = delete;\ diff --git a/base/include/observer.h b/base/include/observer.h index 07e60f95b619605ad2b6564b903e253e9ead91bb..35811afbd289eccf3ccb8d5f54752d6694bcacf1 100644 --- a/base/include/observer.h +++ b/base/include/observer.h @@ -24,7 +24,7 @@ namespace OHOS { /** - * @brief Parameters and data required to call the update method. + * @brief Provides the parameters and data required to call the update method. */ struct ObserverArg { public: @@ -32,73 +32,75 @@ public: }; /** - * @brief Observer class. + * @brief Implements the Observer class. */ class Observer; /** - * @brief Observed class. + * @brief Implements the observed class. */ class Observable { public: virtual ~Observable() = default; /** - * @brief Add the specified observer to the set of observers. + * @brief Adds the specified observer to the set of observers. * * If `o` is valid and does not exist in the observer set, the observer - * will be added, otherwise this function will return directly. + * will be added; otherwise, this function will return directly. */ void AddObserver(const std::shared_ptr& o); /** - * @brief Remove the observer passed in from the parameter. + * @brief Removes the specified observer. */ void RemoveObserver(const std::shared_ptr& o); /** - * @brief Remove all observers. + * @brief Removes all observers. */ void RemoveAllObservers(); /** - * @brief Notify all observers without data transmission. + * @brief Notifies all observers with no data passed. * - * Equivalent to NotifyObservers(nullptr). + * This function is equivalent to NotifyObservers(nullptr). */ void NotifyObservers(); /** - * @brief Notify all observers, and pass the data 'arg' to the observer. + * @brief Notifies all observers, with the data 'arg' passed to + * the observers. * - * If the `changed_` is true, call the `Update()` function to notify all + * If `changed_` is true, call the `Update()` function to notify all * observers to respond. * - * @param arg Parameters and data maybe used for Observer::Update(). + * @param arg Indicates the parameters and data to be used for + * Observer::Update(). * @see ObserverArg. */ void NotifyObservers(const ObserverArg* arg); /** - * @brief Get the number of observers. + * @brief Obtains the number of observers. */ int GetObserversCount(); protected: /** - * @brief Get the state of this Observable object. + * @brief Obtains the state of this Observable object. * - * @return The value of `changed_`. + * @return Returns the value of `changed_`. */ bool HasChanged(); /** - * @brief Set the state of this Observable object to true. + * @brief Sets the state of this Observable object to true. */ void SetChanged(); /** - * @brief Set the state of this Observable object to false. + * @brief Set the state of this Observable object to false. */ void ClearChanged(); @@ -114,9 +116,10 @@ class Observer { public: virtual ~Observer() = default; /** - * @brief The observer's interface to update itself. + * @brief Updates this observer. * - * It will be called when this object is notified by an Observable object. + * It will be called when this observer is notified by an + * Observable object. */ virtual void Update(const Observable* o, const ObserverArg* arg) = 0; }; diff --git a/base/include/parcel.h b/base/include/parcel.h index 3ce1b4d8ea82c67e1b326cd90cf39cace5700b56..89ac76c3ad181a228d57f56bce7f749febe76b3c 100644 --- a/base/include/parcel.h +++ b/base/include/parcel.h @@ -16,9 +16,10 @@ /** * @file parcel.h * - * @brief Provide classes for data container implemented in c_utils. + * @brief Provides classes for the data container implemented in c_utils. * - * Including class Parcel, Parcelable and related memory Allocator. + * The Parcel and Parcelable classes and the related memory + * allocator are provided. */ #ifndef OHOS_UTILS_PARCEL_H @@ -35,10 +36,10 @@ namespace OHOS { class Parcel; /** - * @brief Interface for class whose Instance can be written into a Parcel. + * @brief Defines a class for which the instance can be written into a parcel. * - * @note If this object is remote, its position intends to - * use in kernel data transaction. + * @note If this object is remote, its position will be used in + * kernel data transaction. */ class Parcelable : public virtual RefBase { public: @@ -46,39 +47,41 @@ public: Parcelable(); /** - * @brief Construct a new Parcelable object. + * @brief Creates a `Parcelable` object. * - * @param asRemote Specifies whether this object is remote. + * @param asRemote Specifies whether the object is remote. */ explicit Parcelable(bool asRemote); /** - * @brief Write a parcelable object to the given parcel. + * @brief Writes a `Parcelable` object into a parcel. * - * @param parcel Target parcel to write to. - * @return Return true being written on success or false if any error occur. - * @note If this object is remote, its position will be saved in the parcel. - * @note A static Unmarshalling function must also be implemented, so that - * you can get data from the given parcel into this parcelable object. + * @param parcel Indicates the parcel. + * @return Returns `true` if the operation is successful; returns `false` + * otherwise. + * @note If the `Parcelable` object is remote, its position will be saved + * in the parcel. + * @note You must implement a static Unmarshalling function to + * fetch data from the given parcel into this `Parcelable` object. * See `static TestParcelable *Unmarshalling(Parcel &parcel)` as an example. */ virtual bool Marshalling(Parcel &parcel) const = 0; /** - * @brief Enum flag to describe behaviors of the Parcelable object. + * @brief Enumerates the behavior types of a `Parcelable` object. * - * @var IPC Indicate the object can be used in IPC. - * @var RPC Indicate the object can be used in RPC. - * @var HOLD_OBJECT Indicate the object will ensure - * alive during data transaction. + * @var IPC Indicate an object that can be used in IPC. + * @var RPC Indicate an object that can be used in RPC. + * @var HOLD_OBJECT Indicate an object that will be always alive + * during data transaction. * */ enum BehaviorFlag { IPC = 0x01, RPC = 0x02, HOLD_OBJECT = 0x10 }; /** - * @brief Enable specified behavior. + * @brief Enables the specified behavior. * - * @param b Specific flag value. + * @param b Indicates the behavior. * @see BehaviorFlag. */ inline void SetBehavior(BehaviorFlag b) const @@ -87,9 +90,10 @@ public: } /** - * @brief Disable specified behavior. + * @brief Disables the specified behavior. * - * @param b Specific flag value. See BehaviorFlag. + * @param b Indicates the behavior. + * @see BehaviorFlag. */ inline void ClearBehavior(BehaviorFlag b) const { @@ -97,9 +101,12 @@ public: } /** - * @brief Check whether specified behavior is enabled. + * @brief Checks whether the specified behavior is enabled. * - * @param b Specific flag value. + * @param b Indicates the behavior. + + * @return Returns `true` if the behavior is enabled; returns `false` + * otherwise. * @see BehaviorFlag. */ inline bool TestBehavior(BehaviorFlag b) const @@ -108,12 +115,12 @@ public: } public: - bool asRemote_; // if the object is remote - mutable uint8_t behavior_; // value of flag of behaviors + bool asRemote_; // If the object is remote. + mutable uint8_t behavior_; // Behavior of the object. }; /** - * @brief Interface for memory allocator of the data in Parcel. + * @brief Defines a memory allocator for data in `Parcel`. */ class Allocator { public: @@ -127,144 +134,150 @@ public: }; /** - * @brief Default implement of Allocator. + * @brief Provides the default implementation for a memory allocator. * - * @note Allocator defined by user for a parcel need be specified manually. + * @note A non-default allocator for a parcel must be specified manually. */ class DefaultAllocator : public Allocator { public: /** - * @brief Use `malloc()` to allocate memory for a parcel. + * @brief Allocates memory for this parcel. * - * @param size Size of desired memory region. - * @return Void-type pointer to the memory region. + * @param size Indicates the size of the memory to allocate. + * @return Returns the void pointer to the memory region. */ void *Alloc(size_t size) override; /** - * @brief Use `free()` to deallocate memory for a parcel. + * @brief Deallocates memory for this parcel. * - * @param data Void-type pointer to the memory region. + * @param data Indicates the void pointer to the memory region. */ void Dealloc(void *data) override; private: /** - * @brief Use `realloc()` to reallocate memory for a parcel. + * @brief Reallocates memory for this parcel. * - * @param data Void-type pointer to the existed memory region. - * @param newSize New desired size of memory region. - * @return Void-type pointer to the new memory region. + * @param data Indicates the void pointer to the existing memory region. + * @param newSize Indicates the size of the memory to reallocate. + * @return Returns the void pointer to the new memory region. */ void *Realloc(void *data, size_t newSize) override; }; /** - * @brief A data/message container. + * @brief Provides a data/message container. * - * Contains interfaces for writing and reading data of various types, - * including primitives, Parcelable objects etc. + * This class provides methods for writing and reading data of various types, + * including primitives and parcelable objects. * - * @note Usually used in IPC, RPC. + * @note This class is usually used in IPC and RPC scenarios. */ class Parcel { public: Parcel(); /** - * @brief Construct a new Parcel object with specified Allocator. + * @brief Creates a `Parcel` object with the specified memory allocator. * - * @param allocator Specified Allocator. + * @param allocator Indicates the memory allocator. */ explicit Parcel(Allocator *allocator); virtual ~Parcel(); /** - * @brief Get total size of existed data in this parcel. + * @brief Obtains the total size of existing data in this parcel. * - * @return Value of the size in bytes. + * @return Returns the size, in bytes. */ size_t GetDataSize() const; /** - * @brief Get the pointer to the beginning of data in this parcel. + * @brief Obtains the pointer to the beginning of data in this parcel. * - * @return `uintptr_t`-type pointer. + * @return Returns a pointer of the `uintptr_t` type. */ uintptr_t GetData() const; /** - * @brief Get position of every object written in this parcel. + * @brief Obtains the position (offset) of every object written + * in this parcel. * - * @return `binder_size_t`-type pointer to + * @return Returns a pointer of the `binder_size_t` type to * the first slot of the position array. * @see flat_obj.h */ binder_size_t GetObjectOffsets() const; /** - * @brief Get total size of all of the current positions. + * @brief Obtains the size of the position array. * - * @return Value of the size in bytes. + * @return Returns the size, in bytes. */ size_t GetOffsetsSize() const; /** - * @brief Get total availiable bytes to write to this parcel. + * @brief Obtains the total number of available bytes to write + * into this parcel. * - * @return Amount of the availiable bytes. + * @return Returns the number of available bytes. */ size_t GetWritableBytes() const; /** - * @brief Get total availiable bytes to read from this parcel. + * @brief Obtains the total number of available bytes to read + * from this parcel. * - * @return Amount of the availiable bytes. + * @return Returns the number of available bytes. */ size_t GetReadableBytes() const; /** - * @brief Get total capacity of this parcel, - * i.e. size of current data region in parcel. + * @brief Obtains the total capacity of this parcel, that is, the size of + * the current data region in the parcel. * - * @return Value of the capacity in bytes. + * @return Returns the capacity, in bytes. */ size_t GetDataCapacity() const; /** - * @brief Get maximum capacity of this parcel. + * @brief Obtains the maximum capacity of this parcel. * - * @return Value of the capacity in bytes. + * @return Returns the capacity, in bytes. */ size_t GetMaxCapacity() const; /** - * @brief Set capacity of this parcel, - * i.e. size of current data region in parcel. + * @brief Sets the capacity for this parcel, that is, the size of the + * current data region in the parcel. * - * @param newCapacity Desired new capacity. - * @return Return True on success, or false if any error occur. - * @note Corresponding Allocator will try to reallocate - * the data region with new capacity. + * @param newCapacity Indicates the capacity to set. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. + * @note The memory allocator will try to reallocate the data region + * with the new capacity. * */ bool SetDataCapacity(size_t newCapacity); /** - * @brief Set total size of existed data in this parcel. + * @brief Sets the total size of existing data in this parcel. * - * @param dataSize Desired value of size in bytes. - * @return Return True on success, or false if any error occur. - * @note Avoid using it independently, otherwise it may not - * represents the correct size of existed data. + * @param dataSize Indicates the size, in bytes. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. + * @note Do not call this function independently; otherwise, it may fail to + * return the correct data size. */ bool SetDataSize(size_t dataSize); /** - * @brief Set maximux capacity of this parcel. + * @brief Sets the maximum capacity for this parcel. * - * @param maxCapacity Desired value of maximum capacity. - * @return Return True on success, or false if any error occur. + * @param maxCapacity Indicates the maximum capacity to set. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool SetMaxCapacity(size_t maxCapacity); @@ -283,150 +296,166 @@ public: bool WritePointer(uintptr_t value); /** - * @brief Write a data region(buffer) to this parcel. + * @brief Writes a data region (buffer) to this parcel. * - * @param data Void-type pointer to the buffer. - * @param size Size of the buffer to be written. - * @return Return True on success, or false if any error occur. + * @param data Indicates the void pointer to the buffer. + * @param size Indicates the size of the buffer. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteBuffer(const void *data, size_t size); /** - * @brief Write a data region(buffer) to this parcel - * in alignment and with terminator replaced. + * @brief Writes a data region (buffer) to this parcel in alignment + * and with the terminator replaced. * - * @param data Void-type pointer to the buffer. - * @param size Size of the buffer to be written. - * @param typeSize Size of the terminator. - * @return Return True on success, or false if any error occur. + * @param data Indicates the void pointer to the buffer. + * @param size Indicates the size of the buffer. + * @param typeSize Indicates the size of the terminator. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. * @note The last several bytes specified by `typeSize` of the aligned data - * will be deemed as a terminator, and then will be replaced by - * '0b00000000'. + * will be treated as a terminator and replaced by '0b00000000'. */ bool WriteBufferAddTerminator(const void *data, size_t size, size_t typeSize); /** - * @brief Write a data region(buffer) to this parcel without padding. + * @brief Writes a data region (buffer) to this parcel. * - * @param data Void-type pointer to the buffer. - * @param size Size of the buffer to be written. - * @return Return True on success, or false if any error occur. + * Currently, this function provides the same capability as `WriteBuffer()`. + * + * @param data Indicates the void pointer to the buffer. + * @param size Indicates the size of the buffer. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteUnpadBuffer(const void *data, size_t size); /** - * @brief Write a C-style string to this parcel. + * @brief Writes a C-style string to this parcel. * - * Default terminator `\0` of C-style string will also write. + * The default terminator `\0` of the C-style string will also be written. * - * @param value A C-style string, i.e. char-type pointer. - * @return Return True on success, or false if any error occur. + * @param value Indicates a pointer of the char type to a C-style string. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteCString(const char *value); /** - * @brief Write a C++ string(`std::u16string`) to this parcel. + * @brief Writes a C++ string (`std::string`) to this parcel. * - * The exact length of the string will write first, then the string itself - * with an appended terminator `\0` will write. + * The exact length of the string will be written first, and then the string + * itself with the appended terminator `\0` will be written. * - * @param value An `std::string` object passed by reference. - * @return Return True on success, or false if any error occur. + * @param value Indicates the reference to an `std::string` object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteString(const std::string &value); /** - * @brief Write a C++ UTF-16 encoded string(`std::string`) to this parcel. + * @brief Writes a C++ UTF-16 encoded string (`std::u16string`) + * to this parcel. * - * The exact length of the string will write first, then the string itself - * with an appended terminator `\0` will write. + * The exact length of the string will be written first, and then the string + * itself with the appended terminator `\0` will be written. * - * @param value An `std::u16string` object passed by reference. - * @return Return True on success, or false if any error occur. + * @param value Indicates the reference to an `std::u16string` object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteString16(const std::u16string &value); /** - * @brief Write a UTF-16 encoded string - * with specified length to this parcel. + * @brief Writes a UTF-16 encoded string with the specified length + * to this parcel. * - * An `std::u16string` object will be constructed by input `char16_t*` + * An `std::u16string` object will be constructed based on the `char16_t*` * pointer and the length `len` first. Then the input length and the string - * data in `u16string` object with an appended terminator `\0` will write. + * data in the `u16string` object with the appended terminator `\0` will + * be written. * - * @param value Pointer to the UTF-16 encoded string. - * @param len Exact length of the input string. - * @return Return True on success, or false if any error occur. + * @param value Indicates the pointer to a UTF-16 encoded string. + * @param len Indicates the exact length of the input string. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteString16WithLength(const char16_t *value, size_t len); /** - * @brief Write a UTF-8 encoded string - * with specified length to this parcel. + * @brief Writes a UTF-8 encoded string with the specified length + * to this parcel. * - * The input length `len` and the string data - * with an appended terminator `\0` will write. + * The input length `len` and the string itself + * with the appended terminator `\0` will be written. * - * @param value Pointer to the UTF-8 encoded string. - * @param len Exact length of the input string. - * @return Return True on success, or false if any error occur. + * @param value Indicates the pointer to a UTF-8 encoded string. + * @param len Indicates the exact length of the input string. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteString8WithLength(const char *value, size_t len); /** - * @brief Write a Parcelable object to this parcel. + * @brief Writes a `Parcelable` object to this parcel. * - * Remote object will be written by `WriteRemoteObject(const Parcelable *)`. - * Non-remote object will be written by its own - * `Marshalling(Parcel &parcel)`. + * Call `WriteRemoteObject(const Parcelable *)` to write a remote object. + * Call `Marshalling(Parcel &parcel)` to write a non-remote object. * - * @param object Pointer to the input Parcelable object. - * @return Return True on success, or false if any error occur. - * @note '0' of `Int32_t` will write if input pointer is `nullptr`. + * @param object Indicates the pointer to a `Parcelable` object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. + * @note The value '0' of `Int32_t` will be written if a null pointer + * is passed in. */ bool WriteParcelable(const Parcelable *object); /** - * @brief Write a Parcelable object to this parcel, - * and enable its behavior of `HOLD_OBJECT`. + * @brief Writes a `Parcelable` object to this parcel, and enables its + * behavior of `HOLD_OBJECT`. * - * @param object Smart pointer to the input parcelable object. - * @return Return True on success, or false if any error occur. + * @param object Indicates the smart pointer to a `Parcelable` object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteStrongParcelable(const sptr &object); /** - * @brief Write a remote object to this parcel. + * @brief Writes a remote object to this parcel. * - * @param object Pointer to a remote object. - * @return Return True on success, or false if any error occur. - * @note If `HOLD_OBJECT` is enabled for the input object, it will stay + * @param object Indicates the pointer to a remote object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. + * @note If `HOLD_OBJECT` is enabled for the remote object, it will stay * alive as long as this parcel is alive. * */ bool WriteRemoteObject(const Parcelable *object); /** - * @brief Write an object to this parcel. + * @brief Writes an object to this parcel. * - * Use its own `Marshalling(Parcel &parcel)` when `nullptr` as input, - * otherwise use `WriteRemoteObject(const Parcelable *)`. + * Use its own `Marshalling(Parcel &parcel)` when a null pointer is passed + * in; in other scenarios, use `WriteRemoteObject(const Parcelable *)`. * - * @tparam T Specific class type of the input object. - * @param object Smart pointer to the input object. - * @return Return True on success, or false if any error occur. + * @tparam T Indicates the class type of the object. + * @param object Indicates the smart pointer to the object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ template bool WriteObject(const sptr &object); /** - * @brief Parse input data by this parcel. + * @brief Parses input data by this parcel. * - * @param data Pointer to input data. - * @param size Size of input data(Bytes). - * @return Return True on success, or false if any error occur. - * @note Only read operation from this parcel is permitted after successful - * calling this method. + * @param data Indicates the pointer to input data. + * @param size Indicates the size of the input data, in bytes. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. + * @note Only the read operation from this parcel is allowed after + * successful calling of this method. */ bool ParseFrom(uintptr_t data, size_t size); @@ -477,200 +506,212 @@ public: bool ReadDouble(double &value); /** - * @brief Read a block of data(buffer data) from this parcel. + * @brief Reads a block of data (buffer data) from this parcel. * - * @param length Size of the buffer(Bytes). - * @return A `uint8_t` pointer to the buffer. + * @param length Indicates the size of the buffer, in bytes. + * @return Returns a pointer of the `uint8_t` type to the buffer. */ const uint8_t *ReadBuffer(size_t length); /** - * @brief Read a block of data(buffer data) without padding(alignment) from - * this parcel. + * @brief Reads a block of data (buffer data) without padding (alignment) + * from this parcel. * - * This method will read the effective data whose length specified by - * `length` and discard bytes for padding. + * This method will read the effective data with the specified + * `length` and discard the bytes used for padding. * - * @param length Effective size of the buffer(Bytes). - * @return A `uint8_t` pointer to the buffer. + * @param length Indicates the effective size of the buffer, in bytes. + * @return Returns a pointer of the `uint8_t` type to the buffer. * */ const uint8_t *ReadUnpadBuffer(size_t length); /** - * @brief Skip the next several bytes specifed by `bytes` in read process. + * @brief Skips the next several bytes specified by `bytes` in the read + * operation. * - * @param bytes Skipped number of bytes. + * @param bytes Indicates the number of bytes to skip. */ void SkipBytes(size_t bytes); /** - * @brief Read a C-style string from this parcel. + * @brief Reads a C-style string from this parcel. * - * @return A C-style string, which is represented by a `char`-type pointer. + * @return Returns a pointer of the `char` type to the C-style string. */ const char *ReadCString(); /** - * @brief Read a C++ string(`std::string`) object from this parcel. + * @brief Reads a C++ string (`std::string`) object from this parcel. * - * @return An `std::string` object. + * @return Returns a pointer of the `std::string` type to the C-style + * string. */ const std::string ReadString(); /** - * @brief Read a C++ string(`std::string`) object from this parcel to input - * object. + * @brief Reads a C++ string (`std::string`) object from this parcel to + * an object. * - * @param value Target receiver `std::string` object. - * @return Return True on success, or false if any error occur. + * @param value Indicates the `std::string` object to hold the data read. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool ReadString(std::string &value); /** - * @brief Read a C++ UTF-16 encoded string(`std::string`) object from this - * parcel. + * @brief Reads a C++ UTF-16 encoded string (`std::u16string`) object + * from this parcel. * - * @return An `std::u16string` object. + * @return Returns a pointer of the `std::u16string` type to the C-style + * string. */ const std::u16string ReadString16(); /** - * @brief Read a C++ UTF-16 string(`std::u16string`) object from this - * parcel to input object. + * @brief Reads a C++ UTF-16 string (`std::u16string`) object from this + * parcel to an object. * - * @param value Target receiver `std::string` object. - * @return Return True on success, or false if any error occur. + * @param value Indicates the `std::u16string` object to hold the data read. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool ReadString16(std::u16string &value); /** - * @brief Read a C++ UTF-16 string(`std::u16string`) object and its length + * @brief Reads a C++ UTF-16 string (`std::u16string`) object and its length * from this parcel. * - * @param len `int32_t`-type variable passed by reference to receive the - * length. - * @return An output `std::u16string` object. + * @param len Indicates the reference to a variable of the `int32_t` type + * to receive the length. + * @return Returns an `std::u16string` object. */ const std::u16string ReadString16WithLength(int32_t &len); /** - * @brief Read a C++ string(`std::string`) object and its length from this - * parcel. + * @brief Reads a C++ string (`std::string`) object and its length from + * this parcel. * - * @param len `int32_t`-type variable passed by reference to receive the - * length. - * @return An output `std::u8string` object. + * @param len Indicates the reference to a variable of the `int32_t` type + * to receive the length. + * @return Returns an `std::string` object. */ const std::string ReadString8WithLength(int32_t &len); /** - * @brief Set the read cursor to specified position. + * @brief Sets the read cursor to the specified position. * - * @param newPosition Specified position represented by offsets relative to - * the beginning of the data region. - * @return Return True on success, or false if any error occur. + * @param newPosition Indicates the position, represented by the offset + * (in bytes) from the beginning of the data region. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool RewindRead(size_t newPosition); /** - * @brief Set the write cursor to specified position. + * @brief Sets the write cursor to the specified position. * - * @param offsets Specified position represented by offsets(Bytes) relative - * to the beginning of the data region. - * @return Return True on success, or false if any error occur. + * @param offsets Indicates the position, represented by the offset + * (in bytes) from the beginning of the data region. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool RewindWrite(size_t offsets); /** - * @brief Get current position of read cursor. + * @brief Obtains the current position of the read cursor. * - * @return Position represented by offsets(Bytes) relative to the beginning - * of the data region. + * @return Returns the position, represented by the offset (in bytes) + * from the beginning of the data region. */ size_t GetReadPosition(); /** - * @brief Get current position of write cursor. + * @brief Obtains the current position of the write cursor. * - * @return Position represented by offsets(Bytes) relative to the beginning - * of the data region. + * @return Returns the position, represented by the offset (in bytes) + * from the beginning of the data region. */ size_t GetWritePosition(); /** - * @brief Read a Parcelable(and its subclass) object from this parcel. + * @brief Reads a `Parcelable` object and its child class objects + * from this parcel. * - * @tparam T Specific class type of the output object. - * @return Object of specific class. - * @note `nullptr` will return if a '0' is read. + * @tparam T Indicates the class type of the output object. + * @return Returns the object read. + * @note A null pointer will be returned if '0' is read. */ template T *ReadParcelable(); /** - * @brief Read a Parcelable object from this parcel, and manage it by a + * @brief Reads a `Parcelable` object from this parcel and manages it by a * smart pointer. * - * @tparam T Specific class type of the output object. - * @return Object managed by a smart pointer. - * @note `nullptr` will return if a '0' is read. + * @tparam T Indicates the class type of the output object. + * @return Returns the object managed by a smart pointer. + * @note A null pointer will be returned if '0' is read. */ template sptr ReadStrongParcelable(); /** - * @brief Check if it is valid to read an object from current cursor. + * @brief Checks whether it is valid to read an object from the current + * cursor. * - * @return Return true if valid, otherwise return false. + * @return Returns `true` if valid; returns `false` otherwise. */ bool CheckOffsets(); /** - * @brief Read an object from this parcel. + * @brief Reads an object from this parcel. * - * `CheckOffsets()` will call first to check whether it is valid to read an + * Call `CheckOffsets()` first to check whether it is valid to read an * object. * - * @tparam T Specific class type of the output object. - * @return A smart pointer to the object. - * @note `nullptr` will return if `CheckOffsets()` fail. + * @tparam T Indicates the class type of the output object. + * @return Returns the smart pointer to the object. + * @note A null pointer will be returned if `CheckOffsets()` fails + * to be called. */ template sptr ReadObject(); /** - * @brief Set the Allocator object of this parcel. + * @brief Sets a memory allocator for this parcel. * - * New Allocator will reallocate the data region to which has been written. + * The new allocator will reallocate the data region that has been written. * - * @param allocator Specified Allocator object. - * @return Return True on success, or false if any error occur. + * @param allocator Indicates the pointer to an `Allocator` object. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool SetAllocator(Allocator *allocator); /** - * @brief Record an array of offsets of the object. + * @brief Records an array of positions of this parcel. * - * @param offsets A pointer to the input array. - * @param offsetSize Size of the input array. - * @note It will return directly if fail. + * @param offsets Indicates the pointer to the position array. + * @param offsetSize Indicates the size of the position array. + * @note The method returns directly if the call fail. */ void InjectOffsets(binder_size_t offsets, size_t offsetSize); /** - * @brief Deallocate the data region, and reset this parcel. + * @brief Deallocates the data region and resets this parcel. */ void FlushBuffer(); /** - * @brief Write an `std::vector` object to this parcel. + * @brief Writes an `std::vector` object to this parcel. * - * @tparam T1 Specific class type for input vector. - * @tparam T2 Specific class type for write method of this parcel. - * @param val Input vector object passed by reference. - * @param Write Specific `Parcel::Write(T2 value)` method. - * @return Return True on success, or false if any error occur. + * @tparam T1 Indicates the class type for the vector. + * @tparam T2 Indicates the class type for the write method of this parcel. + * @param val Indicates the reference to the vector. + * @param Write Indicates the `Parcel::Write(T2 value)` method. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ template bool WriteVector(const std::vector &val, bool (Parcel::*Write)(T2)); @@ -689,13 +730,14 @@ public: bool WriteString16Vector(const std::vector &val); /** - * @brief Read an `std::vector` object from this parcel. + * @brief Reads an `std::vector` object from this parcel. * - * @tparam T1 Specific class type for output vector. - * @tparam T2 Specific class type for read method of this parcel. - * @param val Pointer to the output vector object. - * @param Write Specific `Parcel::Read(T2 value)` method. - * @return Return True on success, or false if any error occur. + * @tparam T1 Indicates the class type for the vector. + * @tparam T2 Indicates the class type for the read method of this parcel. + * @param val Indicates the pointer to the vector. + * @param Write Indicates the `Parcel::Read(T2 value)` method. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ template bool ReadVector(std::vector *val, bool (Parcel::*Read)(T &)); @@ -728,21 +770,23 @@ public: protected: /** - * @brief Record position of the written object, which are represented by - * offset from the beginning of the data region. + * @brief Records the position of the written object, which is represented + * by the offset from the beginning of the data region. * - * @param offset Specific position. - * @return Return True on success, or false if any error occur. + * @param offset Indicates the position. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool WriteObjectOffset(binder_size_t offset); /** - * @brief Ensure number of the written objects is lower than the capacity of - * objects. + * @brief Ensures that the number of written objects is less than + * the capacity of objects. * - * If it is full, the capacity will be expanded. + * If the data region is full, the capacity will be expanded. * - * @return Return True on success, or false if any error occur. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool EnsureObjectsCapacity(); @@ -821,7 +865,7 @@ T *Parcel::ReadParcelable() return T::Unmarshalling(*this); } -// Read data from the given parcel into this parcelable object, return sptr. +// Read data from the given parcel into this parcelable object, and return sptr. template sptr Parcel::ReadStrongParcelable() { diff --git a/base/include/pubdef.h b/base/include/pubdef.h index 912010347b6f3ae32a7a87abb0c7a4f8302369a8..ef3ce615b50be8668599d404fc1f32ec45ee0885 100644 --- a/base/include/pubdef.h +++ b/base/include/pubdef.h @@ -17,7 +17,7 @@ * @file pubdef.h * * @brief The file contains macro definitions for some basic functions - * in c_utils, such as unit conversion, return maximum value, etc. + * in c_utils, for example, unit conversion and space freeup. */ #ifndef UTILS_BASE_PUBDEF_H @@ -39,7 +39,7 @@ namespace OHOS { // Used for unit conversion from second to hour #define SECOND_TO_HOUR(s) ((s) / 3600) -// Used to return the size of array +// Used to return the array size #define ARRAY_SIZE(a) (sizeof((a)) / sizeof((a[0]))) // Used to free the space pointed by pointer p @@ -52,11 +52,11 @@ namespace OHOS { // Used to return the minimum of two numbers #define MIN(x, y) (((x) < (y)) ? (x) : (y)) -// Used to determine whether a float number 'x' is 0 +// Used to determine whether float number 'x' is 0 #define EPS (1e-8) #define EQUAL_TO_ZERO(x) (fabs(x) <= (EPS)) -// Used to retry syscalls that can return EINTR. +// Used to attempt a retry when the syscall error code is EINTR #ifndef TEMP_FAILURE_RETRY #define TEMP_FAILURE_RETRY(exp) \ ({ \ diff --git a/base/include/refbase.h b/base/include/refbase.h index 66db564dcd071aa0f16fb98c750e80d573ab4fe6..a49bfccf8ab7a829579e648371c73f4423f84484 100644 --- a/base/include/refbase.h +++ b/base/include/refbase.h @@ -22,12 +22,12 @@ /** * @defgroup SmartPointer * @{ - * @brief Smart Pointer are pointer-like classes. + * @brief SmartPointer is a pointer-like class. * - * They simulates a pointer while providing added features, - * such as automatic memory management.\n - * Automatic memory management is mainly about deallocating - * the related memory correctly when an object beyonds its life cycle. + * This class simulates a pointer while providing + * enhanced features, such as automatic memory management.\n + * Automatic memory management helps to deallocate + * memory resources correctly when an object's life time expires. */ #ifndef UTILS_BASE_REFBASE_H @@ -42,7 +42,7 @@ namespace OHOS { /** * @ingroup SmartPointer - * @brief A value indicates no strong references exist ever. + * @brief A value indicates no strong references ever. */ #define INITIAL_PRIMARY_VALUE (1 << 28) @@ -54,25 +54,24 @@ class RefTracker; /** * @ingroup SmartPointer - * @brief Reference counter. A class records two kinds of count of references to - * the corresponding RefBase object, and a count of references to the RefCounter - * itself. + * @brief Reference counter class. Such a class records two kinds + * of references to the corresponding RefBase object and one kind + * of references to the RefCounter object itself. * * There are two different references for a single object.\n - * Strong Reference holds a reference directly point to the object. - * Objects which are strong referenced ought to be alive/existed - * as long as this strong reference exists, thus the reference - * is still valid.\n - * Weak Reference holds a reference indirectly point to the object. - * Objects which are weak referenced are not guaranteed to be alive/existed + * A strong reference holds the reference directly pointing to the object, + * and the object should be alive as long as the strong reference exists.\n + * A weak reference holds a reference indirectly pointing to the object, + * and the object is not always alive/existent * even if the weak reference exists. - * @note Descriptions above are valid only when smart pointers + * @note The preceding descriptions are valid only when smart pointers * are properly used. */ class RefCounter { public: /** - * @brief Callback function to destroy the corresponding RefBase object. + * @brief Callback function used to destroy the corresponding + * RefBase object. */ using RefPtrCallback = std::function; friend class RefBase; @@ -86,157 +85,159 @@ public: virtual ~RefCounter(); /** - * @brief Set the callback function. + * @brief Sets the callback function. * - * @param callback A function to be set to delete + * @param callback Callback function used to delete * the corresponding RefBase object. */ void SetCallback(const RefPtrCallback& callback); /** - * @brief Remove the current callback function. Set it to a `nullptr`. + * @brief Removes the current callback function by setting it to a `nullptr`. */ void RemoveCallback(); /** - * @brief Get reference count to the RefCounter object. + * @brief Gets the count of references to the RefCounter object. * - * @return Value of the related count. + * @return Count of references to the RefCounter object. */ int GetRefCount(); /** - * @brief Increment the reference count to the RefCounter object by 1. + * @brief Increments the count of references to the RefCounter object by 1. */ void IncRefCount(); /** - * @brief Decrement the reference count to the RefCounter object by 1. + * @brief Decrements the count of references to the RefCounter object by 1. * * Once the count reaches 0 after being decremented, - * it will call `delete this` to deallocate this RefCounter object. + * `delete this` will be called to deallocate this RefCounter object. */ void DecRefCount(); /** - * @brief Check if pointer to the call back function is a `nullptr`. + * @brief Checks if the pointer to the callback function is a `nullptr`. * - * @return Return true if it is not a `nullptr`. + * @return `true` if the callback function is a `nullptr`; + * `false` otherwise. */ bool IsRefPtrValid(); /** - * @brief Increment the strong reference count to the + * @brief Increments the count of strong references to the * corresponding RefBase object by 1. * - * @return Original (before increment) value of the count. + * @return Original count before increment. */ int IncStrongRefCount(const void *objectId); /** - * @brief Decrement the strong reference count to the + * @brief Decrements the count of strong references to the * corresponding RefBase object by 1. * - * @return Original (before decrement) value of the count. - * @note If the strong reference has never existed, - * decrement will cause no effection. + * @return Original count before decrement. + * @note If the strong reference never exists, + * decrement will be ineffective. */ int DecStrongRefCount(const void *objectId); /** - * @brief Get the strong reference count to the + * @brief Gets the count of strong references to the * corresponding RefBase object. * - * @return Value of the related count. + * @return Count of strong references. */ int GetStrongRefCount(); /** - * @brief Increment the weak reference count to the + * @brief Increments the count weak references to the * corresponding RefBase object by 1. * - * @return Original (before increment) value of the count. + * @return Original count before increment. */ int IncWeakRefCount(const void *objectId); /** - * @brief Decrement the weak reference count to the + * @brief Decrements the count of weak references to the * corresponding RefBase object by 1. * * @return Original (before decrement) value of atomicWeak_. - * @note When the count reaches 0 after being decremented, the + * @note If the count reaches 0 after being decremented, the * corresponding RefBase object with no strong reference ever, - * or the object with strong reference count of 0 but has not been - * deallocated due to its extended 'life time', will be deallocated. + * or the RefBase object with 0 strong reference but an extended + * 'life time', will be deallocated. */ int DecWeakRefCount(const void *objectId); /** - * @brief Get the weak reference count to the + * @brief Gets the count of weak references to the * corresponding RefBase object. * - * @return Value of the related count. + * @return Count of weak references. */ int GetWeakRefCount(); /** - * @brief Increment the times of attempts to increment. + * @brief Sets the number of attempts to increment. */ void SetAttemptAcquire(); /** - * @brief Check if the times of attempts greater than 0. + * @brief Check if the number of attempts is greater than 0. * - * @return Return true if the times is greater than 0. + * @return `true` if the number of attempts is greater than 0; + * `false` otherwise. */ bool IsAttemptAcquireSet(); /** - * @brief Clear the times of attempts to increment. + * @brief Clears number of attempts to increment. */ void ClearAttemptAcquire(); /** - * @brief Attempt to increment the strong reference count to the + * @brief Attempts to increment the count of strong references to the * corresponding RefBase object by 1. * * @param outCount If the attempt success, the original value * (before increment) of the count will be stored here. - * @return Return true if the attempt success. + * @return `true` if the attempt is successful; `false` otherwise. */ bool AttemptIncStrongRef(const void *objectId, int &outCount); // Only for IPC use. /** - * @brief Attempt to increment the strong reference count to - * the corresponding RefBase object by 1(Simplified). + * @brief Attempts to increment the count of strong references to the + * the corresponding RefBase object by 1 (simplified). * - * @return Return true if the attempt success. - * @note Ony for IPC use. + * @return `true` if the attempt is successful; `false` otherwise. + * @note Only for IPC use. */ bool AttemptIncStrong(const void *objectId); /** - * @brief Check if the corresponding RefBase object - * own an extended life-time. + * @brief Checks if the corresponding RefBase object + * has an extended life-time. * - * @return Return true if its life-time has been extended. + * @return `true` if success; `false` otherwise. */ bool IsLifeTimeExtended(); /** - * @brief Extend the life-time of corresponding RefBase object. + * @brief Extends the life-time of corresponding RefBase object. * - * It allows the corresponding object keep alive - * even if there exists no strong reference to it. - * @note Corresponding object will be deallocated - * when related weak reference count also reach 0. + * This allows the corresponding object keep alive + * even if there is no strong reference. + * @note The RefBase object will be deallocated + * if the count of weak references also reaches 0. */ void ExtendObjectLifetime(); #if ((defined DEBUG_REFBASE) && (!defined TRACK_ALL)) /** - * @brief Enable the ability of tracking. This is a debug feature. + * @brief Enables tracking. It is applicable to debugging only. */ void EnableTracker(); #endif @@ -245,9 +246,9 @@ private: std::atomic atomicStrong_; // = (num of sptr) or Initial-value std::atomic atomicWeak_; // = (num of sptr)+(num of WeakRefCounter) std::atomic atomicRefCount_; // = (num of WeakRefCounter) + 1 - std::atomic atomicFlags_; // A life-time extended flag - std::atomic atomicAttempt_; // Times of attempts - RefPtrCallback callback_ = nullptr; // A callback function to deallocate the corresponding RefBase object + std::atomic atomicFlags_; // Life-time extended flag + std::atomic atomicAttempt_; // Number of attempts + RefPtrCallback callback_ = nullptr; // Callback function to deallocate the corresponding RefBase object static constexpr unsigned int FLAG_EXTEND_LIFE_TIME = 0x00000002; // Extended life-time bit to be set via logic-OR #ifdef DEBUG_REFBASE #ifdef TRACK_ALL @@ -271,17 +272,16 @@ private: * @brief An intermediate class to represent the weak reference * to the correspond RefBase object. * - * A WeakRefCounter object can be held by multiple wptr objects.\n - * It holds references to the corresponding RefBase and RefCounter object. - * Those two references will be set as `nullptr`s, when the weak referenced - * target and its RefCounter object has been deallocated. Thus WeakRefCounter - * object can still alive even if the target refereneced by this object - * is vanished. + * A WeakRefCounter object can be shared by multiple wptr objects.\n + * It holds the references to the corresponding RefBase and RefCounter object. + * Those two references will be set as `nullptr` when the weak referenced + * target and its RefCounter object are deallocated. The WeakRefCounter + * object can remain alive even if the referenced target is deallocated. */ class WeakRefCounter { public: /** - * @brief Construct a new Weak Ref Counter object. + * @brief Constructs a WeakRefCounter object. * * @param counter Pointer to corresponding RefCounter object. * @param cookie Pointer to corresponding RefBase object. @@ -291,27 +291,27 @@ public: virtual ~WeakRefCounter(); /** - * @brief Get current pointer to the corresponding RefBase object. + * @brief Gets the current pointer to the corresponding RefBase object. * * @return A void pointer to the RefBase object. - * If the corresponding object does not alive, a `nullptr` will return. - * @note Void pointer means you should cast it to the real type, since it - * can be kinds of subclasses of RefBase. + * If the corresponding object is not alive, a `nullptr` will be returned. + * @note A void pointer means that you should cast it to the real type, + * since it can be any subclass of RefBase. */ void *GetRefPtr(); /** - * @brief Increment the reference count to this WeakRefCounter object. + * @brief Increments the count of references to this WeakRefCounter object. * - * @note Notice the difference between this count and the weak reference - * count in RefCounter. This value equals to the number of wptrs directly - * referencing this WeakRefCount object. + * @note This count is different from the count of weak references + * in RefCounter. It is equal to the count of wptrs directly + * referenced to this WeakRefCount object. * @see RefCounter */ void IncWeakRefCount(const void *objectId); /** - * @brief Decrement the reference count to this WeakRefCounter object. + * @brief Decrements the count of references to this WeakRefCounter object. * * @note This WeakRefCounter object will be deallocated when this count * reaches 0. @@ -319,35 +319,37 @@ public: void DecWeakRefCount(const void *objectId); /** - * @brief Get the count recorded by this WeakRefCounter object. + * @brief Gets the count recorded by this WeakRefCounter object. * - * @return Value of the count. - * @note This value of count is different from that in RefCounter. + * @return Count recorded by this WeakRefCounter object. + * @note The count is different from that in RefCounter. * @see RefCounter::GetWeakRefCount() */ int GetWeakRefCount() const; /** - * @brief Attempt to increment the strong reference count of - * the corresponding RefBase object(Used in promoting a wptr to a sptr). + * @brief Attempts to increment the count of strong references to + * the corresponding RefBase object (to promote a wptr to a sptr). * - * @return Return `true` after a success increment. + * @return `true` after a success increment. */ bool AttemptIncStrongRef(const void *objectId); private: - std::atomic atomicWeak_; // Count of references to this WeakRefCounter object - // The value equals to the total amount of wptrs which - // reference this WeakRefCounter object - RefCounter *refCounter_ = nullptr; // reference to the RefCounter object of corresponding RefBase Object + std::atomic atomicWeak_; // Count of references to this + // WeakRefCounter object + // The value is equal to the count of wptrs + // that references this WeakRefCounter object. + RefCounter *refCounter_ = nullptr; // Reference to the RefCounter object of + // the corresponding RefBase object void *cookie_ = nullptr; // Pointer to the corresponding RefBase object }; /** * @ingroup SmartPointer - * @brief A base class which can be managed by a smart pointer. + * @brief A base class of subclasses that can be managed by SmartPointer. * - * @note All classes which intend to be managed by smart pointers should be + * @note All classes which intend to be managed by SmartPointer should be * derived from RefBase. */ class RefBase { @@ -357,17 +359,17 @@ public: /** * @brief Copy constructor of RefBase. * - * @note Note that this method will construct a new RefCounter object, - * and bind with it. + * @note This function constructs a new RefCounter object + * and binds it to the RefBase object. */ RefBase(const RefBase &); /** * @brief Copy assignment operator of RefBase. * - * @note This method will unbind the current RefBase object and its - * original RefCounter object, then bind a newly constructed - * RefCounter object. + * @note This function unbinds this RefBase object from the + * original RefCounter object, and then binds it to the + * newly constructed RefCounter object. */ RefBase &operator=(const RefBase &); @@ -379,195 +381,193 @@ public: /** * @brief Move assignment operator of RefBase. * - * @note This method will bind this RefBase object with the RefCounter - * object of the argument `other`, then `other` will unbind the RefCounter - * object.\n No counts operation will be poccessed. + * @note This function binds this RefBase object with the RefCounter + * object of the argument `other`, which will unbind the + * RefCounter object. No counts operation will be processed. */ RefBase &operator=(RefBase &&other) noexcept; virtual ~RefBase(); /** - * @brief A callback method to deallocate this object. + * @brief Callback function to deallocate this object. * - * This method has default implement to simply deallocate this RefBase - * object simply by calling `delete(this)`. + * This function provides the default implementation to deallocate + * this RefBase object by simply calling `delete(this)`. */ virtual void RefPtrCallback(); /** - * @brief Extend life time of the RefBase object. + * @brief Extends the life time of the RefBase object. * * @note The object whose life time has been extended will not be - * deallocated when the the weak reference count reach 0 instead of the - * strong one. + * deallocated if the count of weak references, instead of strong + * references, reaches 0. */ void ExtendObjectLifetime(); /** - * @brief Increment the strong reference count. + * @brief Increments the count of strong references. * - * `OnFirstStrongRef()`, which is an empty method by default, will be - * called when the first strong reference are established.、 + * `OnFirstStrongRef()`, which is an empty function by default, + * will be called when the first strong reference is established. * - * @note It will atomically increment the weak reference count meanwhile. + * @note This function automatically increments the count of weak + * references meanwhile. */ void IncStrongRef(const void *objectId); /** - * @brief Decrement the strong reference count. + * @brief Decrements the count of strong references. * - * This object will be deallocated when the count reaches 0, if it owns a - * normal life time.\n `OnLastStrongRef()`, which is an empty method by - * default, will be called when the last strong reference vanishes. + * If the life time is not extended, this object will be deallocated + * when the count of strong references reaches 0.\n + * `OnLastStrongRef()`, which is an empty function by default, + * will be called when the last strong reference is deleted. */ void DecStrongRef(const void *objectId); /** - * @brief Get the strong reference count. + * @brief Gets the count of strong references. * - * @return Related count value. Return 0 when corresponding RefCounter - * object does not exist. - * @note Only valid when corresponding RefCounter object exists. + * @return Count of strong references. The value is 0 if the + * corresponding RefCounter object does not exist. + * @note This function is valid only when corresponding RefCounter + * object exists. */ int GetSptrRefCount(); /** - * @brief Create weak reference to this RefBase object. - * - * Create a WeakRefCounter object which holds reference to this RefBase - * object and set the reference count. + * @brief Creates a weak reference to this RefBase object. * * @param cookie Void pointer to this RefBase object. * @return Pointer to the newly created WeakRefCounter object. - * @note Avoid using it independently. Use related methods of wptr. + * @note Use this function with related functions of wptr. + * Do not use it independently. */ WeakRefCounter *CreateWeakRef(void *cookie); /** - * @brief Get the pointer to corresponding counter object. + * @brief Gets the pointer to corresponding counter object. * * @return Pointer to the counter object. */ RefCounter *GetRefCounter() const; /** - * @brief Increment the weak reference count. + * @brief Increments the count of weak references. * - * @note Only valid when corresponding RefCounter object exists. + * @note This function is valid only when corresponding RefCounter + * object exists. */ void IncWeakRef(const void *objectId); /** - * @brief Decrement the weak reference count. + * @brief Decrements the count of weak references. * - * @note Only valid when corresponding RefCounter object exists. + * @note This function is valid only when corresponding RefCounter + * object exists. */ void DecWeakRef(const void *objectId); /** - * @brief Get the weak reference count. + * @brief Gets the count of weak references. * - * @return Value of related count. Return 0 when corresponding - * RefCounter object doesn't exist. + * @return Count of weak references. The value is 0 if the corresponding + * RefCounter object does not exist. */ int GetWptrRefCount(); /** - * @brief Attempt to increment the strong reference count. + * @brief Attempts to increment the count of strong references. * - * `OnFirstStrongRef()`, which is an empty method by default, will be - * called when the first strong reference are established. + * `OnFirstStrongRef()`, which is an empty function by default, will be + * called when the first strong reference is established. * - * @return Return true if successfully increment the count. - * @note Note that count of times of attempts will increment by 1 + * @return `true` if the increment is successful; `false` otherwise. + * @note The count of attempts will increment by 1 * after a successful increment. */ bool AttemptAcquire(const void *objectId); /** - * @brief Attempt to increment the strong reference count. + * @brief Attempts to increment the count of strong references. * - * `OnFirstStrongRef()`, which is an empty method by default, will be - * called when the first strong reference are established. - * @return Return true if successfully increment the count. - * @note Used in various copy constructor of sptr in scenario of + * `OnFirstStrongRef()`, which is an empty function by default, will be + * called when the first strong reference is established. + * @return `true` if the increment is successful; `false` otherwise. + * @note Use this function in the copy constructor of sptr in scenario of * interaction between sptr and wptr. Avoid using it independently. */ bool AttemptIncStrongRef(const void *objectId); // Only for IPC use. /** - * @brief Attempt to increment the strong reference count. + * @brief Attempts to increment the count of strong references. * - * @return Return true if successfully increment the count, otherwise - * return false. - * @note Note that times of successful attempts will increment by 1 after - * a successful increment of the related count. - * @note This method is a simplified version of `AttemptAcquire`, but only - * for IPC use. + * @return `true` if the increment is successful; `false` otherwise. + * @note If the operation is successful, the count of successful attempts + * will increment by 1. + * @note This function is a simplified version of `AttemptAcquire`. + * It is only for IPC use. */ bool AttemptIncStrong(const void *objectId); /** - * @brief check if the times of successful attempts of greater than 0. + * @brief Checks if the count of successful attempts is greater than 0. * - * @return Return true if times of successful attempts is greater than 0; - * Return false if it is not greater than 0, or the corresponding - * RefCounter object does not exist. + * @return `true` if the count of successful attempts is greater than 0; + * `false` if the count of successful attempts is not greater than 0 + * or the corresponding RefCounter object does not exist. */ bool IsAttemptAcquireSet(); /** - * @brief Check if the life time of this RefBase object has been extended. + * @brief Checks if the life time of this RefBase object has been extended. * - * @return Return false when have a normal life time, or the corresponding + * @return `true` if the life time of this RefBase object has been extended; + * `false` if the RefBase object has a normal life time or the corresponding * RefCounter object does not exist. */ bool IsExtendLifeTimeSet(); /** - * @brief An event-drive method, which will be automatically called when - * first strong reference comes up. + * @brief Called when the first strong reference is established. * * @note It is an empty function by default. */ virtual void OnFirstStrongRef(const void *); /** - * @brief An event-drive method, which will be automatically called when - * last strong reference eliminates. + * @brief Called when the last strong reference is deleted. * * @note It is an empty function by default. */ virtual void OnLastStrongRef(const void *); /** - * @brief An event-drive method, which will be automatically called when - * last weak reference eliminates. + * @brief Called when the last weak reference is deleted. * * @note It is an empty function by default. */ virtual void OnLastWeakRef(const void *); /** - * @brief An event-drive method, which will be autmatically called when - * use `wptr::Promote()`. + * @brief Called when `wptr::Promote()` is invoked. * - * @note Directly return true by default. - * @return Return true if success, otherwise return false. + * @return `true` if success; `false` otherwise. */ virtual bool OnAttemptPromoted(const void *); /** - * @brief Enable the ability to track RefBase. This function will only be - * implemented if the macro DEBUG_REFBASE is defined and TRACK_ALL is not - * defined. + * @brief Enables tracking of the RefBase object. This function will + * be implemented only if DEBUG_REFBASE, but not TRACK_ALL, is defined. */ void EnableTracker(); private: - RefCounter *refs_ = nullptr; // Pointer to the corresponding reference counter of this RefBase object + RefCounter *refs_ = nullptr; // Pointer to the corresponding reference + // counter of this RefBase object }; template @@ -575,12 +575,13 @@ class wptr; /** * @ingroup SmartPointer - * @brief Strong reference smart pointer to a RefBase(or its subclass) object. + * @brief Strong reference smart pointer to a RefBase object + * (or an object of its subclass). * * It directly reference the RefBase object. * - * @tparam T Specific class type managed by sptr. This class must inherit - * from RefBase. + * @tparam T Specific class type managed by sptr. + * This class must inherit from RefBase. */ template class sptr { @@ -592,15 +593,15 @@ public: ~sptr(); /** - * @brief Constructor with specified object to be managed. + * @brief Constructor with the specified object to be managed. * - * @note Null sptr will be created if `other` is a `nullptr`. + * @note A null sptr will be created if `other` is `nullptr`. * @param other Object to be managed by wptr. */ sptr(T *other); /** - * @brief Copy Constructor for sptr with different managed class type(T). + * @brief Copy constructor for sptr with the managed class type (T). * * @param other Input sptr object. */ @@ -618,12 +619,13 @@ public: * @brief Move assignment operator. * * @param other Input sptr object. - * @note Original strong reference in target sptr object will be removed. + * @note The original strong reference in target sptr object will + * be removed. */ sptr &operator=(sptr &&other); /** - * @brief Copy Constructor for sptr with different managed class type(O). + * @brief Copy Constructor for sptr with the managed class type (O). * * @tparam O Another specific class type managed by `other`. * @param other Input sptr object. @@ -632,16 +634,16 @@ public: sptr(const sptr &other); /** - * @brief Constructor only used in promote process of wptr. + * @brief Constructor used to promote the process of wptr. * * @param p WeakRefCounter object which hold the reference to the * managed object. - * @param force Only used to identify from other constructor. + * @param force Used to distinguish from other constructors. */ inline sptr(WeakRefCounter *p, bool force); /** - * @brief Get the pointer to the managed object. + * @brief Gets the pointer to the managed object. * * @return Pointer of the specific managed class type. */ @@ -651,18 +653,18 @@ public: } /** - * @brief Set the pointer to the managed object. + * @brief Sets the pointer to the managed object. * * @param other Another pointer object to be managed by sptr. - * @note Avoid using independently, otherwise it will - * cause mismatch of reference count and thus memory problems. + * @note Avoid using this function independently. Otherwise, + * a mismatch of the reference count will arise, leading to memory problems. */ inline void ForceSetRefPtr(T *other); /** - * @brief Remove the reference to the managed object held by current sptr. + * @brief Removes the reference to the managed object held by current sptr. * - * @note It will make this sptr a "null sptr". + * @note This function will make this sptr a "null sptr". */ void clear(); @@ -670,8 +672,8 @@ public: * @brief Type conversion operator. * * @return Raw pointer to the managed object. - * @note Sptr object itself will not be converted, only the member raw - * pointer returns. + * @note The sptr object will not be converted. Only the member raw + * pointer will be returned. */ inline operator T *() const { @@ -681,9 +683,9 @@ public: /** * @brief Dereference operator. * - * It will return the object managed by this sptr. + * This function will return the object managed by this sptr. * - * @return Return reference of specific object managed by sptr. + * @return Reference to the specific object managed by sptr. */ inline T &operator*() const { @@ -693,7 +695,8 @@ public: /** * @brief Member selection operator. * - * It will return the specified member of the object managed by this sptr. + * This function will return the specified member of the object + * managed by this sptr. */ inline T *operator->() const { @@ -701,9 +704,10 @@ public: } /** - * @brief Logical-NOT operator. Check if sptr is a "null sptr". + * @brief Logical-NOT operator, which is used to check if + * the sptr is a "null sptr". * - * @return Return true if sptr is a "null sptr". + * @return `true` if sptr is a "null sptr"; `false` otherwise. */ inline bool operator!() const { @@ -711,9 +715,9 @@ public: } /** - * @brief Copy assignment operator with specified object to be managed. + * @brief Copy assignment operator with the specified object to be managed. * - * @note Original reference will be removed, then new reference to the + * @note The original reference will be removed, and a new reference to the * input object will be established. * @param other Another object to be managed by this sptr. */ @@ -721,52 +725,52 @@ public: /** * @brief Copy assignment operator for sptr with - * same managed class type(T). + * the same managed class type (T). * - * @note Original reference will be removed, this sptr will manage the - * same object with the input sptr object. - * @param other Another sptr object with same managed class type(T). + * @note The original reference will be removed, and the same object + * with the input sptr object will be managed by this sptr. + * @param other Another sptr object with the same managed class type (T). */ sptr &operator=(const sptr &other); /** * @brief Copy assignment operator for wptr with - * same managed class type(T). + * the same managed class type (T). * - * @note Original reference will be removed, this sptr will manage the - * same object with the input wptr object. - * @note This may fail, then this sptr will turn to be a "null sptr". - * @param other Another wptr object with same managed class type(T). + * @note The original reference will be removed, and the same object + * with the input wptr object will be managed by this sptr. + * @note If the operation fails, this sptr will turn to be a "null sptr". + * @param other Another wptr object with the same managed class type (T). */ sptr &operator=(const wptr &other); /** * @brief Copy assignment operator for sptr with - * different managed class type(O). + * a different managed class type (O). * - * @note Original reference will be removed, this sptr will manage the - * same object with the input sptr object. - * @note This sptr will interpret the managed object as a type T. - * @param other Another sptr object with different managed class type(O). + * @note The original reference will be removed, and the same object + * with the input sptr object will be managed by this sptr. + * @note This sptr will interpret the managed object as the type (T). + * @param other Another sptr object with a different managed class type (O). */ template sptr &operator=(const sptr &other); /** - * @brief Equal-to operator between sptr and a raw pointer. + * @brief Equal-to operator between the sptr and raw pointer. * * @param other Input raw pointer. - * @return Return true if sptr point to the same object with input - * raw pointer. + * @return `true` if the sptr points to the same object with input + * raw pointer; `false` otherwise. */ bool operator==(const T *other) const; /** - * @brief Not-equal-to operator between sptr and a raw pointer. + * @brief Not-equal-to operator between the sptr and raw pointer. * * @param other Input raw pointer. - * @return Return true if sptr does not point to the same object with input - * raw pointer. + * @return `true` if the sptr does not point to the same object + * with input raw pointer; `false` otherwise. */ inline bool operator!=(const T *other) const { @@ -774,18 +778,20 @@ public: } /** - * @brief Equal-to operator between sptr and a wptr. + * @brief Equal-to operator between the sptr and wptr. * * @param other Input wptr. - * @return Return true if sptr and wptr are managing same object. + * @return `true` if the same object is managed by the sptr and wptr; + * `false` otherwise. */ bool operator==(const wptr &other) const; /** - * @brief Not-equal-to operator between sptr and a wptr. + * @brief Not-equal-to operator between the sptr and wptr. * * @param other Input wptr. - * @return Return true if sptr and wptr are not managing same object. + * @return `true` if different objects are managed by the sptr and wptr; + * `false` otherwise. */ inline bool operator!=(const wptr &other) const { @@ -793,10 +799,11 @@ public: } /** - * @brief Equal-to operator between sptrs. + * @brief Equal-to operator between two sptrs. * * @param other Input sptr. - * @return Return true if two sptrs are managing same object. + * @return `true` if the same object is managed by two sptrs; + * `false` otherwise. */ bool operator==(const sptr &other) const; @@ -804,7 +811,8 @@ public: * @brief Not-equal-to operator between sptrs. * * @param other Input sptr. - * @return Return true if two sptrs are not managing same object. + * @return `true` if different objects are managed by two sptrs; + * `false` otherwise. */ inline bool operator!=(const sptr &other) const { @@ -812,7 +820,7 @@ public: } private: - T *refs_ = nullptr; // Raw pointer to the managed specific object + T *refs_ = nullptr; // Raw pointer to the specific managed object }; template @@ -982,10 +990,11 @@ inline sptr::sptr(WeakRefCounter *p, bool /* force */) /** * @ingroup SmartPointer - * @brief Weak reference smart pointer to a RefBase(or its subclass) object. + * @brief Weak reference smart pointer to a RefBase object + * (or an object of its subclass). * - * Indirectly reference the RefBase object; - * Directly reference the WeakRefCounter object. + * A weak reference indirectly references the RefBase object + * and directly references the WeakRefCounter object. * * @tparam T Specific class type managed by wptr. * This class must inherit from RefBase. @@ -999,77 +1008,77 @@ public: wptr(); /** - * @brief Constructor with specified object to be managed. + * @brief Constructor with the specified object to be managed. + * + * This function will create WeakRefCounter object for `other` + * and set the count of weak references to 1. * - * This method will create WeakRefCounter object for `other` and set its - * weak reference count to 1. + * @note A WeakRefCounter object will not be created if `other` + * is a `nullptr`. * - * @note WeakRefCounter object will not be created if `other` is a - * `nullptr`. * @param other Object to be managed by wptr. */ wptr(T *other); /** - * @brief Copy constructor for wptr with same managed class type(T). + * @brief Copy constructor for wptr with the same managed class type (T). * - * This method will share the WeakRefCounter object of `other` with this - * wptr. Weak reference count in this WeakRefCounter object will be set - * properly. + * This function will share the WeakRefCounter object of `other` with this + * wptr and set the count of weak references properly. * - * @param other Another wptr with same managed class type(T). + * @param other Another wptr with the same managed class type (T). */ wptr(const wptr &other); /** - * @brief Copy constructor for sptr with same managed class type(T). + * @brief Copy constructor for sptr with the same managed class type (T). * - * This method will create WeakRefCounter object for the managed object of - * `other`, and set its weak reference count properly. + * This function will create a WeakRefCounter object for the managed + * object of `other`, and set the count of weak references properly. * - * @param other Another sptr with same managed class type(T). + * @param other Another sptr with the same managed class type (T). * @tparam T Specific class type managed by `other`. */ wptr(const sptr &other); /** - * @brief Copy constructor for wptr with different managed class type(O). + * @brief Copy constructor for wptr with a different managed class type (O). * - * Same with wptr::wptr(const wptr &other). + * This function is the same as wptr::wptr(const wptr &other). * * @tparam O Class type managed by `other`. - * @param other Another wptr with different managed class type(O). + * @param other Another wptr with a different managed class type (O). * @tparam T Specific class type managed by `other`. */ template wptr(const wptr &other); /** - * @brief Copy constructor for sptr with different managed class type(O). + * @brief Copy constructor for sptr with a different managed class type (O). * - * Same with wptr::wptr(const sptr &other). + * This function is the same as wptr::wptr(const sptr &other). * - * @param other Another sptr with same managed class type(O). + * @param other Another sptr with the same managed class type (O). * @tparam T Specific class type managed by `other`. */ template wptr(const sptr &other); /** - * @brief Copy assignment operator with specified object to be managed. + * @brief Copy assignment operator with the specified object to be managed. * - * @note Current wptr will unbind the original WeakRefCounter object and - * create a new WeakRefCounter object, then set its weak reference count - * properly. + * @note The current wptr will unbind the original WeakRefCounter object, + * create a new WeakRefCounter object, and then set the count of weak + * references properly. * @param other Another object to be managed by this wptr. */ wptr &operator=(T *other); /** - * @brief Copy assignment operator with specified object to be managed. + * @brief Copy assignment operator with the specified object to be managed. * * @note Same with wptr &operator=(T *other), but a pointer type casting - * which will not affect the type of `*other` is proccessed. + * which will not affect the type of `*other` is processed. * @tparam O Specific class type managed by `other`. * @param other Another object to be managed by this wptr. * @@ -1078,59 +1087,62 @@ public: wptr &operator=(O *other); /** - * @brief Copy assignment operator for wptr with same managed class type(T). + * @brief Copy assignment operator for wptr with the same managed class + * type (T). * - * @note Current wptr will unbind the original WeakRefCounter object and - * share the WeakRefCounter object with `other`, then set its weak - * reference count properly. - * @param other Another wptr. Object managed by it will also be managed by - * this wptr. + * @note The current wptr will unbind the original WeakRefCounter object, + * share the WeakRefCounter object with `other`, and then set the count of + * weak references properly. + * @param other Another wptr object. Objects managed by it will also be + * managed by this wptr. */ wptr &operator=(const wptr &other); /** - * @brief Copy assignment operator for sptr with - * same managed class type(T). + * @brief Copy assignment operator for sptr with the same managed class + * type (T). * - * @note Current wptr will unbind the original WeakRefCounter object and - * create a new WeakRefCounter object, then set its weak reference count - * properly. - * @param other A sptr object. Object managed by it will also be managed by - * this wptr. + * @note The current wptr will unbind the original WeakRefCounter object, + * create a new WeakRefCounter object, and then set the count of weak + * references properly. + * @param other A sptr object. Objects managed by it will also be + * managed by this wptr. */ wptr &operator=(const sptr &other); /** - * @brief Copy assignment operator for wptr with - * different managed class type(O). + * @brief Copy assignment operator for wptr with a different managed class + * type (O). * - * @note Same with wptr &operator=(const wptr &). Note that no cast - * here is proccessed. - * @param other An wptr object. Object managed by it will also be managed by - * this wptr. + * @note This function is the same as wptr &operator=(const wptr &). + * Note that no cast here is processed. + * @param other An wptr object. Objects managed by it will also be + * managed by this wptr. * @tparam O Specific class type managed by `other`. */ template wptr &operator=(const wptr &other); /** - * @brief Copy assignment operator for sptr with - * different managed class type(O). + * @brief Copy assignment operator for sptr with a different managed class + * type (O). * - * @note Same with wptr &wptr::operator=(const sptr &). Note that - * no cast here is proccessed. - * @param other An sptr object. Object managed by it will also be managed by - * this wptr. + * @note This function is the same as + * wptr &wptr::operator=(const sptr &). + * Note that no cast here is processed. + * @param other An sptr object. Objects managed by it will also be + * managed by this wptr. * @tparam O Specific class type managed by `other`. */ template wptr &operator=(const sptr &other); /** - * @brief Dereference operator. It will return the object managed by this - * wptr. + * @brief Dereference operator. + * + * This function will return the object managed by this wptr. * - * @return Return specific object managed by wptr. + * @return Specific object managed by wptr. */ inline T &operator*() const { @@ -1140,7 +1152,8 @@ public: /** * @brief Member selection operator. * - * It will return the specified member of the object managed by this wptr. + * This function will return the specified object member managed + * by this wptr. */ inline T *operator->() const { @@ -1148,18 +1161,18 @@ public: } /** - * @brief Equal-to operator between wptr and a raw pointer. + * @brief Equal-to operator between the wptr and raw pointer. * * @param other Input raw pointer. - * @return Return true if two pointers have same value. + * @return `true` if two pointers have the same value; `false` otherwise. */ bool operator==(const T *other) const; /** - * @brief Not-equal-to operator between wptr and a raw pointer. + * @brief Not-equal-to operator between the wptr and raw pointer. * * @param other Input raw pointer. - * @return Return true if two pointers have different value. + * @return `true` if two pointers have different values; `false` otherwise. */ inline bool operator!=(const T *other) const { @@ -1169,16 +1182,16 @@ public: /** * @brief Equal-to operator between two wptrs. * - * @param other Input reference of a wptr object. - * @return Return if two pointers have same value. + * @param other Input reference to a wptr object. + * @return `true` if two pointers have the same value; `false` otherwise. */ bool operator==(const wptr &other) const; /** * @brief Not-equal-to operator between two wptrs. * - * @param other Input reference of a wptr object. - * @return Return if two pointers have different value. + * @param other Input reference to a wptr object. + * @return `true` if two pointers have different values; `false` otherwise. */ inline bool operator!=(const wptr &other) const { @@ -1186,18 +1199,18 @@ public: } /** - * @brief Equal-to operator between wptr and a input sptr object. + * @brief Equal-to operator between the wptr and input sptr object. * - * @param other Input reference of an sptr object. - * @return Comparison result. + * @param other Input reference to an sptr object. + * @return true` if two pointers have the same value; `false` otherwise. */ bool operator==(const sptr &other) const; /** - * @brief Not-Equal-to operator between wptr and a input sptr object. + * @brief Not-equal-to operator between the wptr and input sptr object. * - * @param other Input reference of an sptr object. - * @return Comparison result. + * @param other Input reference to an sptr object. + * @return `true` if two pointers have different values; `false` otherwise. */ inline bool operator!=(const sptr &other) const { @@ -1205,19 +1218,20 @@ public: } /** - * @brief Get the pointer to the RefBase object. + * @brief Gets the pointer to the RefBase object. * * @return Raw pointer to the RefBase object. - * @note Return `nullptr` if the managed object has been deallocated. + * @note `nullptr` will be returned if the managed object has been + * deallocated. */ T *GetRefPtr() const; /** - * @brief Get the count value of corresponding WeakRefCounter object. + * @brief Gets the count of weak references in a WeakRefCounter object. * * The value indicates how many wptrs share the same WeakRefCounter object. * - * @return Value of the count. + * @return Count of weak references. * @note Only for test. */ inline int GetWeakRefCount() const @@ -1226,11 +1240,11 @@ public: } /** - * @brief Attempt to increment the strong reference count of + * @brief Attempts to increment the count of strong references in * the managed object. * - * @return Return true after a success increment. - * @note Avoid using it independently. Use `promote()`. + * @return `true` if the increment is successful; `false` otherwise. + * @note Avoid using this function independently. Use `promote()` instead. */ inline bool AttemptIncStrongRef(const void *objectId) const { @@ -1238,20 +1252,20 @@ public: } /** - * @brief Promote a wptr to an sptr. + * @brief Promotes a wptr to an sptr. * - * It will create an sptr object based on - * object managed by this wptr. + * This function will create an sptr object based on the object + * managed by this wptr. * - * @note Original weak reference will be retained. Promote may fail, - * and then return a "null sptr". + * @note The original weak reference will be retained. + * If the promotion fails, a "null sptr" will be returned. */ const sptr promote() const; ~wptr(); private: - WeakRefCounter *refs_ = nullptr; // Pointer to the corresponding weak reference counter object + WeakRefCounter *refs_ = nullptr; // Pointer to the corresponding WeakRefCounter object }; template diff --git a/base/include/rwlock.h b/base/include/rwlock.h index a3c7a1de1ee52505c3694ca186fd2f1a7cb84cc7..12c341f9e4ea7421c39d7823ca9f58329307ccec 100644 --- a/base/include/rwlock.h +++ b/base/include/rwlock.h @@ -16,7 +16,7 @@ /** * @file rwlock.h * - * @brief A file contains interfaces of RWLock in c_utils. + * @brief Provides interfaces of RWLock in c_utils. */ #ifndef UTILS_RWLOCK_H @@ -31,16 +31,17 @@ namespace OHOS { namespace Utils { /** - * @brief RWLock promise reading and writing thread-safe. + * @brief Implements the RWLock class to ensure that read and write + * operations are thread-safe. * - * Under RWLock, writing and writing are mutually exclusive, - * writing and reading are mutually exclusive. - * However, reading and reading are not mutually exclusive. + * Under RWLock, write operations are mutually exclusive, + * and read and write operations are mutually exclusive. + * However, read operations are not mutually exclusive. */ class RWLock : NoCopyable { public: /** - * @brief Enumeration of lock status. + * @brief Enumerates the lock states. */ enum LockStatus { LOCK_STATUS_WRITE = -1, @@ -48,70 +49,71 @@ public: }; /** - * @brief Construct a RWLock object. + * @brief Creates an RWLock object. * - * @param writeFirst Specifies the mode of RWLock, whether it is write-first. + * @param writeFirst Indicates whether the RWLock object is write-first. */ RWLock() : RWLock(true) {} explicit RWLock(bool writeFirst); /** - * @brief Destroy a RWLock object. + * @brief Destroys this RWLock object. */ ~RWLock() override {} /** - * @brief Acquire a read lock + * @brief Obtains a read lock. * - * If the thread has acquired the write lock, return directly. - * In 'write-first' mode, the state must be non-write locked - * and no other threads are waiting to write to acquire a read lock. - * If it is not write priority, you only need the current state to be - * non-write-locked to acquire a read lock. + * If the thread has obtained a write lock, this function returns directly. + * In write-first mode, a read lock can be obtained only when the state + * is non-write-locked and no other threads are waiting to write data. + * In other modes, a read lock can be obtained when the state is + * non-write-locked. */ void LockRead(); /** - * @brief Release the read lock. + * @brief Releases the read lock. * - * If the "write lock" has been acquired before, - * LockRead() will return directly, thus, - * this method will also be returned directly when called. + * If the write lock has been obtained before, + * LockRead() will return directly. + * This function will also return directly when called. */ void UnLockRead(); /** - *@brief Acquire a write lock + *@brief Obtains a write lock * - * If the thread has acquired a "write lock", LockWrite() will return directly - * to avoid acquiring a lock, because write locks are "exclusive locks". - * Only when no other thread has acquired a read lock or a write lock, - * the write lock can be acquired; otherwise wait. + * If the thread has obtained a write lock, this function returns directly + * to avoid acquiring a lock, because write locks are exclusive. + * The write lock can be obtained only when no other thread has obtained a read + * lock or a write lock; otherwise, the thread shall wait. */ void LockWrite(); /** - * @brief Release the write lock. + * @brief Releases the write lock. * - * If the thread does not obtain a "write lock" , it returns directly. + * If the thread has not obtained a write lock, this function returns directly. */ void UnLockWrite(); private: - bool writeFirst_; // The flag of write mode, true means write priority mode - std::thread::id writeThreadID_; // The ID of write Thread + bool writeFirst_; // Whether the thread is write-first. The value true means that the thread is write-first. + std::thread::id writeThreadID_; // ID of the write thread. - // Resource lock counter, -1 is write state, 0 is free state, and greater than 0 is shared read state + // Resource lock counter. -1 indicates the write state, 0 indicates the free state, and a value greater than 0 + // indicates the shared read state. std::atomic_int lockCount_; - // Thread counter waiting for write lock + // Thread counter waiting for the write lock. std::atomic_uint writeWaitCount_; }; /** * @brief UniqueWriteGuard object controls the ownership of a lockable object * within a scope, and is used only as acquisition - * and release of "write locks". + * and release of write locks. * It is actually an encapsulation of the RWLock class, which can be locked * at construction time and unlocked during destruction, * providing a convenient RAII mechanism. @@ -141,8 +143,8 @@ private: /** * @brief UniqueWriteGuard object controls the ownership of a lockable object * within a scope, and is used only as acquisition - * and release of "read locks". - * It is actually a encapsulation of the RWLock class, which can be locked + * and release of read locks. + * It is actually an encapsulation of the RWLock class, which can be locked * at construction time and unlocked during destruction, * providing a convenient RAII mechanism. */ diff --git a/base/include/safe_block_queue.h b/base/include/safe_block_queue.h index 80f0dbc49a60115260263f1787e8dde14e40f5b1..9ea21e6f63b047e4da0434c3397c9e8228c08353 100644 --- a/base/include/safe_block_queue.h +++ b/base/include/safe_block_queue.h @@ -16,9 +16,9 @@ /** * @file safe_block_queue.h * - * The file contains interfaces of Thread-safe block queues in c_utils. - * Includes the SafeBlockQueue class, and the SafeBlockQueueTracking class - * for trackable tasks. + * Provides interfaces for thread-safe blocking queues in c_utils. + * The file includes the SafeBlockQueue class and + * the SafeBlockQueueTracking class for trackable tasks. */ #ifndef UTILS_BASE_BLOCK_QUEUE_H @@ -33,9 +33,10 @@ namespace OHOS { /** - * @brief Thread-safe blocking queues. + * @brief Provides interfaces for thread-safe blocking queues. * - * Provides blocking and non-blocking push and pop interfaces. + * The interfaces can be used to perform blocking and non-blocking push and + * pop operations on queues. */ template class SafeBlockQueue { @@ -45,41 +46,43 @@ public: } /** - * @brief Insert an element at the end of the queue (blocking). + * @brief Inserts an element at the end of this queue in blocking mode. * - * When the queue is full, the thread of the push operation will be blocked. - * When the queue is not full, the push operation can be executed - * and wakes up one of the waiting threads. + * If the queue is full, the thread of the push operation will be blocked + * until the queue has space. + * If the queue is not full, the push operation can be performed and one of the + * pop threads (blocked when the queue is empty) is woken up. * - * @param elem Enqueue data. + * @param elem Indicates the element to insert. */ virtual void Push(T const& elem) { std::unique_lock lock(mutexLock_); while (queueT_.size() >= maxSize_) { - // queue full , waiting for jobs to be taken + // If the queue is full, wait for jobs to be taken. cvNotFull_.wait(lock, [&]() { return (queueT_.size() < maxSize_); }); } - // here means not full we can push in + // Insert the element into the queue if the queue is not full. queueT_.push(elem); cvNotEmpty_.notify_one(); } /** - * @brief Get the first element of the queue (blocking). + * @brief Removes the first element from this queue in blocking mode. * - * When the queue is empty, the thread of the pop operation will be blocked. - * When the queue is not empty, the pop operation can be executed - * and wakes up one of the waiting threads. Then return the first element - * of the queue. + * If the queue is empty, the thread of the pop operation will be blocked + * until the queue has elements. + * If the queue is not empty, the pop operation can be performed, the first + * element of the queue is returned, and one of the push threads (blocked + * when the queue is full) is woken up. */ T Pop() { std::unique_lock lock(mutexLock_); while (queueT_.empty()) { - // queue empty, waiting for tasks to be Push + // If the queue is empty, wait for elements to be pushed in. cvNotEmpty_.wait(lock, [&] { return !queueT_.empty(); }); } @@ -90,14 +93,14 @@ public: } /** - * @brief Insert an element at the end of queue (Non-blocking). + * @brief Inserts an element at the end of this queue in non-blocking mode. * - * When the queue is full, the thread of the push operation - * will directly return false. - * When the queue is not full, the push operation can be executed - * and wakes up one of the waiting threads, and return true. + * If the queue is full, false is returned directly. + * If the queue is not full, the push operation can be performed, one of the + * pop threads (blocked when the queue is empty) is woken up, and true + * is returned. * - * @param elem Enqueue data. + * @param elem Indicates the element to insert. */ virtual bool PushNoWait(T const& elem) { @@ -105,21 +108,21 @@ public: if (queueT_.size() >= maxSize_) { return false; } - // here means not full we can push in + // Insert the element if the queue is not full. queueT_.push(elem); cvNotEmpty_.notify_one(); return true; } /** - * @brief Get the first elements of the queue (Non-blocking). + * @brief Removes the first element from this queue in non-blocking mode. * - * When the queue is empty, the thread of the pop operation - * will directly return false. - * When the queue is not empty, the pop operation can be executed - * and wakes up one of the waiting threads, and return true. + * If the queue is empty, false is returned directly. + * If the queue is not empty, the pop operation can be performed, one of the + * push threads (blocked when the queue is full) is woken up, and true + * is returned. * - * @param outtask data of pop. + * @param outtask Indicates the data of the pop operation. */ bool PopNotWait(T& outtask) { @@ -156,7 +159,7 @@ public: virtual ~SafeBlockQueue() {} protected: - unsigned long maxSize_; // capacity of queue + unsigned long maxSize_; // Capacity of the queue std::mutex mutexLock_; std::condition_variable cvNotEmpty_; std::condition_variable cvNotFull_; @@ -164,8 +167,9 @@ protected: }; /** - * @brief A thread-safe blocking queue that inherits SafeBlockQueue - * and tracks the number of outstanding tasks. + * @brief Provides interfaces for operating the thread-safe blocking queues + * and tracking the number of pending tasks. + * This class inherits from SafeBlockQueue. */ template class SafeBlockQueueTracking : public SafeBlockQueue { @@ -178,34 +182,35 @@ public: virtual ~SafeBlockQueueTracking() {} /** - * @brief Insert an element at the end of queue (blocking). + * @brief Inserts an element at the end of this queue in blocking mode. * - * When the queue is full, the thread of the push operation will be blocked. - * When the queue is not full, the push operation can be executed - * and wakes up one of the waiting threads. + * If the queue is full, the thread of the push operation will be blocked + * until the queue has space. + * If the queue is not full, the push operation can be performed and one of the + * pop threads (blocked when the queue is empty) is woken up. */ virtual void Push(T const& elem) { unfinishedTaskCount_++; std::unique_lock lock(mutexLock_); while (queueT_.size() >= maxSize_) { - // queue full , waiting for jobs to be taken + // If the queue is full, wait for jobs to be taken. cvNotFull_.wait(lock, [&]() { return (queueT_.size() < maxSize_); }); } - // here means not full we can push in + // If the queue is not full, insert the element. queueT_.push(elem); cvNotEmpty_.notify_one(); } /** - * @brief Insert an element at the end of queue (Non-blocking). + * @brief Inserts an element at the end of this queue in non-blocking mode. * - * When the queue is full, the thread of the push operation - * will directly return false. - * When the queue is not full, the push operation can be executed - * and wakes up one of the waiting threads, and return true. + * If the queue is full, false is returned directly. + * If the queue is not full, the push operation can be performed, + * one of the pop threads (blocked when the queue is empty) is woken up, + * and true is returned. */ virtual bool PushNoWait(T const& elem) { @@ -213,7 +218,7 @@ public: if (queueT_.size() >= maxSize_) { return false; } - // here means not full we can push in + // Insert the element if the queue is not full. queueT_.push(elem); unfinishedTaskCount_++; cvNotEmpty_.notify_one(); @@ -221,14 +226,14 @@ public: } /** - * @brief A response function when a task completes. + * @brief Called to return the result when a task is complete. * - * If the count of unfinished task < 1, return false directly. - * If the count of unfinished task = 1, all threads waiting - * while calling Join() will be woken up; - * the count of unfinished task decrements by 1 and returns true. - * If the count of unfinished task > 1, - * decrements the count by 1 and returns true. + * If the count of unfinished tasks < 1, false is returned directly. + * If the count of unfinished tasks = 1, all the threads blocked + * by calling Join() will be woken up, + * the count of unfinished tasks decrements by 1, and true is returned. + * If the count of unfinished tasks > 1, + * the count of unfinished tasks decrements by 1, and true is returned. */ bool OneTaskDone() { @@ -247,9 +252,9 @@ public: } /** - * @brief Wait for all tasks to complete. + * @brief Waits for all tasks to complete. * - * When anyone of the tasks is not completed, the current thread will be + * If there is any task not completed, the current thread will be * blocked even if it is just woken up. */ void Join() @@ -259,7 +264,7 @@ public: } /** - * @brief Returns the number of unfinished tasks. + * @brief Obtains the number of unfinished tasks. */ int GetUnfinishTaskNum() { diff --git a/base/include/safe_map.h b/base/include/safe_map.h index b137ab577474f148f08e5c46b8275d232fce73f7..213a023d3f4ea75543c07dd6b5aced2ea87b7368 100644 --- a/base/include/safe_map.h +++ b/base/include/safe_map.h @@ -22,7 +22,7 @@ namespace OHOS { /** - * @brief A thread-safe map implementation is provided. + * @brief Provides interfaces for thread-safe map operations. */ template class SafeMap { @@ -51,10 +51,11 @@ public: } /** - * @brief Get the size of the map. + * @brief Obtains the map size. * - * when multithread calling Size() return a tmp status, some threads may - * insert just after Size() call. + * In the multithread scenario, the map size returned is a tmp status, + * because elements may be inserted or removed by other threads after + * Size() is called. */ int Size() { @@ -63,12 +64,14 @@ public: } /** - * @brief Determine whether the map is empty or not. + * @brief Checks whether the map is empty. * - * when multithread calling Empty() return a tmp status, some threads may - * insert just after Empty() call. + * In the multithread scenario, the value returned by Empty() is a + * tmp status, because elements may be inserted or removed by other threads + * after Empty() is called. * - * @return Return true if it is empty, otherwise returns false. + * @return Returns true if the map is empty; + * returns false otherwise. */ bool IsEmpty() { @@ -77,12 +80,12 @@ public: } /** - * @brief Insert a new element into the map. + * @brief Inserts an element to the map. * - * @param key The key to be inserted. - * @param value The value to be inserted. - * @return Return true if the insertion is successful, otherwise returns - * false. + * @param key Indicates the key of the key-value (KV) pair to insert. + * @param value Indicates the value of the KV pair to insert. + * @return Returns true if the KV pair is inserted; returns + * false otherwise. */ bool Insert(const K& key, const V& value) { @@ -92,12 +95,12 @@ public: } /** - * @brief Insert elements into the map. + * @brief Forcibly inserts an element to the map. * - * @param key The key to be inserted. - * @param value The value to be inserted. - * @note Delete and then insert when the key exists, ensuring that the - * final value is inserted. + * @param key Indicates the key of the KV pair to insert. + * @param value Indicates the value of the KV pair to insert. + * @note If the key to insert already exists, delete and then insert + * the KV pair to ensure that the value is inserted. */ void EnsureInsert(const K& key, const V& value) { @@ -113,11 +116,12 @@ public: } /** - * @brief Search for elements in the map. + * @brief Searches for an element in the map. * - * @param Key The key to be found. - * @param value The value corresponding to the found key. - * @return Return true when the key exists, otherwise returns false. + * @param Key Indicates the key to search. + * @param value Indicates the value of the KV pair to search. + * @return Returns true if the KV pair is found; + * returns false otherwise. */ bool Find(const K& key, V& value) { @@ -134,13 +138,13 @@ public: } /** - * @brief Search for elements in the map and replace the `oldValue` - * corresponding to the key with `newValue`. + * @brief Replaces the value of a KV pair. * - * @param Key The key to be found. - * @param oldValue The value corresponding to the found key. - * @param newValue The new value to insert. - * @return Return true when the key exists, otherwise returns false. + * @param Key Indicates the key of the KV pair. + * @param oldValue Indicates the value to be replaced. + * @param newValue Indicates the new value of the KV pair. + * @return Returns true if the key is replaced; + * returns false otherwise. */ bool FindOldAndSetNew(const K& key, V& oldValue, const V& newValue) { @@ -160,9 +164,9 @@ public: } /** - * @brief Delete key-value pairs whose key is key in the map. + * @brief Erases a KV pair. * - * @param Key The key to be deleted. + * @param Key Indicates the key of the KV pair to erase. */ void Erase(const K& key) { @@ -171,7 +175,7 @@ public: } /** - * @brief Delete all key-value pairs stored in the map. + * @brief Deletes all KV pairs from the map. */ void Clear() { @@ -183,10 +187,10 @@ public: using SafeMapCallBack = std::function; /** - * @brief Iterate through the elements in the map. + * @brief Iterates over the elements of the map. * - * @param callback A specific function that performs custom operations on - * each KV key-value pair. + * @param callback Called to perform the custom operations on + * each KV pair. */ void Iterate(const SafeMapCallBack& callback) { diff --git a/base/include/safe_queue.h b/base/include/safe_queue.h index 9c97047c7935126ecfcab595ace15bc19b54c25a..5cc468273e6157ed130e6129ddd66838cee99348 100644 --- a/base/include/safe_queue.h +++ b/base/include/safe_queue.h @@ -16,10 +16,10 @@ /** * @file safe_queue.h * - * @brief The file contains interfaces of thread-safe queues in c_utils. + * @brief Provides interfaces for thread-safe queue operations in c_utils. * - * The file contains thread-safe abstract class, the SafeQueue - * and SafeStack that override the virtual methods of the abstract class. + * The file contains the thread-safe abstract class, the SafeQueue + * and SafeStack that override the virtual methods of the abstract class. */ #ifndef UTILS_BASE_SAFE_QUEUE_H @@ -31,10 +31,10 @@ namespace OHOS { /** - * @brief An abstract class for thread-safe queues. + * @brief Provides an abstract class for thread-safe queues. * - * Encapsulate std::lock_guard locks on the basis of std::deque, - * so that the interface of the queue becomes thread-safe. + * It encapsulates std::lock_guard locks on the basis of std::deque to + * make the interfaces of the queue thread-safe. */ template class SafeQueueInner { @@ -98,10 +98,10 @@ protected: }; /** - * @brief Thread-safe Queue. + * @brief Provides thread-safe queue operations. * - * Overrides the DoPush and DoPop methods of abstract classes to implement - * the push and pop functionality of the "SafeQueue". + * It overrides the DoPush and DoPop methods of abstract classes + * to implement the push and pop functionality of SafeQueue. */ template class SafeQueue : public SafeQueueInner { @@ -116,8 +116,8 @@ protected: } /** - * @brief Encapsulate the pop_front() of dequeues - * and implement the pop function of queues. + * @brief Encapsulates the pop_front() method + * to implement the pop function of queues. */ bool DoPop(T& pt) override { @@ -132,10 +132,10 @@ protected: }; /** - * @brief Thread-safe Stack. + * @brief Provides thread-safe stack operations. * - * Overrides the DoPush and DoPop methods of abstract classes - * to implement the push and pop functionality of the "SafeStack". + * It overrides the DoPush and DoPop methods of abstract classes + * to implement the push and pop functionality of SafeStack. */ template class SafeStack : public SafeQueueInner { @@ -150,8 +150,8 @@ protected: } /** - * @brief Encapsulate the pop_back() of dequeues - * and implement the pop function of stack. + * @brief Encapsulates the pop_back() method + * to implement the pop function of stack. */ bool DoPop(T& pt) override { diff --git a/base/include/semaphore_ex.h b/base/include/semaphore_ex.h index ccb1fd11abb901f3b3502acd82799f1b11999ac5..f3e04c7101b33dd4a3bacaf7de245483f13244d4 100644 --- a/base/include/semaphore_ex.h +++ b/base/include/semaphore_ex.h @@ -16,14 +16,14 @@ /** * @file semaphore_ex.h * - * @brief This file contains interfaces of Semaphore in c_utils, + * @brief Provides interfaces of semaphores in c_utils, * including nameless and named semaphores. * - * The semaphore is an atomic counter, which can act as a lock, - * to achieve mutual exclusion, synchronization and other functions; - * Used in a multithreaded environment, it is possible to ensure that - * a critical pieces of code is not called concurrently or maximum number - * of threads entering the code section is restricted. + * A semaphore is an atomic counter, which can act as a lock + * to achieve mutual exclusion, synchronization, and other functions. + * Used in a multithreaded environment, it prevents concurrent + * calling of a critical piece of code or restricts the maximum number + * of threads entering the code section. */ #ifndef SEMAPHORE_EX_H @@ -40,47 +40,47 @@ namespace OHOS { /** - * @brief Semaphore. This class is a counter to implement functions such as - * mutual exclusion between processes/threads, synchronization, etc. + * @brief Provides interfaces for operating semaphores. * + * A semaphore is a counter used to implement functions, such as + * mutual exclusion between processes/threads, synchronization, and more. * The difference between nameless semaphores and named semaphores lies * in the form of creation and destruction. - * The semaphore exists only in memory, requiring that the process/thread + * Semaphores exist only in memory. The process/thread * using the semaphore must access the memory where the semaphore is located. * Therefore, the nameless semaphore can only be in the thread of * the same process, or threads in different processes that have mapped - * the same memory to their address space, that is, the nameless semaphore + * the same memory to their address space, that is, the nameless semaphores * can only be accessed through shared memory. */ class Semaphore : public NoCopyable { public: /** - * @brief Construct a semaphore object. + * @brief A constructor used to create a semaphore object. * - * @param Value The initial value of the semaphore object. + * @param Value Indicates the initial value of the semaphore object. */ explicit Semaphore(int value = 1) : count_(value) {} /** - * @brief Acquire semaphore operation, i.e. semaphore -1. + * @brief Acquires the semaphore. * - * When the semaphore is >= 0 after decrement, the current thread continues. - * When semaphore is < 0 after decrement, the current thread blocks. + * If the current semaphore count >= 0, the current thread continues. + * If the current semaphore count < 0, the current thread will be blocked. */ void Wait(); /** - * @brief Release semaphore operation, i.e. semaphore +1. + * @brief Releases the semaphore. * - * When the semaphore is > 0 after increment, it means that - * there is no blocked thread. - * When the semaphore is <= 0 after increment, it means that there are still + * If the current semaphore count > 0, there is no blocked thread. + * If the current semaphore count <= 0, there are still * blocked threads. Then this method will wake one of them up. */ void Post(); private: - int count_; // The initial value of the Semaphore object + int count_; // Initial value of the semaphore object. std::mutex mutex_; std::condition_variable cv_; }; diff --git a/base/include/singleton.h b/base/include/singleton.h index 3f3f4e4b804fc84644b03cefb35427ca7635620f..0e0c91010e39558202ab1c7f628c618fd7a09d23 100644 --- a/base/include/singleton.h +++ b/base/include/singleton.h @@ -28,19 +28,19 @@ namespace OHOS { * * Taking DelayedSingleton as an example, when declaring the target class as a * singleton, add the DECLARE_DELAYED_SINGLETON (class_name) to the class - * declaration.\n - * When using the target singleton, call class_name::GetInstance()->. + * declaration. When using the target singleton, call + * class_name::GetInstance()->. */ /** - * @brief Set `MyClass` as a `DelayedSingleton`. + * @brief Sets `MyClass` as a `DelayedSingleton`. * - * `MyClass` object can be obtained by calling + * A `MyClass` object can be obtained by calling * `DelayedSingleton::GetInstance()`. * * @param MyClass Target class to be set as a singleton. - * @note This macro definition should be used into the body of a class - * definition. + * + * @note This macro definition should be used in the body of a class definition. */ #define DECLARE_DELAYED_SINGLETON(MyClass)\ public:\ @@ -50,14 +50,14 @@ private:\ MyClass(); /** - * @brief Set `MyClass` as a `DelayedRefSingleton`. + * @brief Sets `MyClass` as a `DelayedRefSingleton`. * - * `MyClass` object can be obtained by calling + * A `MyClass` object can be obtained by calling * `DelayedRefSingleton::GetInstance()`. * * @param MyClass Target class to be set as a singleton. - * @note This macro definition should be used into the body of a class - * definition. + * + * @note This macro definition should be used in the body of a class definition. */ #define DECLARE_DELAYED_REF_SINGLETON(MyClass)\ private:\ @@ -66,14 +66,14 @@ private:\ MyClass(); /** - * @brief Set `MyClass` as a `Singleton`. + * @brief Sets `MyClass` as a `Singleton`. * - * `MyClass` object can be obtained by calling + * A `MyClass` object can be obtained by calling * `Singleton::GetInstance()`. * * @param MyClass Target class to be set as a singleton. - * @note This macro definition should be used into the body of a class - * definition. + * + * @note This macro definition should be used in the body of a class definition. */ #define DECLARE_SINGLETON(MyClass)\ private:\ @@ -84,35 +84,33 @@ private:\ ~MyClass(); /** - * @brief class DelayedSingleton is a thread-safe, memory-safe lazy initialized + * @brief DelayedSingleton is a thread-safe, memory-safe lazy initialized * singleton (with smart pointer and lock). */ template class DelayedSingleton : public NoCopyable { public: /** - * @brief Create a unique instance object and return. + * @brief Creates a unique instance object. * - * Use smart pointer to manage resources, and when all shared_ptrs are - * destroyed, the new object will also be deleted. This avoids memory - * leaks.\n - * Lock is added only when the pointer is empty to avoid locking every time - * the `GetInstance()` method is called, reducing the overhead of lock. + * Use a smart pointer to manage resources. If all shared_ptrs are + * destroyed, the new object will also be deleted. This avoids memory leaks. + * A lock is added only when the pointer is empty, so as to avoid locking + * every time `GetInstance()` is called, reducing overhead of the lock. */ static std::shared_ptr GetInstance(); /** - * @brief Release the ownership of managed object of the smart pointer. + * @brief Releases the ownership of managed object of the smart pointer. * - * @note After calling this method, the 'GetInstance()' method will create - * a new object, and if the old object has an external 'std::shared_ptr' - * reference, the developer needs to release it himself to guarantee a - * singleton. + * @note After this API is called successfully, 'GetInstance()' will create + * a new object. If the old object has an external 'std::shared_ptr' + * reference, you need to release it to maintain a singleton. */ static void DestroyInstance(); private: static std::shared_ptr instance_; // Record the created DelayedSingleton instance. - static std::mutex mutex_; // Guarantees that only one thread is accessing a common resource at any time. + static std::mutex mutex_; // Mutex, which guarantees that only one thread is accessing a common resource at any time. }; template @@ -146,22 +144,22 @@ void DelayedSingleton::DestroyInstance() } /** - * @brief class DelayedRefSingleton is a thread-safe, lazy initialized - * singleton(with ordinary pointer and lock). + * @brief DelayedRefSingleton is a thread-safe, lazy initialized + * singleton (with ordinary pointer and lock). */ template class DelayedRefSingleton : public NoCopyable { public: /** - * @brief Create a unique instance object and return. + * @brief Creates a unique instance object. * - * Pointer is used in the implementation, and the return type is a - * reference:the instance returned by reference has a lifetime that is - * managed by non-user code. + * Pointer is used in the implementation, and the return value is a + * reference. It points to an instance that has a lifetime managed by + * the non-user code. * * @note The instance may not have been created at a certain point in time, - * or it can be deleted, which cannot prevent the user from using delete - * keyword to cause the object to be destroyed in advance. + * or it may have been deleted, and therefore it is not possible to + * prohibit use of the delete keyword to destroy the object in advance. */ static T& GetInstance(); @@ -190,15 +188,15 @@ T& DelayedRefSingleton::GetInstance() } /** - * @brief class Singleton is a normal initialized singleton(no pointers and - * locks are used). + * @brief Singleton is a normally initialized singleton (without pointers and + * locks). */ template class Singleton : public NoCopyable { public: /** - * @brief Return a unique instance object. + * @brief Gets a singleton instance object. */ static T& GetInstance() { return instance_; } diff --git a/base/include/sorted_vector.h b/base/include/sorted_vector.h index ed23d8e87422a625ded703b3e96bb1364e45dcee..8da487d3df99a3039178b804efead71ff6d9c380 100644 --- a/base/include/sorted_vector.h +++ b/base/include/sorted_vector.h @@ -25,7 +25,7 @@ namespace OHOS { /** - * @brief The order of the items in it can be maintained automatically. + * @brief Provides a sorted vector, in which all items are sorted automatically. */ template class SortedVector { @@ -37,7 +37,7 @@ public: using const_iterator = typename std::vector::const_iterator; /** - * @brief Construct a new SortedVector object. + * @brief Creates a `SortedVector` object. */ SortedVector(); @@ -48,47 +48,50 @@ public: SortedVector(const std::vector& orivect); /** - * @brief Destroy the SortedVector object. + * @brief Destroys this `SortedVector` object. */ virtual ~SortedVector() {} /** - * @brief Copy assignment operator. + * @brief An overloaded assignment operator function that assigns a sorted + * vector to this vector. * - * @param TYPE Type of the items. - * @param AllowDuplicate Specify if duplicated items are allowed. + * @param TYPE Indicates the type of items. + * @param AllowDuplicate Specifies whether duplicated items are allowed. */ SortedVector& operator=(const SortedVector& rhs); SortedVector& operator=(const SortedVector& rhs); /** - * @brief Empty the vector. + * @brief Clears this vector. */ inline void Clear() { vec_.clear(); } /** - * @brief Return number of items in the vector. + * @brief Obtains the number of items in this vector. */ inline size_t Size() const { return vec_.size(); } /** - * @brief Return whether or not the vector is empty. + * @brief Checks whether this vector is empty. * - * @return Return true if vector is empty, false otherwise. + * @return Returns `true` if the vector is empty; returns `false` otherwise. */ inline bool IsEmpty() const { return vec_.empty(); } /** - * @brief Return how many items can be stored before reallocating new - * storage space. + * @brief Obtains the capacity of this vector, that is, the number of items + * that can be stored before the system reallocates new storage space. */ inline size_t Capacity() const { return vec_.capacity(); } /** - * @brief Set the vector's capacity to `size`. + * @brief Sets the capacity of this vector. * - * @return Return `size` if the vector's capacity is changed to `size`, - * otherwise return `CAPACITY_NOT_CHANGED`(-1). + * @param size Indicates the capacity to set. + * + * @return Returns the capacity if the operation is successful; + * returns `CAPACITY_NOT_CHANGED`(-1) otherwise. */ ssize_t SetCapcity(size_t size) { @@ -102,66 +105,80 @@ public: // Cstyle access /** - * @brief Return a const pointer to the first item of a vector, which is - * used to access the item. + * @brief Accesses the first item in this vector. + * + * @return Returns a constant pointer to the first item. */ inline const TYPE* Array() const { return vec_.data(); } /** - * @brief Return a non-const pointer to the first item of a vector that is - * used to access the item of the vector. + * @brief Accesses the first item in this vector while editing it. + * + * @note When using this function, you should ensure that the vector + * is sorted. * - * @note When use it , you should make sure it is sorted. + * @return Returns a non-constant pointer to the first item. */ TYPE* EditArray() { return vec_.data(); } /** - * @brief Find the first index of the 'item' value in the vector. + * @brief Obtains the index of the first occurrence of an item + * in this vector. + * + * @param item Indicates the item. + * + * @return Returns the index if the item is found; + * returns `NOT_FOUND`(-1) otherwise. * - * @param item Target value. - * @return If found, the index value is returned, otherwise `NOT_FOUND`(-1) - * is returned. */ ssize_t IndexOf(const TYPE& item) const; /** - * @brief Find where this `item` should be inserted. + * @brief Obtains the index where an item should be inserted into + * this vector. * - * @param item Target value. - * @return Return the index where the value should be inserted. + * @param item Indicates the item. + * + * @return Returns the index. */ size_t OrderOf(const TYPE& item) const; /** - * @brief Access vector items based on the input `index`. + * @brief Accesses an item with the specified index. + * + * @param index Indicates the index. * - * @param index `index` value. - * @return Return the value of the item corresponding to the `index`. + * @return Returns the item value. */ inline const TYPE& operator[](size_t index) const { return vec_[index]; } /** - * @brief Return a reference to the item at the end of the vector. + * @brief Obtains the reference to the last item in this vector. + * + * @return Returns the reference to the last item. */ const TYPE& Back() const { return vec_.back(); } /** - * @brief Return a reference to the vector starting item. + * @brief Obtains the reference to the first item in this vector. + * + * @return Returns the reference to the first item. */ const TYPE& Front() const { return vec_.front(); } /** - * @brief Remove the last item of the vector. + * @brief Removes the last item from this vector. */ void PopBack() { return vec_.pop_back(); } /** - * @brief Return the item value of a vector. + * @brief Obtains the value of an item with the specified index + * in this vector. * - * @param index `index` value. - * @return If `index` is less than 0, the value of - * vector[vector.size() + `index`] is returned, otherwise the value of - * vector[`index`] is returned. + * @param index Indicates the index. + * + * @return Returns vector[vector.size() + `index`] if `index` is + * less than 0; returns vector[`index`] otherwise. */ const TYPE& MirrorItemAt(ssize_t index) const { @@ -171,19 +188,22 @@ public: return *(vec_.begin() + index); }; - // modify the array + // Modify the array. /** - * @brief Add a new 'item' in the correct place. + * @brief Adds an item to this vector. * - * @return Return the position of the new item on success, otherwise it - * returns `ADD_FAIL`(-1) + * @return Returns the index of the item if the operation is successful; + * returns `ADD_FAIL`(-1) otherwise. */ ssize_t Add(const TYPE& item); /** - * @brief Return reference of the item based on `index`. + * @brief Obtains the reference to an item with the specified index + * in this vector. + * + * @param index Indicates the index. * - * @param index `index` value. + * @return Returns the reference to the item. */ TYPE& EditItemAt(size_t index) { @@ -192,24 +212,26 @@ public: /** - * @brief Merge a vector into this one. + * @brief Merges a vector into this vector. * - * If the value of `AllowDuplicate` is false, it is vec_ to deduplicate. + * If `AllowDuplicate` is set to `false`, the current vector should + * perform deduplication. * - * @param invec The vector to be merged. - * @return Return the size of the merged vec_. + * @param invec Indicates the vector to be merged. + * + * @return Returns the size of the merged vector. */ size_t Merge(const std::vector& invec); size_t Merge(const SortedVector& sortedVector); /** - * @brief If `index` is less than the vector's size, delete the item at - * `index`. + * @brief Erases the item with the specified index from this vector. + * + * @param index Indicates the index. * - * @param index `index` value. - * @return If `index` is greater than or equal to the size of the vector, - * the iterator of the last item is returned, otherwise the iterator of the - * next item of the deleted item is returned. + * @return Returns an iterator to the last item if the index is + * greater than or equal to the size of the vector; + * returns the item next to the deleted item otherwise. */ iterator Erase(size_t index) { @@ -220,8 +242,10 @@ public: } /** - * @brief An iterator that returns a vector starting item of a non-const - * type. + * @brief Obtains an iterator of the non-const type to the first item + * in this vector. + * + * @return Returns an iterator to the first item. */ iterator Begin() { @@ -229,7 +253,10 @@ public: } /** - * @brief An iterator that returns the vector starting item of type const. + * @brief Obtains an iterator of the const type to the first item + * in this vector. + * + * @return Returns an iterator to the first item. */ const_iterator Begin() const { @@ -237,8 +264,10 @@ public: } /** - * @brief Return an iterator for an item at the end of a vector of a - * non-const type. + * @brief Obtains an iterator of the non-const type to the last item + * in this vector. + * + * @return Returns an iterator to the last item. */ iterator End() { @@ -246,8 +275,10 @@ public: } /** - * @brief Return an iterator for the item at the end of a vector of type - * const. + * @brief Obtains an iterator of the const type to the last item + * in this vector. + * + * @return Returns an iterator to the last item. */ const_iterator End() const { diff --git a/base/include/string_ex.h b/base/include/string_ex.h index f7671d6ffc5519f958b77a64064d34f3d79c4bc1..cf99110c3561048b2eec33507de2a2b1e8fa6196 100644 --- a/base/include/string_ex.h +++ b/base/include/string_ex.h @@ -16,13 +16,13 @@ /** * @file string_ex.h * -* @brief Provide global string operation function implemented in c_utils. +* @brief Provides the global string operation function implemented in c_utils. */ /** * @defgroup StringOperation * @{ -* @brief To operate strings. +* @brief Provides interfaces for operating strings. * * Include converting between uppercase and lowercase, * string replacement, trim and split etc. @@ -37,76 +37,76 @@ namespace OHOS { /** * @ingroup StringOperation - * @brief Convert all letters of string to uppercase. + * @brief Converts all letters in a string to uppercase. * - * @param str Base string. - * @return Return a new converted `std::string` object. + * @param str Indicates the base string. + * @return Returns a new `std::string` object after conversion. */ std::string UpperStr(const std::string& str); /** * @ingroup StringOperation - * @brief Convert all letters of string to lowercase. + * @brief Converts all letters in a string to lowercase. * - * @param str Base string. - * @return Return a new converted `std::string` object. + * @param str Indicates the base string. + * @return Returns a new `std::string` object after conversion. */ std::string LowerStr(const std::string& str); /** * @ingroup StringOperation - * @brief Replace `src` with `dst` in base string `str`. + * @brief Replaces a substring in the base string. * - * @param str Target sub-string to be replaced. - * @param src Base string. - * @param dst Expected sub-string for replacement. - * @return Return a new replaced `std::string` object. + * @param str Indicates the substring to be replaced. + * @param src Indicates the base string. + * @param dst Indicates the expected substring for replacement. + * @return Returns a new `std::string` object after replacement. */ std::string ReplaceStr(const std::string& str, const std::string& src, const std::string& dst); /** * @ingroup StringOperation - * @brief Trim string by `cTrim` at the front and end of `str`. + * @brief Trims a string indicated by `cTrim` from both ends of the base string. * - * @param str Base string. - * @param cTrim Target string used in trim，which is '' by default. - * @return Return a new trimmed `std::string` object. + * @param str Indicates the base string. + * @param cTrim Indicates the string to trim from the base string, which is '' by default. + * @return Returns a new `std::string` object after trimming. */ std::string TrimStr(const std::string& str, const char cTrim = ' '); /** * @ingroup StringOperation - * @brief Convert decimal to hexadecimal string. + * @brief Converts a decimal value to a hexadecimal string. * - * @param value Target decimal value. - * @param upper Specify if output as uppercase, - * whose value is `true` by default。 - * @return Return a new converted `std::string` object. + * @param value Indicates the decimal value to convert. + * @param upper Specifies whether the output string is in uppercase. + * The default value is `true`. + * @return Returns a new `std::string` object after conversion. */ std::string DexToHexString(int value, bool upper = true); /** * @ingroup StringOperation - * @brief Split string by `sep`. + * @brief Splits a string by `sep`. * - * @param str Base string. - * @param sep Sub-string as separator. - * @param strs `std::vector` object to store the results. - * @param canEmpty Specify if output empty string as results, - * whose value is false by default. - * @param needTrim Specify if need to trim by '', - * whose value is true by default. + * @param str Indicates the base string. + * @param sep Indicates the substring to be used as the separator. + * @param strs Indicates the `std::vector` object to store the results. + * @param canEmpty Specifies whether the output string can be an empty string. + * The default value is `false`. + * @param needTrim Specifies whether to remove whitespace from the output string. + * The default value is `true`. */ void SplitStr(const std::string& str, const std::string& sep, std::vector& strs, bool canEmpty = false, bool needTrim = true); /** * @ingroup StringOperation - * @brief Convert int and double and so on to string. + * @brief Converts a value of int, double, or any other type to a string. * - * @tparam T Specific type of input data. - * @param iValue Input data. - * @return Return a new converted `std::string` object. + * @tparam T Indicates the type of the input data. + * @param iValue Indicates the input data. + * @return Returns a new `std::string` object after conversion. */ template inline std::string ToString(T iValue) @@ -116,120 +116,130 @@ inline std::string ToString(T iValue) /** * @ingroup StringOperation - * @brief Convert string to int. + * @brief Converts a string to an int value. * - * @param str String to be converted. - * @param value Target `int` variable to store the result. - * @return Return true if converting success, false if failed. + * @param str Indicates the string to be converted. + * @param value Indicates the `int` variable to store the result. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool StrToInt(const std::string& str, int& value); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are numbers. + * @brief Checks whether all characters in a string are numeric. * - * @param str Base string. - * @return Return true if all are numbers, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are numeric; + * returns `false` otherwise. */ bool IsNumericStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are alphabet. + * @brief Checks whether all characters in a string are alphabetic. * - * @param str Base string. - * @return Return true if all are alphabet, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are alphabetic; + * returns `false` otherwise. */ bool IsAlphaStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are uppercase. + * @brief Checks whether all characters in a string are in uppercase. * - * @param str Base string. - * @return Return true if all are uppercase, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are in uppercase; + * returns `false` otherwise. */ bool IsUpperStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are lowercase. + * @brief Checks whether all characters in a string are in lowercase. * - * @param str Base string. - * @return Return true if all are lowercase, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are in lowercase; + * returns `false` otherwise. */ bool IsLowerStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if `str` contains the `sub`. + * @brief Checks whether a string contains the specified substring. * - * @param str Base string. - * @param sub Target sub-string. - * @return Return true if contains, otherwise false. + * @param str Indicates the base string. + * @param sub Indicates the substring. + * @return Returns `true` if the string contains the specified substring; + * returns `false` otherwise. */ bool IsSubStr(const std::string& str, const std::string& sub); /** * @ingroup StringOperation - * @brief Get the first sub_str between `left` and `right`. + * @brief Obtains the first substring between the substrings specified + * by `left` and `right`. * - * @param str Base string. - * @param left Specified left string. - * @param right Specified right string. - * @param sub Target `std::string` object to store the result string. - * @return Return the right string pos, if failed return string::npos. + * @param str Indicates the base string. + * @param left Indicates the left string. + * @param right Indicates the right string. + * @param sub Indicates the `std::string` object to store the result string. + * @return Returns `pos` if the operation is successful; + * returns `string::npos` otherwise. */ std::string::size_type GetFirstSubStrBetween(const std::string& str, const std::string& left, const std::string& right, std::string& sub); /** * @ingroup StringOperation - * @brief Get all of the sub strings between `left` and `right`. + * @brief Obtains all of the substrings between the substrings specified + * by `left` and `right`. * - * @param str Base string. - * @param left Specified left string. - * @param right Specified right string. - * @param sub Target `std::vector` object to store all of the result strings. + * @param str Indicates the base string. + * @param left Indicates the left string. + * @param right Indicates the right string. + * @param sub Indicates the `std::vector` object to store all the result strings. */ void GetSubStrBetween(const std::string& str, const std::string& left, const std::string& right, std::vector& sub); /** * @ingroup StringOperation - * @brief Judge if the `first`'s letter is same with `second`. + * @brief Checks whether two strings are equal. * - * @param first First input string. - * @param second Second input string. - * @note Case-insensitive. + * @param first Indicates the first string to check. + * @param second Indicates the second string to check. + * @note The string is case-insensitive. */ bool IsSameTextStr(const std::string& first, const std::string& second); /** * @ingroup StringOperation - * @brief Judge if all of the characters in `str` are ASCII encoded. + * @brief Checks whether all characters in a string are ASCII encoded. * - * @param str Base string. - * @return Return true if all are ASCII encoded, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are ASCII encoded; + * returns `false` otherwise. */ bool IsAsciiString(const std::string& str); #ifndef IOS_PLATFORM /** * @ingroup StringOperation - * @brief Convert a string from UTF-16 to UTF-8 encoded. + * @brief Converts a string from UTF-16 to UTF-8 encoded. * - * @param str16 Input `std::u16string` object. - * @return If converting failed, return an empty `std::string` object. + * @param str16 Indicates a `std::u16string` object. + * @return Returns an empty `std::string` object if the operation fails. */ std::string Str16ToStr8(const std::u16string& str16); /** * @ingroup StringOperation - * @brief Convert a string from UTF-8 to UTF-16 encoded. + * @brief Converts a string from UTF-8 to UTF-16 encoded. * - * @param str Input `std::string` object. - * @return If converting failed, return an empty `std::u16string` object. + * @param str Indicates a `std::string` object. + * @return Returns an empty `std::u16string` object if the operation fails. */ std::u16string Str8ToStr16(const std::string& str); #endif diff --git a/base/include/thread_ex.h b/base/include/thread_ex.h index 7482134083a744e3f3bc543783829022023cc21c..242b9781a4a8fabd022a702090bbf8bd73b6260c 100644 --- a/base/include/thread_ex.h +++ b/base/include/thread_ex.h @@ -16,7 +16,7 @@ /** * @file thread_ex.h * - * @brief The file contains interfaces of the Thread class + * @brief Provides interfaces of the Thread class * implemented in c_utils. */ @@ -47,77 +47,81 @@ constexpr int INVALID_PTHREAD_T = -1; constexpr int MAX_THREAD_NAME_LEN = 15; /** - * @brief A thread class provided by c_utils, include functions such as - * creating threads and getting thread ID. + * @brief Provides interfaces for creating a thread + * and obtaining a thread ID. */ class Thread { public: /** - * @brief Construct a Thread object, but does not start the thread. + * @brief A constructor used to create a Thread object, without + * starting the thread. */ Thread(); virtual ~Thread(); /** - * @brief Create and start a child thread, and execute Run() in a loop. - * Loop stops when Run() returns false or notifies to exit by - * `NotifyExitSync()` or `NotifyExitAsync()` from another thread. + * @brief Creates and starts a child thread, and executes + * Run() in a loop. + * The loop stops when Run() returns false or it is notified + * to exit by `NotifyExitSync()` or `NotifyExitAsync()` from another thread. * - * @param name The thread name. - * @param priority Thread priority. - * @param stack The size of the thread stack. - * @return Return OK if the call is successful; - * return INVALID_OPERATION when the thread already exists; - * return UNKNOWN_ERROR when thread creation fails. - * @see NotifyExitSync() NotifyExitAsync() + * @param name Indicates the name of the thread. + * @param priority Indicates the thread priority. + * @param stack Indicates the size of the thread stack. + * @return Returns OK if the call is successful; + * returns INVALID_OPERATION if the thread already exists; + * returns UNKNOWN_ERROR if the thread creation fails. + * @see {@link NotifyExitSync()} or {@link NotifyExitAsync()} */ ThreadStatus Start(const std::string& name, int32_t priority = THREAD_PROI_NORMAL, size_t stack = 0); /** - * @brief Synchronously notify this Thread object to exit. + * @brief Synchronously instructs this Thread object to exit. * - * The current thread is blocked, waiting for the child thread to finish. + * This method can be called only by another thread to instruct this + * Thread object to exit. The calling thread will be blocked until this + * Thread object exits. */ ThreadStatus NotifyExitSync(); /** - * @brief Asynchronously notify this Thread object to exit. + * @brief Asynchronously instructs this Thread object to exit. * - * That is, whether the child thread exits does not block - * the current thread. Notifies the child thread to stop - * and the current thread to continue running. + * This method can be called only by another thread to instruct this + * Thread object to exit. However, the calling thread will not be blocked + * when this Thread object exits. */ virtual void NotifyExitAsync(); /** - * @brief Determine whether the thread is ready. + * @brief Checks whether the thread is ready. */ virtual bool ReadyToWork(); /** - * @brief Get the flag of the thread exitPending. + * @brief Checks whether there is any thread waiting for exit. * - * If the flag is true, other waiting threads who have called - * `NotifyExitSync()` are woken up when the current thread - * finishes running and exits. + * If true is returned, the waiting threads who have called + * `NotifyExitSync()` will be woken up when the current thread finishes + * running and exits. * - * @return Returns true, indicating that another thread may be - * blocking to wait for the current thread to complete; - * Otherwise return false. + * @return Returns true if there is any thread that is + * blocked to wait for the current thread to exit. + * Returns false otherwise. */ bool IsExitPending() const; /** - * @brief Determine whether the thread is running. + * @brief Checks whether the thread is running. * - * @return Return true if the thread is running, - * otherwise, return false. + * @return Returns true if the thread is running; + * returns false otherwise. */ bool IsRunning() const; /** - * @brief Get the thread ID. + * @brief Obtains the thread ID. */ pthread_t GetThread() const { return thread_; } @@ -135,7 +139,7 @@ private: std::condition_variable cvThreadExited_; ThreadStatus status_; volatile bool exitPending_; - volatile bool running_; // flag of thread runing + volatile bool running_; // flag of thread running }; } // namespace OHOS diff --git a/base/include/thread_pool.h b/base/include/thread_pool.h index 1559097698c1602294b19af5a9e422430e320338..f522724a684edc72ee2fe4d203e20eed69db23cb 100644 --- a/base/include/thread_pool.h +++ b/base/include/thread_pool.h @@ -27,78 +27,80 @@ namespace OHOS { /** - * @brief Give a thread-safe thread pool. + * @brief Provides interfaces for thread-safe thread pool operations. * - * The thread-safe is for threadpool itself not for the threads in pool. A task - * queue and a thread group are under control. Users add tasks to task queue. - * The thread group will execute the tasks in task queue. + * The thread-safe is for the thread pool, but not for the threads in the pool. + * A task queue and a thread group are under control. Users add tasks to the + * task queue, and the thread group executes the tasks in the task queue. */ class ThreadPool : public NoCopyable { public: typedef std::function Task; /** - * @brief Construct ThreadPool and name the threads in pool. + * @brief Creates a thread pool and names the threads in the pool. * - * @param name it will be set as a part the real name of threads in pool. - * The real name of threads in pool will be like: name + No. The thread - * name is a meaningful C language string, whose length is restricted to - * 16 characters, including the terminating null byte ('\0'). Please pay - * attention to the length of name here. For example, if the number of - * threads in pool is less than 10, the maximum length of name is 14. + * @param name Indicates the prefix of the names of the threads in pool. + * The names of threads in the pool are in the name + No format. + * The thread name is a meaningful C language string, whose length is + * restricted to 16 characters including the terminating null byte ('\0'). + * Pay attention to the name length when setting this parameter. + * For example, if the number of threads in the pool is less than 10, + * the name length cannot exceed 14 characters. */ explicit ThreadPool(const std::string &name = std::string()); ~ThreadPool() override; /** - * @brief Start a given number(threadsNum) of threads, which will execute - * the tasks in task queue. + * @brief Starts a given number of threads, which will execute + * the tasks in a task queue. * - * @param threadsNum A given number of threads to start. + * @param threadsNum Indicates the number of threads to start. */ uint32_t Start(int threadsNum); /** - * @brief Stop ThreadPool and wait all threads in pool to stop. + * @brief Stops the thread pool. */ void Stop(); /** - * @brief Add a Task to task queue. + * @brief Adds a task to the task queue. * - * If Start() has never been called, the Task will be executed immediately. + * If Start() has never been called, the task will be executed + * immediately. * - * @param f A Task to be added to task queue. + * @param f Indicates the task to add. */ void AddTask(const Task& f); /** - * @brief Set the maximum amount of tasks in task queue. + * @brief Sets the maximum number of tasks in the task queue. * - * @param maxSize The maximum amount of tasks in task queue. + * @param maxSize Indicates the maximum number of tasks to set. */ void SetMaxTaskNum(size_t maxSize) { maxTaskNum_ = maxSize; } // for testability /** - * @brief Get the maximum amount of tasks in task queue. + * @brief Obtains the maximum number of tasks in the task queue. */ size_t GetMaxTaskNum() const { return maxTaskNum_; } /** - * @brief Get the current amount of tasks in task queue. + * @brief Obtains the number of tasks in the task queue. */ size_t GetCurTaskNum(); /** - * @brief Get the current amount of threads in pool. + * @brief Obtains the number of threads in the pool. */ size_t GetThreadsNum() const { return threads_.size(); } /** - * @brief Get the name of ThreadPool. + * @brief Obtains the name of the thread pool. */ std::string GetName() const { return myName_; } private: - // tasks in the queue reach the maximum set by maxQueueSize, means thread pool is full load. + // If the number of tasks in the queue reaches the maximum set by maxQueueSize, the thread pool is full load. bool Overloaded() const; void WorkInThread(); // main function in each thread. - Task ScheduleTask(); // fetch a task from the queue and execute + Task ScheduleTask(); // fetch a task from the queue and execute it private: std::string myName_; diff --git a/base/include/timer.h b/base/include/timer.h index 9d04d7bc62d22501fe944189235f23d4a7cacdd2..acc760b4bbbbce46b1b95d5546c75d28c9df0853 100644 --- a/base/include/timer.h +++ b/base/include/timer.h @@ -30,22 +30,22 @@ namespace OHOS { namespace Utils { /** - * @brief This is a timer manager. + * @brief Implements a timer manager. * - * After "Timer" started, users can register several timed events, which can be - * continuous or once, to it. Some points need to be noticed:\n - * 1. Timer should be set up(via Setup()) before use, and shutdown + * After a timer is started, users can register several timed events, which + * can be continuous or one-shot, to it. Some points need to be noticed:\n + * 1. A timer must be set up (through Setup()) before use, and be shut down * (via Shutdown()) before its deconstruction.\n - * 2. Timer should be set up first and then shutdown. Avoid delegating them to - * different threads since it may cause multithreading problem.\n - * 3. Set up Timer again would not reset this Timer, but return - * `TIMER_ERR_INVALID_VALUE`. If a reset operation is required, shut Timer down - * first and then set it up.\n - * 4. Parameter in Shutdown() determines whether the thread in Timer would be - * detach or join(True(default) --> join; False --> detach). Detach operation - * would cause possible multithreading problems, thus is not recommended. If a + * 2. A timer must be set up first and then shut down. Avoid delegating a + * timer to different threads. Otherwise, multithreading issues may occur.\n + * 3. Setting up a timer again will not reset the timer, but return + * `TIMER_ERR_INVALID_VALUE`. If a reset operation is required, shut down + * the timer first and then set it up.\n + * 4. The parameter in Shutdown() determines whether the thread in the timer + * will be detached. A detach operation may cause possible + * multithreading problems, and is therefore not recommended. If a * detach operation is required, availability of related objects used in - * `thread_` should be guaranteed. + * `thread_` must be guaranteed. */ class Timer { public: @@ -55,58 +55,61 @@ public: public: /** - * @brief Construct Timer. + * @brief Creates a timer. * - * If performance-sensitive, change "timeoutMs" larger before Setup. - * "timeoutMs" default-value(1000ms), performance-estimate: occupy - * fixed-100us in every default-value(1000ms). + * In performance-sensitive scenarios, set `timeoutMs` to a + * greater value before timer setup based on your timed event setttings. The + * default value is 1000 ms. The timeout event requires 100 us to respond. * - * @param name Name for Timer. It is used as the name of thread in Timer. - * @param timeoutMs Time for waiting timer events. It is an integer in - * [-1, INT32MAX], but -1 and 0 is not recommended. -1 means waiting - * forever(until event-trigger). 0 means no waiting, which occupies too - * much cpu time. others means waiting(until event-trigger). + * @param name Indicates the name of the timer. It is used as the name + * of the thread in the timer. + * @param timeoutMs Indicates the duration for which the timer will wait. + * The value is an integer in [-1, INT32MAX], but `-1` and `0` are not + * recommended. `-1` means to wait indefinitely (until the timed event is + * triggered). `0` means not to wait, which occupies too much CPU time. */ explicit Timer(const std::string& name, int timeoutMs = 1000); virtual ~Timer() {} /** - * @brief Set up "Timer". + * @brief Sets up a timer. * - * Do not set up repeatly before shutdown. + * Do not set up a timer before shutting down the existing one. */ virtual uint32_t Setup(); /** - * @brief Shut down "Timer". + * @brief Shuts down this timer. * - * There are two modes to shut the "Timer" down: blocking and unblocking. - * Blocking mode will shut "Timer" down until all running events in "Timer" - * finished. If "timeoutMs" is set as -1, use unblocking mode to avoid - * deadloop. + * A timer can be shut down in blocking or unblocking mode. In blocking + * mode, the timer will be shut down only after all running events + * in the timer have finished. If `timeoutMs` is set to `-1`, use + * unblocking mode to avoid deadloop. * - * @param useJoin Shutdown mode. true means blocking. false means - * unblocking(not recommended). + * @param useJoin Specifies whether to use blocking mode. The value `true` + * means to use blocking mode, and `false` (not recommended) means + * the opposite. */ virtual void Shutdown(bool useJoin = true); /** - * @brief Regist timed events. + * @brief Registers timed events. * - * @param callback callback function of a timed event. - * @param interval interval time(ms) of a timed event. - * @param once continuity of a timed event. true means discontinuous. false - * means continuous. Default is false. - * @return return ID of a timed event. You can use it as parameter of - * Unregister(). + * @param callback Indicates the callback function of a timed event. + * @param interval Indicates the interval of a timed event, in ms. + * @param once Indicates whether the timed event is one-shot. + * The value `true` means that the timed event is one-shot, + * and `false` means the opposite. The default value is `false`. + * @return Returns the ID of a timed event. You can use it as the + * parameter of Unregister(). * @see Unregister */ uint32_t Register(const TimerCallback& callback, uint32_t interval /* ms */, bool once = false); /** - * @brief Delete a timed events. + * @brief Deletes a timed event. * - * @param timerId ID of the timed event need to be deleted. Users can get - * it by Register(). + * @param timerId Indicates the ID of the timed event to delete. + * It can be obtained through Register(). * @see Register */ void Unregister(uint32_t timerId); @@ -123,7 +126,7 @@ private: private: struct TimerEntry { - uint32_t timerId; // unique id + uint32_t timerId; // Unique ID. uint32_t interval; // million second TimerCallback callback; bool once; diff --git a/base/include/unique_fd.h b/base/include/unique_fd.h index 0bc90d90d669d95b440c67174a9ae0d46e855b61..f5af32fe2f1307565a1ab3800785a2b53859f382 100644 --- a/base/include/unique_fd.h +++ b/base/include/unique_fd.h @@ -16,10 +16,11 @@ /** * @file unique_fd.h * - * @brief Provide management of file descriptor implemented in c_utils. + * @brief Provides APIs to manage file descriptors (FDs) implemented in c_utils. * - * Include Manager class UniqueFdAddDeletor, default Deleter class - * DefaultDeleter and related global operator overload functions. + * The manager class `UniqueFdAddDeletor`, + * the default deleter class `DefaultDeleter`, + * and related global overloaded operator functions are provided. */ #ifndef UNIQUE_FD_H #define UNIQUE_FD_H @@ -29,21 +30,22 @@ namespace OHOS { /** - * @brief Default implement of Deleter, including a static function to close the fd. + * @brief Provides the default implementation for a deleter, + * including a static function to close FDs. * - * Deleter is used for closing the file descriptor. Developer could implement - * another Deleter to deal with different scenarios./n `Deleter::Close()` will - * call when a UniqueFdAddDeletor object release the management of an fd, and - * there's no any other UniqueFdAddDeletor objects to take over it. + * The deleter is used for closing FDs. You can implement a deleter to + * deal with a different scenario. When `Deleter::Close()` is called to enable + * a `UniqueFdAddDeletor` object to release the management of an FD, + * the FD can no longer be taken over by other `UniqueFdAddDeletor` objects. */ class DefaultDeleter { public: /** - * @brief Default function to close fd. + * @brief Default function to close an FD. * - * Call `close()` if the input `fd` is valid(>=0). + * Call `close()` if the input FD is valid (greater than or equal to 0). * - * @param fd Input file descriptor. + * @param fd Indicates an FD. */ static void Close(int fd) { @@ -69,15 +71,15 @@ template bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs); /** - * @brief A file descriptor manager. + * @brief Defines an FD manager. * - * To take the unique management of a file descriptor, avoiding double close - * issue. Double close issue may wrongly close the fd which is just opened./n - * The management of an fd can be delivered between different UniqueFdAddDeletor - * objects. An fd will be closed if there's no UniqueFdAddDeletor take over the - * management of it. + * To ensure unique management on an FD, avoid the double-close issue, + * which may cause a file to be incorrectly closed./n + * The management of an FD can be delivered between `UniqueFdAddDeletor` + * objects. An FD will be closed if no `UniqueFdAddDeletor` object is available + * to take over its management. * - * @tparam Deleter Specified Deletor. + * @tparam Deleter Indicates a deleter. * @see DefaultDeleter */ template @@ -96,9 +98,9 @@ class UniqueFdAddDeletor final { public: /** - * @brief Construct UniqueFdAddDeletor with managed fd. + * @brief Creates a `UniqueFdAddDeletor` object to manage an FD. * - * @param value Fd to be managed. + * @param value Indicates the FD to be managed. */ explicit UniqueFdAddDeletor(const int& value) : fd_(value) @@ -106,7 +108,8 @@ public: } /** - * @brief Construct UniqueFdAddDeletor with managed fd of -1. + * @brief Constructor used to create a `UniqueFdAddDeletor` object + * with the FD set to `-1`. */ UniqueFdAddDeletor() : fd_(-1) @@ -114,19 +117,18 @@ public: } /** - * @brief Deconstructor. + * @brief Destructor used to destroy this `UniqueFdAddDeletor` object. * - * `UniqueFdAddDeletor::Reset(-1)` will call to close the fd - * and set it to -1. + * This function is used to close the FD and set the FD to `-1`. */ ~UniqueFdAddDeletor() { Reset(-1); } /** - * @brief Release the management of current fd, set it to -1. + * @brief Releases the management on the current FD and sets it to `-1`. * - * @return Return the original fd before release. - * @note Released fd need to be taken over by another UniqueFdAddDeletor - * object, otherwise it must be closed manually. + * @return Returns the original FD before release. + * @note The released FD needs to be taken over by another + * `UniqueFdAddDeletor` object; otherwise, it must be closed manually. */ int Release() { @@ -135,22 +137,24 @@ public: return tmp; } - // this is dangerous, when you use it , you should know it, donot operator on the ret + // this is dangerous, when you use it , you should know it, + // do not operator on the ret /** - * @brief Cast operator overload function. + * @brief An overloaded cast operator function. * - * E.g. This function will call when pass UniqueFdAddDeletor object to - * function who requires a parameter of `int`. + * This function will be called when passing a `UniqueFdAddDeletor` object + * to a function that requires a parameter of `int`. * - * @return Return current fd under management. + * @return Returns the current FD under management. */ operator int() const { return Get(); } // NOLINT - // this is dangerous, when you use it , you should know it, donot operator on the ret + // this is dangerous, when you use it , you should know it, do not operator + // on the ret /** - * @brief Get current fd under management, but not release it. + * @brief Obtains the current FD under management, without releasing it. * - * @return Return current fd under management. + * @return Returns the current FD. */ int Get() const { @@ -159,10 +163,10 @@ public: // we need move fd from one to another /** - * @brief Move constuctor. Used for delivering fd between UniqueFdAddDeletor - * objects. + * @brief Move constructor used to deliver the management of an FD from a + * `UniqueFdAddDeletor` object to this object. * - * @param rhs Source UniqueFdAddDeletor + * @param rhs Indicates the source `UniqueFdAddDeletor` object. */ UniqueFdAddDeletor(UniqueFdAddDeletor&& rhs) { @@ -171,13 +175,14 @@ public: } /** - * @brief Move assignment operator overload function. Used for delivering fd - * between UniqueFdAddDeletor objects. + * @brief Overloaded move assignment operator function used to deliver the + * management of an FD from a `UniqueFdAddDeletor` object to this object. * - * @param rhs Source UniqueFdAddDeletor - * @return This object. - * @note Fd of this object will be closed, then this object will take over - * the fd managed by `rhs`. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. + * @return Returns this `UniqueFdAddDeletor` object. + * @note The current FD manged by this `UniqueFdAddDeletor` object will be + * closed, and this object will take over + * the FD originally managed by `rhs`. */ UniqueFdAddDeletor& operator=(UniqueFdAddDeletor&& rhs) { @@ -187,12 +192,13 @@ public: } /** - * @brief Equal operator overload function. + * @brief Checks whether the FD managed by this object and that managed by + * the source object are equal. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if equal, otherwise return false. + * @return Returns `true` if the two FDs are equal; returns `false` + * otherwise. */ bool operator==(const int& rhs) const { @@ -200,12 +206,13 @@ public: } /** - * @brief Not-equal operator overload function. + * @brief Checks whether the FD managed by this object and that managed by + * the source object are not equal. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if not equal, otherwise return false. + * @return Returns `true` if the two FDs are not equal; returns `false` + * otherwise. */ bool operator!=(const int& rhs) const { @@ -213,13 +220,13 @@ public: } /** - * @brief Equal-or-Greater-than operator overload function. + * @brief Checks whether the FD managed by this object is greater than or + * equal to that managed by the source object. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if equal to or greater than `rhs`, - * otherwise return false. + * @return Returns `true` if FD managed by this object is greater than or + * equal to that managed by the source object; returns `false` otherwise. */ bool operator>=(const int& rhs) const { @@ -227,13 +234,13 @@ public: } /** - * @brief Greater-than operator overload function. + * @brief Checks whether the FD managed by this object is greater than that + * managed by the source object. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if greater than `rhs`, - * otherwise return false. + * @return Returns `true` if FD managed by this object is greater than that + * managed by the source object; returns `false` otherwise. */ bool operator>(const int& rhs) const { @@ -241,13 +248,13 @@ public: } /** - * @brief Equal-or-Less-than operator overload function. + * @brief Checks whether the FD managed by this object is less than or equal + * to that managed by the source object. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if equal to or less than `rhs`, - * otherwise return false. + * @return Returns `true` if FD managed by this object is less than or equal + * to that managed by the source object; returns `false` otherwise. */ bool operator<=(const int& rhs) const { @@ -255,13 +262,13 @@ public: } /** - * @brief Less-than operator overload function. + * @brief Checks whether the FD managed by this object is less than that + * managed by the source object. * - * Compare of the `rhs` and the fd managed by this object. + * @param rhs Indicates the source `UniqueFdAddDeletor` object. * - * @param rhs Input value. - * @return Return true if less than `rhs`, - * otherwise return false. + * @return Returns `true` if FD managed by this object is less than that + * managed by the source object; returns `false` otherwise. */ bool operator<(const int& rhs) const { @@ -285,14 +292,14 @@ private: }; /** - * @brief Global Equal operator overload function. +* @brief Checks whether the FD managed by two objects (specified by `lhs` and +* `rhs` respectively) are equal. +* + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * Compare of the `lhs` and the fd managed by `rhs`. - * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. - * @return Return true if equal, otherwise return false. + * @return Returns `true` if the two FDs are equal; returns `false` otherwise. * @see DefaultDeleter */ template @@ -302,14 +309,15 @@ bool operator==(const int& lhs, const UniqueFdAddDeletor& rhs) } /** - * @brief Global Not-equal operator overload function. - * - * Compare of the `lhs` and the fd managed by `rhs`. +* @brief Checks whether the FD managed by two objects (specified by `lhs` and +* `rhs` respectively) are not equal. +* + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. - * @return Return true if not equal, otherwise return false. + * @return Returns `true` if the two FDs are not equal; returns `false` + * otherwise. * @see DefaultDeleter */ template @@ -319,16 +327,16 @@ bool operator!=(const int& lhs, const UniqueFdAddDeletor& rhs) } /** - * @brief Global Equal-or-Greater-than operator overload function. + * @brief Checks whether the FD managed by `lhs` is greater than or equal to + * that managed by `rhs`. * - * Compare of the `lhs` and the fd managed by `rhs`. + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. + * @return Returns `true` if the FD managed by `lhs` is greater than or equal to + * that managed by `rhs`; returns `false` otherwise. * @see DefaultDeleter - * @return Return true if `lhs` is equal to - * or greater than fd managed by `rhs`. */ template bool operator>=(const int& lhs, const UniqueFdAddDeletor& rhs) @@ -337,15 +345,16 @@ bool operator>=(const int& lhs, const UniqueFdAddDeletor& rhs) } /** - * @brief Global Greater-than operator overload function. + * @brief Checks whether the FD managed by `lhs` is greater than that + * managed by `rhs`. * - * Compare of the `lhs` and the fd managed by `rhs`. + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. + * @return Returns `true` if the FD managed by `lhs` is greater than that + * managed by `rhs`; returns `false` otherwise. * @see DefaultDeleter - * @return Return true if `lhs` is greater than fd managed by `rhs`. */ template bool operator>(const int& lhs, const UniqueFdAddDeletor& rhs) @@ -354,16 +363,16 @@ bool operator>(const int& lhs, const UniqueFdAddDeletor& rhs) } /** - * @brief Global Equal-or-Less-than operator overload function. + * @brief Checks whether the FD managed by `lhs` is less than or equal to that + * managed by `rhs`. * - * Compare of the `lhs` and the fd managed by `rhs`. + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. + * @return Returns `true` if the FD managed by `lhs` is less than or equal to + * that managed by `rhs`; returns `false` otherwise. * @see DefaultDeleter - * @return Return true if `lhs` is equal to - * or less than fd managed by `rhs`. */ template bool operator<=(const int& lhs, const UniqueFdAddDeletor& rhs) @@ -372,15 +381,16 @@ bool operator<=(const int& lhs, const UniqueFdAddDeletor& rhs) } /** - * @brief Global Equal-or-Greater-than operator overload function. + * @brief Checks whether the FD managed by `lhs` is less than that + * managed by `rhs`. * - * Compare of the `lhs` and the fd managed by `rhs`. + * @tparam Deleter Indicates a deleter. + * @param lhs Indicates the first `UniqueFdAddDeletor` object. + * @param rhs Indicates the second `UniqueFdAddDeletor` object. * - * @tparam Deleter Specified Deletor. - * @param lhs Input value. - * @param rhs Input UniqueFdAddDeletor object. + * @return Returns `true` if the FD managed by `lhs` is less than that + * managed by `rhs`; returns `false` otherwise. * @see DefaultDeleter - * @return Return true if `lhs` is less than fd managed by `rhs`. */ template bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs)