行行宜行行

热爱风光、热爱新技术、踏出每一步，过好每一天！

MMapAux 模块技术文档

本文主要是基于我自己所做的日志系统所书写的一个简单技术文档，每一个小的模块我尽量整理成完整的逻辑，并且按时发布，mmap相关部分的理论知识我也还需要持续学习，个人的部分自我理解与学习整理已经发布在我的CSDN账号上。

1. 概述与简介

1.1 模块定位

  • 模块名称：内存映射文件辅助模块 (MMapAux)
  • 所属系统：日志系统核心组件
  • 功能定位：提供基于内存映射 (mmap) 的文件数据管理功能，用于高效地读写和管理日志数据

1.2 核心优势

  • 利用内存映射技术提高 I/O 效率，减少系统调用开销
  • 提供简单易用的接口进行数据操作
  • 自动管理内存映射的生命周期和容量扩展
  • 支持数据有效性验证和错误处理

1.3 应用场景

  • 高性能日志系统的数据持久化
  • 需要频繁读写的大文件数据管理
  • 跨进程数据共享场景
  • 对 I/O 性能敏感的应用场景

2. 设计原理与架构

2.1 核心设计理念

  • 基于内存映射 (mmap) 技术实现文件与内存的高效交互
  • 采用头部标记 (MmapHeader) 确保数据有效性和一致性
  • 自动容量管理机制，按需扩展映射空间
  • 资源管理遵循 RAII 原则，确保内存和文件资源正确释放

2.2 数据结构设计

struct MmapHeader {
    static constexpr uint32_t kMagic = 0xdeadbeef;  /// 魔数，用于验证数据有效性
    uint32_t magic;                                /// 标识文件格式
    uint32_t size;                                /// 当前数据大小
};

2.3 架构图

+-------------------+     +-------------------+     +-------------------+
|  Application      |<--->|    MMapAux Class   |<--->|     File System   |
|  (User Code)      |     |  (Memory Mapping)   |     |  (Physical File)  |
+-------------------+     +-------------------+     +-------------------+
         ^                               ^                               ^
         |                               |                               |
         +-------------------------------+-------------------------------+
                         |
               +---------------------------+
               |  Utils (File & System)  |
               +---------------------------+

3. 核心功能详解

3.1 内存映射管理

  • 映射创建：TryMap_() 方法实现文件到内存的映射

    主要的流程为;

    1. 打开或创建目标文件 调用CreateFileW()

      		/// 打开或创建目标文件
        FileHandlePtr file_handler(CreateFileW(
                file_path_.wstring().c_str(),      ///
                GENERIC_READ | GENERIC_WRITE,       /// 读写权限
                0,                                  /// 不共享
                nullptr,
                OPEN_ALWAYS,                    /// 如果文件存在则打开，如果不存在则创建
                FILE_ATTRIBUTE_NORMAL,
                nullptr));

        /// 打开是否成功
        if (file_handler.get() == INVALID_HANDLE_VALUE) {
            return false;
        }

      1. 在现有获取的文件句柄上创建文件映射

        	/// 创建文件映射
        FileHandlePtr file_mapping_;
        file_mapping_.reset(CreateFileMapping(
                file_handler.get(),             /// CreateFileW获得的文件句柄
                nullptr,             /// 安全属性
                PAGE_READWRITE,              ///  映射页的保护模式
                0,                  ///  映射文件的最高位
                capacity_,           ///  映射文件的最低位
                nullptr                          /// 映射对象的名称，用于跨进程共享
        ));
        if (!file_mapping_.get()) {
            return false;
        }

      1. 将映射对象映射到进程的具体地址

        handle_ = MapViewOfFile(file_mapping_.get(), FILE_MAP_ALL_ACCESS, 0, 0, capacity);

         

  • 映射释放：Unmap_() 方法释放已映射的内存

调用 UnmapViewOfFile 解除内存区域与文件的映射关系. 解除映射后，handle_ 将置为 nullptr.

  void MMapAux::Unmap_() {
        if (handle_) {
            UnmapViewOfFile(handle_);
        }
        handle_ = nullptr;
    }
  • 数据同步：Sync_() 方法将内存数据同步到磁盘
