C++如何实现一个简单的跨平台内存映射文件访问包装类

在开发跨平台C++应用时，免不了要处理内存映射文件。如果你直接拿 mmap 或 CreateFileMapping 往业务逻辑里塞，很快就会发现这是一个坑——这种做法的代价，远不止多写几行预处理器宏那么简单。

Windows 和 POSIX 的内存映射 API 差异究竟有多大？核心 API 返回值天差地别：mmap 返回的是指针，而 Windows 上你需要先调 CreateFileMapping、再调 MapViewOfFile，两步才能拿到映射地址；错误码体系完全对不上号；文件句柄与描述符的管理方式也截然不同。更微妙的是，某些系统上“只读映射是否允许写入”这个行为的定义都不一致。硬写一堆 #ifdef _WIN32 来强行覆盖，最后得到的只是一个接口破碎、RAII 难以统一的烂摊子，等到需要加共享同步、偏移访问、自动 flush 功能时，维护成本和方案复杂度会指数级上升。

核心设计：用 RAII 封装资源生命周期，接口屏蔽平台细节

解决这类问题，关键不在于“怎么映射”，而在于“谁负责释放资源”。闭着眼睛想一下，你需要在构造时保证：出错了不会泄露任何资源；析构时无论成败都要安全释放；还要支持移动语义，避免资源重复释放。推荐的结构体成员顺序是：handle_or_fd → mapping_handle（仅限于 Windows） → mapped_ptr → size。

• handle_or_fd：Windows 下是 HANDLE，POSIX 下是 int。用一个 void* 存起来，加一个 bool is_windows 做判断——比上模板特化或 std::variant 都轻量，还无心智负担。
• Windows 上 CreateFileMapping 的参数 dwMaximumSizeHigh / dwMaximumSizeLow 必须传非零，才能映射大于 4GB 的文件；而 mmap 直接用 off_t 就能搞定大文件。包装类应当接受一个 uint64_t size，内部再按平台拆分。
• 映射地址这块，建议始终让系统自己选址——mmap 传 addr=0，MapViewOfFile 传 lpBaseAddress=NULL。手动指定地址很容易遇到地址冲突或权限问题，得不偿失。

常见错误：忘记 FlushViewOfFile 或 msync，数据未落盘

内存映射的默认行为是 lazy-write：你改完了数据，如果没调同步函数，程序退出或崩溃时，还没来得及落盘的数据就全丢了。Windows 上尤其需要小心：FlushViewOfFile 必须与 UnmapViewOfFile 配对使用，顺序弄错直接失败；POSIX 下 msync(MS_SYNC) 是阻塞保证落盘，而 MS_ASYNC 只是发起请求，不保证立即写盘。如果业务需要强持久化，你必须显式调用同步函数并检查返回值。

• 不要在析构函数里偷偷调用 msync 或 FlushViewOfFile。析构里没法向用户报告失败，而数据没落盘这种问题用户必须知晓。正确的做法是提供一个 flush() 方法，返回 bool，让调用方在需要持久化时显式处理。
• Linux 下，如果你映射时用了 MAP_SHARED 但文件没开写权限，msync 就会返回 -1 并设置 errno=EBADF。Windows 也一样：CreateFile 时如果没加 GENERIC_WRITE，FlushViewOfFile 直接失败。
• 多进程共享场景下，光靠 flush 远远不够。必须引入命名信号量或文件锁，协调各进程的写入顺序，否则数据竞争依然不可避免。

最小可行示例：只读映射的跨平台构造逻辑

下面这个片段只聚焦“打开文件 + 映射 + 获取指针”，省略了异常处理和移动语义，但已经覆盖了平台的核心分歧点：

class mmap_view {
    void* handle_or_fd_ = nullptr;
    void* mapping_handle_ = nullptr;
    void* mapped_ptr_ = nullptr;
    uint64_t size_ = 0;

public:
    mmap_view(const char* path) {
    #ifdef _WIN32
        HANDLE hFile = CreateFileA(path, GENERIC_READ, FILE_SHARE_READ, nullptr,
                                   OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, nullptr);
        if (hFile == INVALID_HANDLE_VALUE) return;
        LARGE_INTEGER li;
        if (!GetFileSizeEx(hFile, &li)) { CloseHandle(hFile); return; }
        size_ = li.QuadPart;
        HANDLE hMap = CreateFileMappingA(hFile, nullptr, PAGE_READONLY,
                                          (DWORD)(size_ >> 32), (DWORD)size_, nullptr);
        if (!hMap) { CloseHandle(hFile); return; }
        void* ptr = MapViewOfFile(hMap, FILE_MAP_READ, 0, 0, 0);
        if (!ptr) { CloseHandle(hMap); CloseHandle(hFile); return; }
        handle_or_fd_ = hFile;
        mapping_handle_ = hMap;
        mapped_ptr_ = ptr;
    #else
        int fd = open(path, O_RDONLY);
        if (fd == -1) return;
        struct stat st;
        if (fstat(fd, &st) != 0) { close(fd); return; }
        size_ = st.st_size;
        void* ptr = mmap(nullptr, size_, PROT_READ, MAP_PRIVATE, fd, 0);
        if (ptr == MAP_FAILED) { close(fd); return; }
        handle_or_fd_ = reinterpret_cast(static_cast(fd));
        mapped_ptr_ = ptr;
    #endif
    }

    const void* data() const { return mapped_ptr_; }
    uint64_t size() const { return size_; }

    ~mmap_view() {
        if (mapped_ptr_) {
        #ifdef _WIN32
            UnmapViewOfFile(mapped_ptr_);
            CloseHandle(mapping_handle_);
            CloseHandle(reinterpret_cast(handle_or_fd_));
        #else
            munmap(mapped_ptr_, size_);
            close(static_cast(reinterpret_cast(handle_or_fd_)));
        #endif
        }
    }
};

注意那个 handle_or_fd_ 的类型擦除方式——没上 std::variant，是为了不依赖 C++17；没用虚函数，是为了避免 vtable 开销。真正上线时，应该把裸指针换成 std::unique_ptr 来管理，并且把 Windows 的 HANDLE 封装成一个小对象。

最容易被忽略的，是文件打开时的标志。Windows 下你必须加上 FILE_SHARE_READ，否则其他进程打不开同一个文件；而 POSIX 下的 O_RDONLY 默认就允许多次 open。如果你后续还想支持追加写映射，两边的权限位、映射标志（PAGE_READWRITE VS PROT_READ|PROT_WRITE）以及 MAP_SHARED 必须严格匹配。上面的示例，只是一个起点。