Class IoBuffer

src/include/io_buffer.hpp:85–153

* @brief 动态分配、对齐 IO 缓冲区的 RAII 封装 * * @pre 无 * @post 缓冲区内存已正确分配并对齐，析构时自动释放 */

 * @post 缓冲区内存已正确分配并对齐，析构时自动释放
 */
class IoBuffer {
 public:
  /// IO 缓冲区的默认对齐大小（如页大小）
  static constexpr size_t kDefaultAlignment = 4096;

  /**
   * @brief 获取缓冲区数据与大小 (只读)
   * @return std::span<const uint8_t> 缓冲区数据的只读视图
   * @pre None
   * @post 返回指向缓冲区数据的常量 span
   */
  [[nodiscard]] auto GetBuffer() const -> std::span<const uint8_t>;

  /**
   * @brief 获取缓冲区数据与大小
   * @return std::span<uint8_t> 缓冲区数据的可变视图
   * @pre None
   * @post 返回指向缓冲区数据的 span
   */
  [[nodiscard]] auto GetBuffer() -> std::span<uint8_t>;

  /**
   * @brief 检查缓冲区是否有效
   * @return bool 有效则返回 true
   * @pre None
   * @post 返回缓冲区是否已分配且有效的状态
   */
  [[nodiscard]] auto IsValid() const -> bool;

  /**
   * @brief 创建此缓冲区的 DmaRegion 视图
   *
   * @param v2p 地址转换函数（默认：恒等映射）
   * @return 描述此缓冲区内存的 DmaRegion
   *
   * @pre IsValid() == true
   * @post 返回的 DmaRegion 不拥有内存所有权
   */
  [[nodiscard]] auto ToDmaRegion(VirtToPhysFunc v2p = IdentityVirtToPhys) const
      -> DmaRegion;

  /// @name 构造/析构函数
  /// @{
  IoBuffer() = default;

  /**
   * @brief 构造函数
   * @param  size 缓冲区大小
   * @param  alignment 对齐要求
   * @pre size > 0, alignment 必须是 2 的幂
   * @post 缓冲区内存已正确分配并对齐
   */
  explicit IoBuffer(size_t size, size_t alignment = kDefaultAlignment);

  ~IoBuffer();

  IoBuffer(const IoBuffer&) = delete;
  auto operator=(const IoBuffer&) -> IoBuffer& = delete;