/// 调用 FlushViewOfFile 将指定范围的内存内容强制写入磁盘
 void MMapAux::Sync_() {
        if (handle_) {
            /// 强制将内存内容写入磁盘
            FlushViewOfFile(handle_, capacity_);
        }
    }

 

3.2 数据操作功能

  • 数据写入：Push() 方法向映射区域添加数据

    使用memcpy()将需要添加的数据拷贝至真实的数据地址处，在添加数据之前也需要验证数据的有效性与缓冲区的有效性

     void MMapAux::Push(const void *data, size_t size) {
        if (IsValid_()) {
            size_t new_size = Size() + size;
            EnsureCapacity_(new_size);
            memcpy(Data() + Size(), data, size);
        }
    }

     

  • 数据读取：Data() 方法获取数据存储起始地址
/**
* @brief 获取真实的数据地址
* @note 获取真实的数据地址需要从结构头跳过头部长度
*/
uint8_t *MMapAux::Data() const {
    if (!IsValid_()) {
        return nullptr;
    }
    /// 返回真实的数据的地址
    return static_cast<uint8_t *>(handle_) + sizeof(MMapHeader);
}

 

  • 数据清空：Clear() 方法重置数据大小，由于mmap头部存放了映射区的空间大小的字段 mmap_size_，重置数据大小则直接将这个值置为0即可。
  • 大小调整：Resize() 方法修改当前数据大小
	/**
    * @brief 重置mmap大小
    * @note  根据获取到的最新有效值，进行重设，并且更新头部中的mmap_size_
    */
    void MMapAux::Resize(size_t new_size) {
        if (!IsValid_()) {
            return;
        }
        EnsureCapacity_(new_size);
        Header_()->mmap_size_ = new_size;
    }

 

3.3 容量管理

  • 容量预留：Reserve_() 方法预分配映射空间（底层起始还是使用TryMap_())

  • 容量扩展：EnsureCapacity_() 方法自动扩展容量，扩展策略是按照页大小进行扩展，即

    void MMapAux::EnsureCapacity_(size_t new_size) {
        size_t real_size = new_size + sizeof(MMapHeader);
        if (real_size <= capacity_) {
            return;
        }
        auto dst_capacity_ = capacity_;
        while (dst_capacity_ < real_size) {
            dst_capacity_ += GetPageSize();         /// 容量不够进行拓展
        }
        /// 分配dst_capacity_大小的空间
        Reserve_(dst_capacity_);
    }

    因为整个系统中，使用双缓存的形式来保证接受数据，那么在容量不够时的扩容策略是根据不同的平台获取对应的页表大小，然后按照页表进行扩展。

  • 容量查询：Capacity_() 方法获取当前映射容量

3.4 状态查询

  • 数据大小：Size() 方法获取当前数据大小
  • 有效性检查：IsValid_() 方法验证数据有效性，在进行常规的数据操作之前都需要判断数据的有效性，通过对比mmapHeader头部的魔数与最初的魔数是否相等来判断。
	/**
     * @brief 验证映射有效性
     * @return 有效返回true，否则返回false
     * @note 通过检查魔数和映射状态验证
     */
    bool MMapAux::IsValid_() const {
        MMapHeader* header = Header_();
        if (!header) {
            return false;
        }
        /// 检查魔数是否被修改，验证是否有效
        return header->magic_ == MMapHeader::kMagic;
    }

 

  • 使用比率：GetRatio() 方法获取空间使用比率，这里是用已经使用的大小与 capacity_的比值计算
double MMapAux::GetRatio() const {
        if (!IsValid_()) {
            return 0.0;
        }
        return static_cast<double>(Size()) / (capacity_ - sizeof(MMapHeader));
    }

 

4. 数据接口

4.1 构造与析构

4.2 数据操作接口

4.3 状态查询接口

具体的实现细节由源码给出

5. 实现细节

