feat: theme abstractions

Author: Charliechen114514

base/include/base/singleton/simple_singleton.hpp

@@ -0,0 +1,72 @@
+/**
+ * @file    base/include/base/singleton/simple_singleton.hpp
+ * @brief   Simple thread-safe singleton using Meyer's singleton pattern.
+ *
+ * Provides a minimal singleton implementation that leverages C++11 guarantees
+ * for thread-safe static local variable initialization.
+ *
+ * @author  N/A
+ * @date    N/A
+ * @version N/A
+ * @since   N/A
+ * @ingroup none
+ */
+
+#pragma once
+
+namespace cf {
+
+/**
+ * @brief  Simple thread-safe singleton using Meyer's singleton pattern.
+ *
+ * Provides a minimal singleton implementation that leverages C++11 guarantees
+ * for thread-safe static local variable initialization. The instance is created
+ * on first access and destroyed on application exit.
+ *
+ * @tparam SingleTargetClass Type of the singleton instance.
+ *
+ * @ingroup none
+ *
+ * @note   Thread-safe. C++11 guarantees thread-safe initialization of function-local
+ *         static variables.
+ *
+ * @warning None
+ *
+ * @code
+ * class MyClass {
+ * public:
+ *     void doSomething() {}
+ * };
+ *
+ * using MySingleton = SimpleSingleton<MyClass>;
+ * MySingleton::instance().doSomething();
+ * @endcode
+ */
+template <typename SingleTargetClass> class SimpleSingleton {
+  public:
+    /**
+     * @brief  Returns the singleton instance.
+     *
+     * Creates the instance on first call, subsequent calls return the same
+     * instance.
+     *
+     * @return Reference to the singleton instance.
+     * @throws None
+     * @note   Thread-safe initialization guaranteed by C++11 standard.
+     * @warning None
+     * @since  N/A
+     * @ingroup none
+     */
+    static SingleTargetClass& instance() {
+        static SingleTargetClass target;
+        return target;
+    }
+
+  private:
+    SimpleSingleton(const SimpleSingleton&) = delete;
+    SimpleSingleton& operator=(const SimpleSingleton&) = delete;
+    SimpleSingleton(SimpleSingleton&&) = delete;
+    SimpleSingleton& operator=(SimpleSingleton&&) = delete;
+};
+
+} // namespace cf

base/include/base/singleton/singleton.hpp

@@ -0,0 +1,122 @@
+/**
+ * @file    base/include/base/singleton/singleton.hpp
+ * @brief   Thread-safe singleton with explicit initialization.
+ *
+ * Provides a singleton implementation that requires explicit initialization
+ * via init() before accessing the instance. Uses std::call_once for
+ * thread-safe initialization.
+ *
+ * @author  N/A
+ * @date    N/A
+ * @version N/A
+ * @since   N/A
+ * @ingroup none
+ */
+
+#pragma once
+#include <memory>
+#include <mutex>
+#include <stdexcept>
+
+namespace cf {
+
+/**
+ * @brief  Thread-safe singleton with explicit initialization.
+ *
+ * Provides a singleton implementation that requires explicit initialization
+ * via init() before accessing the instance. This pattern allows for
+ * parameterized construction and explicit control over initialization timing.
+ *
+ * @tparam T Type of the singleton instance.
+ *
+ * @ingroup none
+ *
+ * @note   Thread-safe. Uses std::call_once for initialization.
+ *
+ * @warning Accessing instance() before calling init() throws std::logic_error.
+ *
+ * @code
+ * class MyClass {
+ * public:
+ *     MyClass(int value) : value_(value) {}
+ *     void doSomething() {}
+ * private:
+ *     int value_;
+ * };
+ *
+ * using MySingleton = Singleton<MyClass>;
+ * MySingleton::init(42);
+ * MySingleton::instance().doSomething();
+ * @endcode
+ */
+template <typename T> class Singleton {
+  public:
+    /**
+     * @brief  Initializes the singleton with the provided arguments.
+     *
+     * Constructs the singleton instance once, subsequent calls return the
+     * existing instance. Thread-safe via std::call_once.
+     *
+     * @tparam  Args Types of constructor arguments.
+     * @param[in] args Arguments to forward to T's constructor.
+     * @return        Reference to the initialized singleton instance.
+     * @throws        None
+     * @note          Thread-safe initialization guaranteed by std::call_once.
+     * @warning       Calling init() twice has no effect; the first instance is kept.
+     * @since         N/A
+     * @ingroup       none
+     */
+    template <typename... Args>
+    static T& init(Args&&... args) {
+        std::call_once(flag_, [&] {
+            instance_.reset(new T(std::forward<Args>(args)...));
+        });
+        return *instance_;
+    }
+
+    /**
+     * @brief  Returns the singleton instance.
+     *
+     * Requires that init() has been called first.
+     *
+     * @return Reference to the singleton instance.
+     * @throws std::logic_error if init() has not been called.
+     * @note   None
+     * @warning Must call init() before accessing instance().
+     * @since  N/A
+     * @ingroup none
+     */
+    static T& instance() {
+        if (!instance_) {
+            throw std::logic_error("Singleton not initialized. Call init() first.");
+        }
+        return *instance_;
+    }
+
+    /**
+     * @brief  Resets the singleton instance.
+     *
+     * Destroys the current instance and allows re-initialization via init().
+     *
+     * @throws None
+     * @note   After calling reset(), init() must be called again before
+     *         accessing instance().
+     * @warning None
+     * @since  N/A
+     * @ingroup none
+     */
+    static void reset() { instance_.reset(); }
+
+    Singleton(const Singleton&) = delete;
+    Singleton& operator=(const Singleton&) = delete;
+
+  protected:
+    Singleton() = default;
+    virtual ~Singleton() = default;
+
+  private:
+    inline static std::unique_ptr<T> instance_ = nullptr;
+    inline static std::once_flag flag_;
+};
+
+} // namespace cf

