diff --git a/base/include/unique_fd.h b/base/include/unique_fd.h index 2ba27bfdb69cf532b235ae6d05eac7c2508d02f3..2d7c7da52a035b9b8947b7f8e6e9d869e546efa6 100644 --- a/base/include/unique_fd.h +++ b/base/include/unique_fd.h @@ -13,14 +13,38 @@ * limitations under the License. */ +/** + * @file unique_fd.h + * + * @brief Provide management of file descriptor implemented in c_utils. + * + * Include Manager class UniqueFdAddDeletor, default Deleter class + * DefaultDeleter and related global operator overload functions. + */ #ifndef UNIQUE_FD_H #define UNIQUE_FD_H #include namespace OHOS { + +/** + * @brief Default implement of Deleter, including a static function to close the fd. + * + * 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. + */ class DefaultDeleter { public: + /** + * @brief Default function to close fd. + * + * Call `close()` if the input `fd` is valid(>=0). + * + * @param fd Input file descriptor. + */ static void Close(int fd) { if (fd >= 0) { @@ -44,9 +68,20 @@ bool operator<=(const int& lhs, const UniqueFdAddDeletor& rhs); template bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs); +/** + * @brief A file descriptor 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. + * + * @tparam Deleter Specified Deletor. + * @see DefaultDeleter + */ template class UniqueFdAddDeletor final { - friend bool operator==(const int& lhs, const UniqueFdAddDeletor& rhs); friend bool operator!=(const int& lhs, const UniqueFdAddDeletor& rhs); @@ -60,17 +95,39 @@ class UniqueFdAddDeletor final { friend bool operator< (const int& lhs, const UniqueFdAddDeletor& rhs); public: + /** + * @brief Construct UniqueFdAddDeletor with managed fd. + * + * @param value Fd to be managed. + */ explicit UniqueFdAddDeletor(const int& value) : fd_(value) { } + + /** + * @brief Construct UniqueFdAddDeletor with managed fd of -1. + */ UniqueFdAddDeletor() : fd_(-1) { } + + /** + * @brief Deconstructor. + * + * `UniqueFdAddDeletor::Reset(-1)` will call to close the fd + * and set it to -1. + */ ~UniqueFdAddDeletor() { Reset(-1); } - // get fd out + /** + * @brief Release the management of current fd, set 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. + */ int Release() { int tmp = fd_; @@ -79,20 +136,49 @@ public: } // this is dangerous, when you use it , you should know it, donot operator on the ret + /** + * @brief Cast operator overload function. + * + * E.g. This function will call when pass UniqueFdAddDeletor object to + * function who requires a parameter of `int`. + * + * @return Return 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 + /** + * @brief Get current fd under management, but not release it. + * + * @return Return current fd under management. + */ int Get() const { return fd_; } // we need move fd from one to another + /** + * @brief Move constuctor. Used for delivering fd between UniqueFdAddDeletor + * objects. + * + * @param rhs Source UniqueFdAddDeletor + */ UniqueFdAddDeletor(UniqueFdAddDeletor&& rhs) { int rhsfd = rhs.Release(); fd_ = rhsfd; } + /** + * @brief Move assignment operator overload function. Used for delivering fd + * between UniqueFdAddDeletor objects. + * + * @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`. + */ UniqueFdAddDeletor& operator=(UniqueFdAddDeletor&& rhs) { int rhsfd = rhs.Release(); @@ -100,30 +186,83 @@ public: return *this; } + /** + * @brief Equal operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if equal, otherwise return false. + */ bool operator==(const int& rhs) const { return fd_ == rhs; } + /** + * @brief Not-equal operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if not equal, otherwise return false. + */ bool operator!=(const int& rhs) const { return !(fd_ == rhs); } + + /** + * @brief Equal-or-Greater-than operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if equal to or greater than `rhs`, + * otherwise return false. + */ bool operator>=(const int& rhs) const { return fd_ >= rhs; } + /** + * @brief Greater-than operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if greater than `rhs`, + * otherwise return false. + */ bool operator>(const int& rhs) const { return fd_ > rhs; } + /** + * @brief Equal-or-Less-than operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if equal to or less than `rhs`, + * otherwise return false. + */ bool operator<=(const int& rhs) const { return fd_ <= rhs; } + /** + * @brief Less-than operator overload function. + * + * Compare of the `rhs` and the fd managed by this object. + * + * @param rhs Input value. + * @return Return true if less than `rhs`, + * otherwise return false. + */ bool operator<(const int& rhs) const { return fd_ < rhs; @@ -145,36 +284,104 @@ private: UniqueFdAddDeletor& operator=(const UniqueFdAddDeletor& rhs) = delete; }; +/** + * @brief Global Equal operator overload function. + * + * 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. + * @see DefaultDeleter + */ template bool operator==(const int& lhs, const UniqueFdAddDeletor& rhs) { return lhs == rhs.fd_; } +/** + * @brief Global Not-equal operator overload function. + * + * 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 not equal, otherwise return false. + * @see DefaultDeleter + */ template bool operator!=(const int& lhs, const UniqueFdAddDeletor& rhs) { return !(lhs == rhs.fd_); } +/** + * @brief Global Equal-or-Greater-than operator overload function. + * + * Compare of the `lhs` and the fd managed by `rhs`. + * + * @tparam Deleter Specified Deletor. + * @param lhs Input value. + * @param rhs Input UniqueFdAddDeletor object. + * @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) { return lhs >= rhs.fd_; } +/** + * @brief Global Greater-than operator overload function. + * + * Compare of the `lhs` and the fd managed by `rhs`. + * + * @tparam Deleter Specified Deletor. + * @param lhs Input value. + * @param rhs Input UniqueFdAddDeletor object. + * @see DefaultDeleter + * @return Return true if `lhs` is greater than fd managed by `rhs`. + */ template bool operator>(const int& lhs, const UniqueFdAddDeletor& rhs) { return lhs > rhs.fd_; } +/** + * @brief Global Equal-or-Less-than operator overload function. + * + * Compare of the `lhs` and the fd managed by `rhs`. + * + * @tparam Deleter Specified Deletor. + * @param lhs Input value. + * @param rhs Input UniqueFdAddDeletor object. + * @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) { return lhs <= rhs.fd_; } +/** + * @brief Global Equal-or-Greater-than operator overload function. + * + * Compare of the `lhs` and the fd managed by `rhs`. + * + * @tparam Deleter Specified Deletor. + * @param lhs Input value. + * @param rhs Input UniqueFdAddDeletor object. + * @see DefaultDeleter + * @return Return true if `lhs` is less than fd managed by `rhs`. + */ template bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs) {