5.1 内存映射实现

  • 使用平台相关的 mmap 系统调用实现内存映射
  • 映射区域包含头部 (MmapHeader) 和数据区两部分
  • 映射大小按系统页大小对齐，确保内存访问效率

5.2 容量管理策略

  • 初始容量：默认 512KB (kDefaultCapacity)
  • 扩展策略：当需要更多空间时，按页大小逐步扩展
  • 容量对齐：所有容量值按系统页大小对齐 (GetValidCapacity_)

5.3 数据一致性保证

  • 头部魔数 (kMagic) 验证数据有效性
  • 同步操作 (Sync_) 确保数据持久化
  • 异常处理机制防止数据损坏

5.4 平台兼容性

  • 依赖 utils/file_util.h 和 utils/sys_util.h 提供平台抽象
  • GetPageSize() 获取系统页大小，确保跨平台一致性
  • 需根据不同平台实现具体的 mmap 和文件操作接口

6. 使用实例

6.1 基本使用流程

#include "mmap/mmap_aux.h"
#include <cstring>
#include <iostream>

int main() {
    /// 1. 创建MMapAux实例
    logger::MMapAux mmap("./log.mmap");
    
    /// 2. 检查是否有效
    if (!mmap.IsValid()) {
        std::cerr << "Mmap initialization failed!" << std::endl;
        return 1;
    }
    
    /// 3. 写入数据
    const char* message = "Hello, MMapAux!";
    mmap.Push(message, strlen(message) + 1);
    
    /// 4. 读取数据
    uint8_t* data = mmap.Data();
    if (data) {
        std::cout << "Data read from mmap: " << data << std::endl;
    }
    
    /// 5. 查看使用状态
    std::cout << "Data size: " << mmap.Size() << " bytes" << std::endl;
    std::cout << "Usage ratio: " << mmap.GetRatio() * 100 << "%" << std::endl;
    
    /// 6. 扩展数据
    const char* more_data = " This is additional data.";
    mmap.Push(more_data, strlen(more_data) + 1);
    
    /// 7. 同步到磁盘
    /// (内部在Push和Resize时已自动同步，如需立即同步可调用相关方法)
    
    return 0;
}

6.2 异常处理示例

try {
    logger::MMapAux mmap("./log.mmap");
    /// 操作...
} catch (const std::exception& e) {
    std::cerr << "Error: " << e.what() << std::endl;
    /// 错误处理...
}

7. 性能与优化

7.1 性能特性

  • 内存映射减少系统调用次数，提高 I/O 效率
  • 直接内存操作比传统 I/O 操作更快
  • 批量数据操作 (Push) 减少映射重分配次数

7.2 优化建议

  • 预分配足够的初始容量，减少重映射开销
  • 批量写入数据，避免频繁小数据量操作
  • 根据实际数据量调整页大小对齐策略
  • 定期同步数据以保证持久性，同时避免过度同步

7.3 性能测试指标

  • 吞吐量：每秒数据写入量 (MB/s)
  • 延迟：单次数据操作的平均耗时
  • 内存利用率：实际数据大小与映射容量的比率
  • 重映射频率：单位时间内映射重分配次数

8. 故障处理与限制

8.1 已知限制

  • 映射文件大小受系统内存和文件系统限制
  • 不支持文件中间部分的随机修改，主要适用于追加操作
  • 跨平台兼容性依赖底层 utils 模块的实现
  • 大文件映射可能导致内存占用过高

8.2 错误处理指南

  • 检查 IsValid_() 确保映射有效
  • 处理可能的内存分配和映射失败情况
  • 监控 GetRatio() 避免映射空间耗尽
  • 实现数据备份策略防止映射文件损坏

8.3 故障排查流程

  1. 检查文件权限是否允许映射和写入
  2. 验证映射文件是否存在且格式正确
  3. 监控系统内存使用情况
  4. 检查磁盘空间是否充足
  5. 分析重映射频率，优化容量管理策略

9. 技术架构图

9.1 层次架构