base/include/base/weak_ptr/private/weak_ptr_internals.h

@@ -0,0 +1,103 @@
+/**
+ * @file    base/include/base/weak_ptr/private/weak_ptr_internals.h
+ * @brief   Internal implementation details for WeakPtr system.
+ *
+ * This header contains the internal implementation details for the WeakPtr
+ * system. External code should not directly include or depend on this file.
+ * WeakPtr and WeakPtrFactory share the WeakReferenceFlag to track liveness.
+ *
+ * @author  N/A
+ * @date    N/A
+ * @version N/A
+ * @since   N/A
+ * @ingroup none
+ */
+
+#pragma once
+
+#include <atomic>
+#include <memory>
+
+namespace cf {
+namespace internal {
+
+/**
+ * @brief  Shared flag tracking WeakPtr liveness state.
+ *
+ * The Owner (WeakPtrFactory) and all WeakPtr instances share the same
+ * WeakReferenceFlag instance. When the owner is destroyed (or explicitly
+ * calls InvalidateWeakPtrs), the alive_ flag is set to false, causing all
+ * WeakPtr::Get() calls to return nullptr.
+ *
+ * @ingroup none
+ *
+ * @note   The alive_ flag uses std::atomic<bool> for thread-safety.
+ *         Invalidate() and IsAlive() are thread-safe operations.
+ *
+ * @warning WeakPtr should only be used on the same thread where it was
+ *          created. The "check + dereference" two-step operation between
+ *          IsAlive() and actual access is not atomic.
+ *
+ * @code
+ * // Internal use only - created by WeakPtrFactory
+ * auto flag = std::make_shared<WeakReferenceFlag>();
+ * if (flag->IsAlive()) {
+ *     // Safe to access
+ * }
+ * flag->Invalidate();  // All WeakPtrs now return nullptr
+ * @endcode
+ */
+class WeakReferenceFlag {
+  public:
+    /// @brief Default constructor: creates a flag in the alive state.
+    WeakReferenceFlag() = default;
+
+    /// @brief Copy constructor: deleted. Flag is shared via shared_ptr.
+    WeakReferenceFlag(const WeakReferenceFlag&) = delete;
+
+    /// @brief Copy assignment: deleted.
+    WeakReferenceFlag& operator=(const WeakReferenceFlag&) = delete;
+
+    /// @brief Move constructor: deleted.
+    WeakReferenceFlag(WeakReferenceFlag&&) = delete;
+
+    /// @brief Move assignment: deleted.
+    WeakReferenceFlag& operator=(WeakReferenceFlag&&) = delete;
+
+    /**
+     * @brief  Checks if the owner is still alive.
+     *
+     * @return true if the owner is alive, false if invalidated.
+     * @throws None
+     * @note   Uses memory_order_acquire for proper synchronization.
+     * @warning None
+     * @since  N/A
+     * @ingroup none
+     */
+    [[nodiscard]] bool IsAlive() const noexcept {
+        return alive_.load(std::memory_order_acquire);
+    }
+
+    /**
+     * @brief  Marks the flag as invalid.
+     *
+     * After calling this method, all existing and future IsAlive() calls
+     * returns false.
+     *
+     * @throws None
+     * @note   Uses memory_order_release for proper synchronization.
+     * @warning None
+     * @since  N/A
+     * @ingroup none
+     */
+    void Invalidate() noexcept { alive_.store(false, std::memory_order_release); }
+
+  private:
+    std::atomic<bool> alive_{true};
+};
+
+/// @brief Shared pointer type for WeakReferenceFlag.
+using WeakReferenceFlagPtr = std::shared_ptr<WeakReferenceFlag>;
+
+} // namespace internal
+} // namespace cf