From 06d5e5872838bd1528493b62b4dc28d44b54aa47 Mon Sep 17 00:00:00 2001 From: Fabian Imhof Date: Sun, 9 Mar 2025 09:30:01 +0000 Subject: add doxygen comments to shared and unique pointer --- arch/x86_64/include/arch/stl/shared_pointer.hpp | 93 ++++++++++++++++++++++++- arch/x86_64/include/arch/stl/unique_pointer.hpp | 71 ++++++++++++++++++- 2 files changed, 161 insertions(+), 3 deletions(-) (limited to 'arch/x86_64/include') diff --git a/arch/x86_64/include/arch/stl/shared_pointer.hpp b/arch/x86_64/include/arch/stl/shared_pointer.hpp index 4a9dec5..80ca7fe 100644 --- a/arch/x86_64/include/arch/stl/shared_pointer.hpp +++ b/arch/x86_64/include/arch/stl/shared_pointer.hpp @@ -5,15 +5,33 @@ namespace teachos::arch::stl { + /** + * @brief A simple implementation of a shared pointer. + * + * This class provides reference counting and automatic resource management + * for dynamically allocated objects. + * + * @tparam T The type of the managed object. + */ template struct shared_pointer { + /** + * @brief Constructs a shared pointer. + * + * @param pointer Raw pointer to manage (default is nullptr). + */ explicit shared_pointer(T * pointer = nullptr) : pointer(pointer) , ref_count(new std::atomic(pointer != nullptr ? 1 : 0)) { } + /** + * @brief Copy constructor. + * + * @param other The shared_pointer to copy from. + */ shared_pointer(const shared_pointer & other) : pointer(other.pointer) , ref_count(other.ref_count) @@ -24,6 +42,11 @@ namespace teachos::arch::stl } } + /** + * @brief Move constructor. + * + * @param other The shared_pointer to move from. + */ shared_pointer(shared_pointer && other) noexcept : pointer(other.pointer) , ref_count(other.ref_count) @@ -32,6 +55,12 @@ namespace teachos::arch::stl other.ref_count = nullptr; } + /** + * @brief Copy assignment operator. + * + * @param other The shared_pointer to copy from. + * @return Reference to this shared_pointer. + */ shared_pointer & operator=(const shared_pointer & other) { if (this != &other) @@ -49,6 +78,12 @@ namespace teachos::arch::stl return *this; } + /** + * @brief Move assignment operator. + * + * @param other The shared_pointer to move from. + * @return Reference to this shared_pointer. + */ shared_pointer & operator=(shared_pointer && other) noexcept { if (this != &other) @@ -63,8 +98,14 @@ namespace teachos::arch::stl return *this; } + /** + * @brief Destructor. Cleans up resources if necessary. + */ ~shared_pointer() { cleanup(); } + /** + * @brief Releases ownership and deletes the object if necessary. + */ void cleanup() { if (pointer != nullptr && ref_count != nullptr && --(*ref_count) == 0) @@ -74,6 +115,11 @@ namespace teachos::arch::stl } } + /** + * @brief Resets the shared pointer with a new raw pointer. + * + * @param p New raw pointer (default is nullptr). + */ void reset(T * p = nullptr) { cleanup(); @@ -81,18 +127,43 @@ namespace teachos::arch::stl ref_count = new std::atomic(p != nullptr ? 1 : 0); } + /** + * @brief Swaps the contents of this shared pointer with another. + * + * @param other The shared_pointer to swap with. + */ void swap(shared_pointer & other) { std::swap(pointer, other.pointer); std::swap(ref_count, other.ref_count); } + /** + * @brief Dereference operator. + * + * @return Reference to the managed object. + */ T & operator*() const { return *pointer; } + /** + * @brief Member access operator. + * + * @return Pointer to the managed object. + */ T * operator->() const { return pointer; } + /** + * @brief Returns the raw pointer. + * + * @return Pointer to the managed object. + */ T * get() const { return pointer; } + /** + * @brief Returns the reference count. + * + * @return Number of shared_pointer instances managing the same object. + */ int use_count() const { if (pointer != nullptr) @@ -103,15 +174,33 @@ namespace teachos::arch::stl return 0; } + /** + * @brief Checks if this is the only shared pointer managing the object. + * + * @return True if the use count is 1, otherwise false. + */ bool unique() const { return use_count() == 1; } + /** + * @brief Checks if the shared pointer is not empty. + * + * @return True if the pointer is not null, otherwise false. + */ explicit operator bool() const { return pointer != nullptr; } private: - T * pointer; - std::atomic * ref_count; + T * pointer; ///< The managed object. + std::atomic * ref_count; ///< Reference count. }; + /** + * @brief Creates a shared pointer instance. + * + * @tparam T The type of object to allocate. + * @tparam Args Argument types for the constructor of T. + * @param args Arguments for the constructor of T. + * @return A shared_pointer instance managing a newly created object. + */ template shared_pointer make_shared(Args &&... args) { diff --git a/arch/x86_64/include/arch/stl/unique_pointer.hpp b/arch/x86_64/include/arch/stl/unique_pointer.hpp index 0ec3c38..08c862d 100644 --- a/arch/x86_64/include/arch/stl/unique_pointer.hpp +++ b/arch/x86_64/include/arch/stl/unique_pointer.hpp @@ -3,25 +3,56 @@ namespace teachos::arch::stl { + /** + * @brief A simple unique pointer implementation. + * + * @tparam T Type of the managed object. + */ template struct unique_pointer { + /** + * @brief Constructs a unique pointer. + * + * @param ptr Pointer to manage, default is nullptr. + */ explicit unique_pointer(T * ptr = nullptr) : pointer(ptr) { } + /** + * @brief Destructor that deletes the managed object. + */ ~unique_pointer() { delete pointer; } + /** + * @brief Deleted copy constructor to enforce unique ownership. + */ unique_pointer(const unique_pointer &) = delete; + + /** + * @brief Deleted copy assignment operator to enforce unique ownership. + */ unique_pointer & operator=(const unique_pointer &) = delete; + /** + * @brief Move constructor. + * + * @param other Unique pointer to move from. + */ unique_pointer(unique_pointer && other) noexcept : pointer(other.pointer) { other.pointer = nullptr; } + /** + * @brief Move assignment operator. + * + * @param other Unique pointer to move from. + * @return Reference to this unique pointer. + */ unique_pointer & operator=(unique_pointer && other) noexcept { if (this != &other) @@ -33,12 +64,32 @@ namespace teachos::arch::stl return *this; } + /** + * @brief Dereference operator. + * + * @return Reference to the managed object. + */ T & operator*() const { return *pointer; } + /** + * @brief Member access operator. + * + * @return Pointer to the managed object. + */ T * operator->() const { return pointer; } + /** + * @brief Gets the raw pointer. + * + * @return The managed pointer. + */ T * get() const { return pointer; } + /** + * @brief Releases ownership of the managed object. + * + * @return The raw pointer and sets internal pointer to nullptr. + */ T * release() { T * temp = pointer; @@ -46,18 +97,36 @@ namespace teachos::arch::stl return temp; } + /** + * @brief Resets the managed object. + * + * @param ptr New pointer to manage (default is nullptr). + */ void reset(T * ptr = nullptr) { delete pointer; pointer = ptr; } + /** + * @brief Swaps the managed object with another unique pointer. + * + * @param other Unique pointer to swap with. + */ void swap(unique_pointer & other) { std::swap(pointer, other.pointer); } private: - T * pointer; + T * pointer; ///< The managed pointer. }; + /** + * @brief Creates a unique pointer instance. + * + * @tparam T Type of the managed object. + * @tparam Args Argument types for T's constructor. + * @param args Arguments for T's constructor. + * @return A unique pointer managing a newly created T object. + */ template unique_pointer make_unique(Args &&... args) { -- cgit v1.2.3