从应用层到操作系统层的四层架构，体现了 MMapAux 模块在系统中的定位和交互关系。

+-----------------------------------+     +---------------------------+
|         应用层 (Application)       |<--->|      MMapAux 模块        |
|      (日志系统、数据管理应用等)        |     |  (内存映射文件管理)       |
+-----------------------------------+     +-----------+-------------+
                                              |           |
                                              v           v
+---------------------------+     +---------------------------+     +-------------------+
|    文件工具模块            |<--->|    系统工具模块            |<--->|    操作系统层     |
|  (file_util.h)              |     |  (sys_util.h)              |     |  (内核文件系统)    |
+---------------------------+     +---------------------------+     +-------------------+

9.2 组织架构

分解了 MMapAux 模块的核心组件，包括数据结构 (MmapHeader)、数据操作方法和容量管理策略，以及与外部组件的接口。

+---------------------+     +---------------------+     +---------------------+
|  用户应用程序        |<--->|  MMapAux 类         |<--->|  物理文件系统       |
|  (日志记录等)        |     |  (内存映射管理)      |     |  (磁盘文件)         |
+---------------------+     +----------+----------+     +---------------------+
                            |          |
                            v          v
+---------------------+     +---------------------+     +---------------------+
|  文件操作接口        |<--->|  系统调用接口        |<--->|  内存管理接口       |
|  (文件创建/读写)      |     |  (mmap/munmap等)     |     |  (内存映射控制)     |
+---------------------+     +---------------------+     +---------------------+
                            |
                 +---------+---------+
                 |         |         |
         +-------v-------+-------v-------+
         |               |               |
+----------------+  +----------------+  +----------------+
|  MmapHeader    |  |  数据操作方法    |   |  容量管理策略     |
|  (魔数/大小标记) |  |  (Push/Resize) |  |  (Reserve/Expand)|
+----------------+  +----------------+  +----------------+

9.3 数据流向架构图

直观展示了数据从应用程序写入到最终持久化到磁盘的完整流程，包括各模块在数据流转中的作用。

+-------------------+     +-------------------+     +-------------------+
|  应用程序写入数据     |---->|  MMapAux.Push()   |---->|  内存映射区域       |
|  (void* data, size)|     |  (数据写入逻辑)     |     |  (MmapHeader+Data)|
+-------------------+     +----------+----------+     +----------+----------+
                                              |                      |
                                              v                      v
+-------------------+     +-------------------+     +-------------------+
|  系统工具模块      |<--->|  文件工具模块      |<--->|  物理文件持久化    |
|  (系统调用封装)    |     |  (文件操作封装)    |     |  (磁盘数据写入)    |
+-------------------+     +-------------------+     +-------------------+

9.4 核心类结构架构图

详细展示了 MMapAux 类的成员变量、公共方法和私有方法，以及 MmapHeader 结构体的组成，体现了类的封装性和功能划分。

+-------------------+
|    MMapAux 类     |
+-------------------+
| - file_path_: fpath|
| - handle_: void*   |
| - capacity_: size_t|
+-------------------+
| + MMapAux(fpath)  |
| + Resize(size_t)   |
| + Data(): uint8_t* |
| + Size(): size_t   |
| + Clear()          |
| + Push(void*, size_t)|
| + GetRatio(): double|
+-------------------+
| - Reserve_(size_t) |
| - EnsureCapacity_(size_t)|
| - TryMap_(size_t)  |
| - Unmap_()         |
| - Sync_()          |
| - IsValid_(): bool |
| - Header_(): MmapHeader*|
| - Init_()          |
+-------------------+
|                  |
v                  v
+-------------------+
|   MmapHeader 结构体 |
+-------------------+
| + kMagic: uint32_t |
| - magic: uint32_t  |
| - size: uint32_t   |
+-------------------+
Previous Article
Next Article

发表回复

Your email address will not be published. Required fields are marked *.

*
*

近期文章

近期评论

您尚未收到任何评论。

归档

分类

conviction

要想看到璀璨的日出时刻，就要有跋山涉水的决心和坚毅